{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Iris x Hermes wire protocol",
  "description": "Machine-readable description of the JSON frames exchanged over the gateway WebSocket. Mirrors gateway-plugin/protocol.py and docs/04-wire-protocol.md. Media travels as binary WS frames referenced by header/end frames.",
  "protocol_version": 1,
  "envelope": {
    "type": "object",
    "required": ["v", "type"],
    "properties": {
      "v": { "type": "integer", "const": 1, "description": "Protocol version." },
      "id": { "type": "integer", "description": "Request id; present on requests and their responses/acks. Absent on pure events." },
      "type": { "type": "string", "description": "Frame type (see frame_types)." },
      "chat_id": { "type": "string", "description": "Optional chat scope (e.g. android:default, android:chan_7)." },
      "thread_id": { "type": "string", "description": "Optional thread scope within a chat_id." },
      "payload": { "type": "object", "description": "Type-specific payload." }
    }
  },
  "frame_types": {
    "server_to_app": {
      "hello.ack": {
        "description": "Pairing succeeded.",
        "payload": {
          "server_caps": { "type": "object", "properties": { "streaming": {"type":"boolean"}, "reasoning": {"type":"boolean"}, "tools": {"type":"boolean"}, "media": {"type":"boolean"}, "search": {"type":"boolean"}, "push": {"type":"string","enum":["fcm","ntfy","none"]}, "pickers": {"type":"boolean"} } },
          "sync_cursor": { "type": "integer" },
          "channels": { "type": "array", "items": { "$ref": "#/definitions/channel" } }
        }
      },
      "message": {
        "description": "A final / standalone message.",
        "payload": {
          "message_id": { "type": "string" },
          "role": { "type": "string", "enum": ["user", "assistant", "system", "cron"] },
          "text": { "type": "string" },
          "reasoning": { "type": "string", "description": "Optional; render ABOVE text." },
          "media": { "type": "array", "items": { "$ref": "#/definitions/media_ref" } },
          "reply_to": { "type": "string" },
          "model": { "type": "string" },
          "tokens": { "type": "integer" },
          "ts": { "type": "integer", "description": "epoch millis" }
        }
      },
      "message.start": { "payload": { "message_id": { "type": "string" }, "role": { "type": "string" } } },
      "message.update": { "payload": { "message_id": { "type": "string" }, "text": { "type": "string", "description": "Full current text (app replaces)." } } },
      "message.stop": { "payload": { "message_id": { "type": "string" }, "final_text": { "type": "string" }, "reasoning": { "type": "string" }, "model": { "type": "string" }, "tokens": { "type": "integer" } } },
      "commentary": { "description": "Intermediate assistant beat.", "payload": { "message_id": { "type": "string" }, "text": { "type": "string" } } },
      "tool.start": { "payload": { "index": { "type": "integer" }, "name": { "type": "string" }, "preview": { "type": "string" }, "args": { "type": "object" } } },
      "tool.progress": { "payload": { "index": { "type": "integer" }, "name": { "type": "string" }, "note": { "type": "string" } } },
      "tool.end": { "payload": { "index": { "type": "integer" }, "name": { "type": "string" }, "ok": { "type": "boolean" }, "duration": { "type": "number" }, "output_preview": { "type": "string" } } },
      "typing": { "payload": { "on": { "type": "boolean" } } },
      "notification": { "payload": { "kind": { "type": "string", "enum": ["channel_renamed", "channel_created", "cron", "approval", "clarify", "generic"] }, "title": { "type": "string" }, "body": { "type": "string" }, "ts": { "type": "integer" } } },
      "picker.model": { "payload": { "picker_id": { "type": "string" }, "current_model": { "type": "string" }, "current_provider": { "type": "string" }, "providers": { "type": "array", "items": { "type": "object", "properties": { "id": {"type":"string"}, "label": {"type":"string"}, "models": { "type": "array", "items": { "type": "object", "properties": { "id": {"type":"string"}, "label": {"type":"string"} } } } } } } } },
      "picker.choice": { "payload": { "picker_id": { "type": "string" }, "title": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "value": {"type":"string"}, "label": {"type":"string"}, "is_current": {"type":"boolean"} } } } } },
      "picker.clarify": { "payload": { "picker_id": { "type": "string" }, "question": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object" } } } },
      "picker.approval": { "payload": { "picker_id": { "type": "string" }, "command": { "type": "string" }, "description": { "type": "string" } } },
      "picker.confirm": { "payload": { "picker_id": { "type": "string" }, "title": { "type": "string" }, "message": { "type": "string" } } },
      "channel.list": { "payload": { "channels": { "type": "array", "items": { "$ref": "#/definitions/channel" } } } },
      "channel.created": { "payload": { "$ref": "#/definitions/channel" } },
      "channel.renamed": { "payload": { "chat_id": { "type": "string" }, "name": { "type": "string" } } },
      "channel.deleted": { "payload": { "chat_id": { "type": "string" } } },
      "history": { "description": "Response to history request; page of messages oldest→newest.", "payload": { "messages": { "type": "array", "items": { "type": "object", "properties": { "message_id": {"type":"string"}, "role": {"type":"string"}, "text": {"type":"string"}, "reasoning": {"type":"string"}, "model": {"type":"string"}, "tokens": {"type":"integer"}, "ts": {"type":"integer"} } } }, "has_more": { "type": "boolean" }, "oldest_message_id": { "type": "string" } } },
      "commands.catalog": { "description": "Full slash-command catalog.", "payload": { "commands": { "type": "array", "items": { "type": "object", "properties": { "name": {"type":"string"}, "description": {"type":"string"}, "args_hint": {"type":"string"}, "category": {"type":"string"} } } } } },
      "commands.complete": { "description": "Autocomplete matches for a typed prefix.", "payload": { "prefix": { "type": "string" }, "matches": { "type": "array", "items": { "type": "object", "properties": { "name": {"type":"string"}, "description": {"type":"string"}, "args_hint": {"type":"string"} } } } } },
      "agent.busy": { "description": "Agent is processing; app shows thinking indicator.", "payload": { "reason": { "type": "string", "enum": ["processing", "tool", "waiting_input", "cron"] } } },
      "agent.idle": { "description": "Agent turn complete; clear thinking indicator.", "payload": {} },
      "search.results": { "payload": { "query": { "type": "string" }, "scope": { "type": "string", "enum": ["all", "chat"] }, "hits": { "type": "array", "items": { "type": "object", "properties": { "message_id": {"type":"string"}, "chat_id": {"type":"string"}, "thread_id": {"type":["string","null"]}, "role": {"type":"string"}, "snippet": {"type":"string"}, "ts": {"type":"integer"} } } } } },
      "media.offer": { "description": "Agent-sent media available; app pulls bytes.", "payload": { "$ref": "#/definitions/media_ref" } },
      "status": { "payload": { "state": { "type": "string", "enum": ["online", "restarting", "degraded"] }, "session": { "type": "object" } } },
      "error": { "payload": { "code": { "type": "string", "enum": ["auth", "not_found", "rate_limited", "media_too_large", "unsupported", "internal"] }, "message": { "type": "string" } } },
      "pong": { "payload": { "ts": { "type": "integer" } } },
      "sync.done": { "payload": { "cursor": { "type": "integer" } } },
      "media.pull.end": { "payload": { "ok": { "type": "boolean" } } }
    },
    "app_to_server": {
      "hello": { "description": "First frame; auth + caps.", "payload": { "token": { "type": "string" }, "device_id": { "type": "string" }, "device_name": { "type": "string" }, "caps": { "type": "object", "properties": { "min_protocol": {"type":"integer"}, "media": {"type":"boolean"}, "push": {"type":"string"} } }, "fcm_token": { "type": "string" }, "ntfy_topic": { "type": "string" } } },
      "message.send": { "payload": { "text": { "type": "string" }, "reply_to": { "type": "string" }, "media_refs": { "type": "array", "items": { "type": "string" } } } },
      "media.upload.start": { "payload": { "media_ref": { "type": "string" }, "kind": { "$ref": "#/definitions/kind" }, "mime": { "type": "string" }, "size": { "type": "integer" }, "filename": { "type": "string" } } },
      "media.upload.end": { "payload": { "media_ref": { "type": "string" }, "sha256": { "type": "string" } } },
      "media.pull": { "payload": { "media_id": { "type": "string" } } },
      "picker.select": { "payload": { "picker_id": { "type": "string" }, "value": { "type": "string" } } },
      "channel.create": { "payload": { "name": { "type": "string" }, "kind": { "type": "string", "enum": ["channel", "thread"] }, "parent_chat_id": { "type": ["string", "null"] } } },
      "channel.rename": { "payload": { "name": { "type": "string" } } },
      "channel.set_default": { "payload": {} },
      "channel.delete": { "payload": {} },
      "search": { "payload": { "query": { "type": "string" }, "scope": { "type": "string", "enum": ["all", "chat"] }, "chat_id": { "type": "string" }, "thread_id": { "type": "string" } } },
      "history": { "description": "Load a page of messages (initial open / scroll-up).", "payload": { "before_message_id": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } } },
      "commands.catalog": { "description": "Fetch full slash-command catalog.", "payload": {} },
      "commands.complete": { "description": "Autocomplete for typed /prefix.", "payload": { "prefix": { "type": "string" } } },
      "agent.stop": { "description": "Abort current agent turn.", "payload": {} },
      "agent.steer": { "description": "Inject steering message mid-turn.", "payload": { "text": { "type": "string" } } },
      "read.receipt": { "description": "User viewed message; server stores + broadcasts to other devices.", "payload": { "chat_id": { "type": "string" }, "message_id": { "type": "string" } } },
      "sync": { "description": "Reconnect catch-up; replays undelivered outbox frames only (not full history).", "payload": { "cursor": { "type": "integer" } } },
      "fcm.register": { "payload": { "fcm_token": { "type": "string" }, "ntfy_topic": { "type": "string" } } },
      "ping": { "payload": { "ts": { "type": "integer" } } }
    }
  },
  "definitions": {
    "kind": { "type": "string", "enum": ["image", "audio", "video", "document", "voice"] },
    "channel": { "type": "object", "properties": { "chat_id": {"type":"string"}, "name": {"type":"string"}, "kind": {"type":"string","enum":["default","channel","thread"]}, "parent_chat_id": {"type":["string","null"]}, "is_default": {"type":"boolean"} } },
    "media_ref": { "type": "object", "properties": { "media_id": {"type":"string"}, "kind": { "$ref": "#/definitions/kind" }, "mime": {"type":"string"}, "size": {"type":"integer"}, "filename": {"type":"string"} } }
  },
  "reliability": {
    "ordering": "Per-connection (TCP/WS). message.update for a message_id is monotonic; app may coalesce to latest.",
    "never_dropped": ["message", "message.stop", "tool.end", "notification", "picker.*", "channel.*", "agent.busy", "agent.idle", "history", "commands.catalog", "commands.complete", "search.results", "error"],
    "coalescable_under_backpressure": ["message.update", "tool.progress"],
    "offline": "Undelivered frames go to the outbox; replayed by sync. Terminal frames always outboxed."
  }
}