{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://aicc.dev/schemas/0.1/aicc.schema.json",
  "title": "AICC Protocol",
  "description": "Schema for the AI-Controlled Character Protocol (AICC) version 0.1. Defines the message envelope, session manifest, tool definitions, and all message types.",
  "type": "object",
  "oneOf": [
    { "$ref": "#/$defs/sessionInit" },
    { "$ref": "#/$defs/sessionResume" },
    { "$ref": "#/$defs/sessionClose" },
    { "$ref": "#/$defs/manifestRequest" },
    { "$ref": "#/$defs/toolCall" },
    { "$ref": "#/$defs/toolResult" },
    { "$ref": "#/$defs/event" },
    { "$ref": "#/$defs/errorMessage" },
    { "$ref": "#/$defs/heartbeat" }
  ],
  "$defs": {
    "protocolString": {
      "type": "string",
      "const": "aicc/0.1",
      "description": "Protocol version string. Must be exactly 'aicc/0.1' for this version."
    },
    "uuid": {
      "type": "string",
      "format": "uuid",
      "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
    },
    "sessionId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID assigned by the bridge at handshake."
    },
    "messageId": {
      "type": "string",
      "format": "uuid",
      "description": "UUID for this message. Used for correlation."
    },
    "callId": {
      "type": "string",
      "minLength": 1,
      "description": "Agent-assigned id. Echoed in tool_result for correlation."
    },
    "envelope": {
      "type": "object",
      "required": ["protocol", "type", "session_id", "message_id"],
      "properties": {
        "protocol": { "$ref": "#/$defs/protocolString" },
        "type": {
          "type": "string",
          "enum": [
            "session_init",
            "session_resume",
            "session_close",
            "manifest_request",
            "tool_call",
            "tool_result",
            "event",
            "error",
            "heartbeat"
          ]
        },
        "session_id": { "$ref": "#/$defs/sessionId" },
        "message_id": { "$ref": "#/$defs/messageId" }
      },
      "additionalProperties": false
    },
    "tickMode": {
      "type": "string",
      "enum": ["fixed", "event", "hybrid"],
      "description": "How the environment advances over time. fixed: regular intervals. event: only on tool calls or triggers. hybrid: fixed physics but agents may request immediate evaluation."
    },
    "worldKind": {
      "type": "string",
      "enum": ["2d", "3d", "text", "abstract"],
      "description": "Visual / spatial style of the world. Does not constrain tool implementations."
    },
    "modelClass": {
      "type": "string",
      "enum": ["edge_small", "edge_medium", "cloud_medium", "cloud_large"],
      "description": "Declared class of the agent's reasoning model. Advisory only — used by the bridge to tune tick rate and sensor cadence."
    },
    "toolClass": {
      "type": "string",
      "enum": ["sensor", "actuator", "generator"]
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "protocol_mismatch",
        "session_expired",
        "tool_unknown",
        "tool_unavailable",
        "invalid_input",
        "execution_failed",
        "timeout",
        "internal_error"
      ]
    },
    "error": {
      "type": "object",
      "required": ["code", "message", "retryable"],
      "properties": {
        "code": { "$ref": "#/$defs/errorCode" },
        "message": { "type": "string", "minLength": 1 },
        "retryable": { "type": "boolean" }
      },
      "additionalProperties": false
    },
    "meta": {
      "type": "object",
      "description": "Optional environment-supplied metadata for any message that reports state.",
      "properties": {
        "tick": { "type": "integer", "minimum": 0 },
        "latency_ms": { "type": "integer", "minimum": 0 },
        "source": { "type": "string" }
      },
      "additionalProperties": true
    },
    "tool": {
      "type": "object",
      "required": ["id", "class", "description", "input_schema", "output_schema"],
      "properties": {
        "id": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_]*$",
          "description": "Lowercase snake_case identifier, unique within the session."
        },
        "class": { "$ref": "#/$defs/toolClass" },
        "description": {
          "type": "string",
          "minLength": 1,
          "description": "Human-readable description surfaced to the agent. Should make the tool's purpose and any non-obvious side effects clear."
        },
        "input_schema": {
          "type": "object",
          "description": "JSON Schema describing the tool's input object."
        },
        "output_schema": {
          "type": "object",
          "description": "JSON Schema describing the tool's output object."
        },
        "limits": {
          "type": "object",
          "description": "Rate limits and quotas. Enforced by the bridge.",
          "properties": {
            "calls_per_minute": { "type": "integer", "minimum": 1 },
            "calls_per_session": { "type": "integer", "minimum": 1 }
          },
          "additionalProperties": false
        },
        "requires_capability": {
          "type": "string",
          "description": "Capability the agent must hold to invoke this tool."
        },
        "strict_input": {
          "type": "boolean",
          "default": false,
          "description": "If true, the bridge rejects tool calls with input fields not declared in input_schema. Default false (extra fields ignored)."
        }
      },
      "additionalProperties": false
    },
    "capabilities": {
      "type": "object",
      "required": ["sensors", "actuators", "generators"],
      "properties": {
        "sensors": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Reserved capability names enabled for sensors."
        },
        "actuators": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Reserved capability names enabled for actuators."
        },
        "generators": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Reserved capability names enabled for generators."
        }
      },
      "additionalProperties": false
    },
    "modelDecl": {
      "type": "object",
      "required": ["class"],
      "properties": {
        "class": { "$ref": "#/$defs/modelClass" },
        "expected_first_token_ms": {
          "type": "integer",
          "minimum": 0,
          "description": "Advisory budget for time-to-first-token."
        },
        "expected_full_response_ms": {
          "type": "integer",
          "minimum": 0,
          "description": "Advisory budget for a full tool-call decision cycle."
        }
      },
      "additionalProperties": false
    },
    "sessionInit": {
      "type": "object",
      "required": ["protocol", "type", "session_id", "message_id", "tick_rate_hz", "tick_mode", "world", "capabilities", "tools", "agent_model"],
      "properties": {
        "protocol": { "$ref": "#/$defs/protocolString" },
        "type": { "const": "session_init" },
        "session_id": { "$ref": "#/$defs/sessionId" },
        "message_id": { "$ref": "#/$defs/messageId" },
        "tick_rate_hz": {
          "type": "number",
          "exclusiveMinimum": 0,
          "description": "Environment's nominal tick rate in Hertz. Informational; bridges may exceed or undershoot."
        },
        "tick_mode": { "$ref": "#/$defs/tickMode" },
        "world": {
          "type": "object",
          "required": ["name", "kind"],
          "properties": {
            "name": { "type": "string", "minLength": 1 },
            "kind": { "$ref": "#/$defs/worldKind" }
          },
          "additionalProperties": false
        },
        "agent_model": { "$ref": "#/$defs/modelDecl" },
        "capabilities": { "$ref": "#/$defs/capabilities" },
        "tools": {
          "type": "array",
          "items": { "$ref": "#/$defs/tool" },
          "minItems": 0,
          "description": "Full catalog of tools available in this session."
        },
        "event_subscriptions": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Optional. Topics the agent is subscribed to. Empty or omitted means only events emitted as direct responses are sent."
        }
      },
      "additionalProperties": false
    },
    "sessionResume": {
      "type": "object",
      "required": ["protocol", "type", "session_id", "message_id"],
      "properties": {
        "protocol": { "$ref": "#/$defs/protocolString" },
        "type": { "const": "session_resume" },
        "session_id": { "$ref": "#/$defs/sessionId" },
        "message_id": { "$ref": "#/$defs/messageId" }
      },
      "additionalProperties": false
    },
    "sessionClose": {
      "type": "object",
      "required": ["protocol", "type", "session_id", "message_id"],
      "properties": {
        "protocol": { "$ref": "#/$defs/protocolString" },
        "type": { "const": "session_close" },
        "session_id": { "$ref": "#/$defs/sessionId" },
        "message_id": { "$ref": "#/$defs/messageId" },
        "reason": { "type": "string" }
      },
      "additionalProperties": false
    },
    "manifestRequest": {
      "type": "object",
      "required": ["protocol", "type", "session_id", "message_id"],
      "properties": {
        "protocol": { "$ref": "#/$defs/protocolString" },
        "type": { "const": "manifest_request" },
        "session_id": { "$ref": "#/$defs/sessionId" },
        "message_id": { "$ref": "#/$defs/messageId" }
      },
      "additionalProperties": false
    },
    "toolCall": {
      "type": "object",
      "required": ["protocol", "type", "session_id", "message_id", "call_id", "tool", "input"],
      "properties": {
        "protocol": { "$ref": "#/$defs/protocolString" },
        "type": { "const": "tool_call" },
        "session_id": { "$ref": "#/$defs/sessionId" },
        "message_id": { "$ref": "#/$defs/messageId" },
        "call_id": { "$ref": "#/$defs/callId" },
        "tool": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9_]*$",
          "description": "Tool id from the manifest."
        },
        "input": {
          "type": "object",
          "description": "Must validate against the tool's input_schema."
        }
      },
      "additionalProperties": false
    },
    "toolResult": {
      "type": "object",
      "required": ["protocol", "type", "session_id", "message_id", "call_id", "ok"],
      "properties": {
        "protocol": { "$ref": "#/$defs/protocolString" },
        "type": { "const": "tool_result" },
        "session_id": { "$ref": "#/$defs/sessionId" },
        "message_id": { "$ref": "#/$defs/messageId" },
        "call_id": { "$ref": "#/$defs/callId" },
        "ok": { "type": "boolean" },
        "output": {
          "type": "object",
          "description": "Tool output. Must conform to the tool's output_schema when ok is true. Absent or null when ok is false."
        },
        "error": {
          "$ref": "#/$defs/error",
          "description": "Present only when ok is false."
        },
        "meta": { "$ref": "#/$defs/meta" }
      },
      "additionalProperties": false
    },
    "event": {
      "type": "object",
      "required": ["protocol", "type", "session_id", "message_id", "topic", "payload"],
      "properties": {
        "protocol": { "$ref": "#/$defs/protocolString" },
        "type": { "const": "event" },
        "session_id": { "$ref": "#/$defs/sessionId" },
        "message_id": { "$ref": "#/$defs/messageId" },
        "topic": {
          "type": "string",
          "enum": ["tick", "collision", "audio", "state_change", "agent_message"],
          "description": "Event topic. Reserved topics are listed; bridges may define additional topics but agents may not rely on them."
        },
        "payload": {
          "type": "object",
          "description": "Topic-specific payload. Bridges MAY extend with additional fields; agents SHOULD ignore unknown fields."
        },
        "meta": { "$ref": "#/$defs/meta" }
      },
      "additionalProperties": false
    },
    "errorMessage": {
      "type": "object",
      "required": ["protocol", "type", "session_id", "message_id", "error"],
      "properties": {
        "protocol": { "$ref": "#/$defs/protocolString" },
        "type": { "const": "error" },
        "session_id": { "$ref": "#/$defs/sessionId" },
        "message_id": { "$ref": "#/$defs/messageId" },
        "error": { "$ref": "#/$defs/error" }
      },
      "additionalProperties": false
    },
    "heartbeat": {
      "type": "object",
      "required": ["protocol", "type", "session_id", "message_id"],
      "properties": {
        "protocol": { "$ref": "#/$defs/protocolString" },
        "type": { "const": "heartbeat" },
        "session_id": { "$ref": "#/$defs/sessionId" },
        "message_id": { "$ref": "#/$defs/messageId" },
        "manifest_update": {
          "type": "object",
          "description": "If present, replaces the current manifest (e.g. capability changes). Same shape as session_init minus session_id and message_id."
        }
      },
      "additionalProperties": false
    }
  }
}