Input and Output Surfaces

Purpose

Surface 2 (Input Schema) declares what the agent accepts as input; Surface 3 (Output Schema) declares what it produces. Together they enable validation, replay, and pattern detection. Without structured schemas, the kernel cannot validate invocations, the Inspector Pipeline cannot compare similar invocations across cells, replay-by-input-hash is impossible, and the cognitive layer (Surfaces 8 and 9) cannot be enforced.

Surface 2 - Input Schema: Required Fields

input_schema:
  format: json_schema|protobuf|openapi
  schema: <schema definition>
  unstructured_input: boolean        # True if agent accepts free-form prompts
  unstructured_input_max_chars: int  # Required if unstructured_input is true

Validation rules: the schema must be valid in the declared format; if unstructured_input is true, unstructured_input_max_chars must be declared; the kernel validates incoming requests against the schema before invoking the agent; requests that violate the schema are rejected and the rejection is recorded in telemetry; and schemas with additionalProperties: true at top level are flagged as too permissive.

input_schema:
  format: json_schema
  schema:
    type: object
    required:
      - feature_description
      - target_codebase
    properties:
      feature_description:
        type: string
        minLength: 50
        maxLength: 5000
      target_codebase:
        type: string
        pattern: "^[a-z0-9-]+$"
      style_preferences:
        type: object
        additionalProperties: true
  unstructured_input: false

Surface 3 - Output Schema: Required Fields

output_schema:
  format: json_schema|protobuf|openapi
  schema: <schema definition>
  contains_unstructured: boolean     # True if output contains free-form content
  unstructured_fields: [string]      # Names of fields that are free-form

Validation rules: outputs that violate the schema are flagged (rejected or returned with a warning is a cell-level policy); unstructured fields must still be wrapped in a structured envelope with metadata; the output schema must always include placeholders for Surface 8 (confidence) and Surface 9 (decision trace) - this is non-negotiable; and empty outputs are not permitted, agents must always produce at least the confidence and trace metadata even if the substantive output is empty.

output_schema:
  format: json_schema
  schema:
    type: object
    required:
      - specification
      - confidence
      - decision_trace
    properties:
      specification:
        type: object
        # ... detailed spec schema
      confidence:
        $ref: kernel://schemas/confidence/v2
      decision_trace:
        $ref: kernel://schemas/decision_trace/v2
  contains_unstructured: true
  unstructured_fields:
    - specification.user_stories
    - specification.acceptance_criteria

Anti-Patterns

• Agents that accept entirely free-form input without bounds - the kernel cannot validate or pattern-detect
• Schemas that are excessively permissive (everything optional, all types allowed) - defeats the purpose of declaration
• Schemas that drift across versions without major version bumps - breaks downstream consumers
• Outputs without confidence and decision trace fields - rejected at agent registration
• Free-form outputs without any structured envelope - even unstructured content needs metadata

Why It Matters

Structured input is what makes the rest of the model possible: validation catches malformed inputs before they reach the agent; pattern detection lets the Inspector Pipeline compare similar invocations across cells; replay-by-input-hash requires deterministic input serialization; and agents with structured inputs are testable. Agents that accept 'anything as a string' cannot be governed effectively.

On the output side, the requirement that confidence and decision trace are always present is the structural mechanism that makes the cognitive layer work. If they were optional, they would be omitted under deadline pressure, and the entire learning system would degrade. KCC's discipline: the kernel will not accept an agent declaration whose output schema omits the cognitive layer fields.