@swifty.js/larky 0.0.1-alpha

package/WIRE_PROTOCOL.md

@@ -0,0 +1,1487 @@
+# Wire Protocol
+
+> Generated by `scripts/gen-protocol-doc.ts`. **Do not edit manually.**
+
+## Transport
+
+- TCP loopback `127.0.0.1:5520` (override via `LARKY_HOST` / `LARKY_PORT`)
+- Each message is one `\n`-terminated JSON line (NDJSON)
+- Commands use JSON-RPC 2.0 (client → server); Events use `kind=event` envelope (server → client)
+
+## Commands
+
+All commands are sent as JSON-RPC 2.0 requests. The `type` field inside `params` is used for routing.
+
+### PingCommand
+
+| Field    | Type     | Required |
+| -------- | -------- | -------- |
+| `type`   | `string` | yes      |
+| `client` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "core.ping",
+      "type": "string",
+      "const": "core.ping"
+    },
+    "client": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "client"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "example-1",
+  "method": "core.ping",
+  "params": {
+    "client": "cli/0.0.1"
+  }
+}
+```
+
+### PongResult
+
+| Field            | Type      | Required |
+| ---------------- | --------- | -------- |
+| `server_version` | `string`  | yes      |
+| `uptime_ms`      | `integer` | yes      |
+| `received_at`    | `string`  | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "server_version": {
+      "type": "string"
+    },
+    "uptime_ms": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "received_at": {
+      "type": "string"
+    }
+  },
+  "required": ["server_version", "uptime_ms", "received_at"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "example-1",
+  "result": {
+    "server_version": "0.2.0",
+    "uptime_ms": 12,
+    "received_at": "2026-05-16T10:00:00.001Z"
+  }
+}
+```
+
+### AgentRunCommand
+
+| Field  | Type     | Required |
+| ------ | -------- | -------- |
+| `type` | `string` | yes      |
+| `goal` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "agent.run",
+      "type": "string",
+      "const": "agent.run"
+    },
+    "goal": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "goal"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "example-2",
+  "method": "agent.run",
+  "params": {
+    "goal": "Summarize the main sections of README.md"
+  }
+}
+```
+
+### AgentRunResult
+
+| Field    | Type     | Required |
+| -------- | -------- | -------- |
+| `run_id` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "run_id": {
+      "type": "string"
+    }
+  },
+  "required": ["run_id"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "example-2",
+  "result": {
+    "run_id": "20260516-100000-abc123"
+  }
+}
+```
+
+### EventSubscribeCommand
+
+| Field             | Type     | Required |
+| ----------------- | -------- | -------- | --- |
+| `type`            | `string` | yes      |
+| `topics`          | `array`  | yes      |
+| `scope`           | `string` | yes      |
+| `replay_from_run` | `string  | null`    | yes |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "event.subscribe",
+      "type": "string",
+      "const": "event.subscribe"
+    },
+    "topics": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "scope": {
+      "default": "global",
+      "type": "string"
+    },
+    "replay_from_run": {
+      "default": null,
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": ["type", "topics", "scope", "replay_from_run"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "example-3",
+  "method": "event.subscribe",
+  "params": {
+    "topics": ["run.*", "step.*", "tool.*", "llm.token"],
+    "scope": "global",
+    "replay_from_run": null
+  }
+}
+```
+
+### EventSubscribeResult
+
+| Field             | Type      | Required |
+| ----------------- | --------- | -------- |
+| `subscription_id` | `string`  | yes      |
+| `replayed_count`  | `integer` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "subscription_id": {
+      "type": "string"
+    },
+    "replayed_count": {
+      "default": 0,
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    }
+  },
+  "required": ["subscription_id", "replayed_count"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "example-3",
+  "result": {
+    "subscription_id": "sub-abc123",
+    "replayed_count": 0
+  }
+}
+```
+
+### SessionCreateCommand
+
+| Field   | Type     | Required |
+| ------- | -------- | -------- |
+| `type`  | `string` | yes      |
+| `mode`  | `string` | yes      |
+| `title` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "session.create",
+      "type": "string",
+      "const": "session.create"
+    },
+    "mode": {
+      "default": "chat",
+      "type": "string",
+      "enum": ["one_shot", "chat"]
+    },
+    "title": {
+      "default": "",
+      "type": "string"
+    }
+  },
+  "required": ["type", "mode", "title"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "example-4",
+  "method": "session.create",
+  "params": {
+    "mode": "chat",
+    "title": ""
+  }
+}
+```
+
+### SessionCreateResult
+
+| Field        | Type     | Required |
+| ------------ | -------- | -------- |
+| `session_id` | `string` | yes      |
+| `status`     | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["active", "waiting_for_input", "closed"]
+    }
+  },
+  "required": ["session_id", "status"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "example-4",
+  "result": {
+    "session_id": "session-abc123def456",
+    "status": "active"
+  }
+}
+```
+
+### SessionSendMessageCommand
+
+| Field        | Type     | Required |
+| ------------ | -------- | -------- |
+| `type`       | `string` | yes      |
+| `session_id` | `string` | yes      |
+| `content`    | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "session.send_message",
+      "type": "string",
+      "const": "session.send_message"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "content": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "session_id", "content"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "example-5",
+  "method": "session.sendMessage",
+  "params": {
+    "session_id": "session-abc123def456",
+    "content": "Summarize README.md"
+  }
+}
+```
+
+### SessionSendMessageResult
+
+| Field    | Type     | Required |
+| -------- | -------- | -------- |
+| `run_id` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "run_id": {
+      "type": "string"
+    }
+  },
+  "required": ["run_id"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": "example-5",
+  "result": {
+    "run_id": "20260516-100000-abc123"
+  }
+}
+```
+
+### SessionGetHistoryCommand
+
+| Field        | Type     | Required |
+| ------------ | -------- | -------- |
+| `type`       | `string` | yes      |
+| `session_id` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "session.get_history",
+      "type": "string",
+      "const": "session.get_history"
+    },
+    "session_id": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "session_id"],
+  "additionalProperties": false
+}
+```
+
+### SessionGetHistoryResult
+
+| Field      | Type    | Required |
+| ---------- | ------- | -------- |
+| `messages` | `array` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "messages": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "propertyNames": {
+          "type": "string"
+        },
+        "additionalProperties": {}
+      }
+    }
+  },
+  "required": ["messages"],
+  "additionalProperties": false
+}
+```
+
+### SessionCloseCommand
+
+| Field        | Type     | Required |
+| ------------ | -------- | -------- |
+| `type`       | `string` | yes      |
+| `session_id` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "session.close",
+      "type": "string",
+      "const": "session.close"
+    },
+    "session_id": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "session_id"],
+  "additionalProperties": false
+}
+```
+
+### SessionCloseResult
+
+| Field    | Type     | Required |
+| -------- | -------- | -------- |
+| `status` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["active", "waiting_for_input", "closed"]
+    }
+  },
+  "required": ["status"],
+  "additionalProperties": false
+}
+```
+
+## Server Push
+
+Events pushed from daemon to subscribed clients over the same TCP connection.
+
+### EventPushEnvelope
+
+| Field   | Type     | Required |
+| ------- | -------- | -------- |
+| `kind`  | `string` | yes      |
+| `event` | `object` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "kind": {
+      "default": "event",
+      "type": "string",
+      "const": "event"
+    },
+    "event": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    }
+  },
+  "required": ["kind", "event"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "kind": "event",
+  "event": {
+    "type": "step.started",
+    "run_id": "20260516-100000-abc123",
+    "step": 1,
+    "timestamp": "2026-05-16T10:00:00.001Z"
+  }
+}
+```
+
+## IPC Events
+
+Events sent over the IPC socket (daemon → client).
+
+### CoreStartedEvent
+
+| Field         | Type     | Required |
+| ------------- | -------- | -------- |
+| `type`        | `string` | yes      |
+| `listen_addr` | `string` | yes      |
+| `version`     | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "core.started",
+      "type": "string",
+      "const": "core.started"
+    },
+    "listen_addr": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "listen_addr", "version"],
+  "additionalProperties": false
+}
+```
+
+## Run Events
+
+Events written to `runs/<run_id>/events.jsonl` and forwarded over IPC to subscribed clients.
+
+### RunStartedEvent
+
+| Field       | Type     | Required |
+| ----------- | -------- | -------- |
+| `type`      | `string` | yes      |
+| `run_id`    | `string` | yes      |
+| `goal`      | `string` | yes      |
+| `timestamp` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "run.started",
+      "type": "string",
+      "const": "run.started"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "goal": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "run_id", "goal", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "run.started",
+  "run_id": "20260516-100000-abc123",
+  "goal": "Summarize README.md",
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### RunFinishedEvent
+
+| Field       | Type      | Required |
+| ----------- | --------- | -------- | --- |
+| `type`      | `string`  | yes      |
+| `run_id`    | `string`  | yes      |
+| `status`    | `string`  | yes      |
+| `reason`    | `string   | null`    | yes |
+| `steps`     | `integer` | yes      |
+| `timestamp` | `string`  | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "run.finished",
+      "type": "string",
+      "const": "run.finished"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "status": {
+      "type": "string"
+    },
+    "reason": {
+      "default": null,
+      "anyOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "steps": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "run_id", "status", "reason", "steps", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "run.finished",
+  "run_id": "20260516-100000-abc123",
+  "status": "success",
+  "reason": null,
+  "steps": 2,
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### StepStartedEvent
+
+| Field       | Type      | Required |
+| ----------- | --------- | -------- |
+| `type`      | `string`  | yes      |
+| `run_id`    | `string`  | yes      |
+| `step`      | `integer` | yes      |
+| `timestamp` | `string`  | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "step.started",
+      "type": "string",
+      "const": "step.started"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "step": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "run_id", "step", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "step.started",
+  "run_id": "20260516-100000-abc123",
+  "step": 1,
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### StepFinishedEvent
+
+| Field       | Type      | Required |
+| ----------- | --------- | -------- |
+| `type`      | `string`  | yes      |
+| `run_id`    | `string`  | yes      |
+| `step`      | `integer` | yes      |
+| `timestamp` | `string`  | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "step.finished",
+      "type": "string",
+      "const": "step.finished"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "step": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "run_id", "step", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "step.finished",
+  "run_id": "20260516-100000-abc123",
+  "step": 1,
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### ToolUseStartedEvent
+
+| Field         | Type     | Required |
+| ------------- | -------- | -------- |
+| `type`        | `string` | yes      |
+| `run_id`      | `string` | yes      |
+| `tool_use_id` | `string` | yes      |
+| `tool_name`   | `string` | yes      |
+| `params`      | `object` | yes      |
+| `timestamp`   | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "tool.call_started",
+      "type": "string",
+      "const": "tool.call_started"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "tool_use_id": {
+      "type": "string"
+    },
+    "tool_name": {
+      "type": "string"
+    },
+    "params": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {}
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "run_id", "tool_use_id", "tool_name", "params", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "tool.call_started",
+  "run_id": "20260516-100000-abc123",
+  "tool_use_id": "tool_use_01",
+  "tool_name": "read_file",
+  "params": {
+    "path": "README.md"
+  },
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### ToolUseFinishedEvent
+
+| Field         | Type      | Required |
+| ------------- | --------- | -------- |
+| `type`        | `string`  | yes      |
+| `run_id`      | `string`  | yes      |
+| `tool_use_id` | `string`  | yes      |
+| `tool_name`   | `string`  | yes      |
+| `elapsed_ms`  | `integer` | yes      |
+| `output`      | `string`  | yes      |
+| `timestamp`   | `string`  | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "tool.call_finished",
+      "type": "string",
+      "const": "tool.call_finished"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "tool_use_id": {
+      "type": "string"
+    },
+    "tool_name": {
+      "type": "string"
+    },
+    "elapsed_ms": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "output": {
+      "default": "",
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "run_id", "tool_use_id", "tool_name", "elapsed_ms", "output", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "tool.call_finished",
+  "run_id": "20260516-100000-abc123",
+  "tool_use_id": "tool_use_01",
+  "tool_name": "read_file",
+  "elapsed_ms": 3,
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### ToolUseFailedEvent
+
+| Field           | Type      | Required |
+| --------------- | --------- | -------- |
+| `type`          | `string`  | yes      |
+| `run_id`        | `string`  | yes      |
+| `tool_use_id`   | `string`  | yes      |
+| `tool_name`     | `string`  | yes      |
+| `error_class`   | `string`  | yes      |
+| `error_message` | `string`  | yes      |
+| `elapsed_ms`    | `integer` | yes      |
+| `attempt`       | `integer` | yes      |
+| `timestamp`     | `string`  | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "tool.call_failed",
+      "type": "string",
+      "const": "tool.call_failed"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "tool_use_id": {
+      "type": "string"
+    },
+    "tool_name": {
+      "type": "string"
+    },
+    "error_class": {
+      "type": "string"
+    },
+    "error_message": {
+      "type": "string"
+    },
+    "elapsed_ms": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "attempt": {
+      "default": 1,
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "run_id",
+    "tool_use_id",
+    "tool_name",
+    "error_class",
+    "error_message",
+    "elapsed_ms",
+    "attempt",
+    "timestamp"
+  ],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "tool.call_failed",
+  "run_id": "20260516-100000-abc123",
+  "tool_use_id": "tool_use_02",
+  "tool_name": "read_file",
+  "error_class": "runtime_error",
+  "error_message": "file not found",
+  "elapsed_ms": 1,
+  "attempt": 1,
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### LlmModelSelectedEvent
+
+| Field       | Type     | Required |
+| ----------- | -------- | -------- |
+| `type`      | `string` | yes      |
+| `run_id`    | `string` | yes      |
+| `model`     | `string` | yes      |
+| `strategy`  | `string` | yes      |
+| `timestamp` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "llm.model_selected",
+      "type": "string",
+      "const": "llm.model_selected"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "strategy": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "run_id", "model", "strategy", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "llm.model_selected",
+  "run_id": "20260516-100000-abc123",
+  "model": "claude-sonnet-4-6",
+  "strategy": "static",
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### LlmTokenEvent
+
+| Field       | Type     | Required |
+| ----------- | -------- | -------- |
+| `type`      | `string` | yes      |
+| `run_id`    | `string` | yes      |
+| `token`     | `string` | yes      |
+| `timestamp` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "llm.token",
+      "type": "string",
+      "const": "llm.token"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "token": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "run_id", "token", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "llm.token",
+  "run_id": "20260516-100000-abc123",
+  "token": "The ",
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### LlmUsageEvent
+
+| Field                         | Type      | Required |
+| ----------------------------- | --------- | -------- |
+| `type`                        | `string`  | yes      |
+| `run_id`                      | `string`  | yes      |
+| `input_tokens`                | `integer` | yes      |
+| `output_tokens`               | `integer` | yes      |
+| `cache_read_input_tokens`     | `integer` | yes      |
+| `cache_creation_input_tokens` | `integer` | yes      |
+| `context_percent`             | `number`  | yes      |
+| `timestamp`                   | `string`  | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "llm.usage",
+      "type": "string",
+      "const": "llm.usage"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "input_tokens": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "output_tokens": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "cache_read_input_tokens": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "cache_creation_input_tokens": {
+      "type": "integer",
+      "minimum": -9007199254740991,
+      "maximum": 9007199254740991
+    },
+    "context_percent": {
+      "default": 0,
+      "type": "number"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "type",
+    "run_id",
+    "input_tokens",
+    "output_tokens",
+    "cache_read_input_tokens",
+    "cache_creation_input_tokens",
+    "context_percent",
+    "timestamp"
+  ],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "llm.usage",
+  "run_id": "20260516-100000-abc123",
+  "input_tokens": 512,
+  "output_tokens": 48,
+  "cache_read_input_tokens": 490,
+  "cache_creation_input_tokens": 0,
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### LogLineEvent
+
+| Field       | Type     | Required |
+| ----------- | -------- | -------- |
+| `type`      | `string` | yes      |
+| `run_id`    | `string` | yes      |
+| `level`     | `string` | yes      |
+| `source`    | `string` | yes      |
+| `message`   | `string` | yes      |
+| `timestamp` | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "log.line",
+      "type": "string",
+      "const": "log.line"
+    },
+    "run_id": {
+      "type": "string"
+    },
+    "level": {
+      "type": "string"
+    },
+    "source": {
+      "type": "string"
+    },
+    "message": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "run_id", "level", "source", "message", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "log.line",
+  "run_id": "20260516-100000-abc123",
+  "level": "INFO",
+  "source": "larky.core.loop",
+  "message": "step 1 started",
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+## Session Events
+
+### SessionCreatedEvent
+
+| Field        | Type     | Required |
+| ------------ | -------- | -------- |
+| `type`       | `string` | yes      |
+| `session_id` | `string` | yes      |
+| `mode`       | `string` | yes      |
+| `timestamp`  | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "session.created",
+      "type": "string",
+      "const": "session.created"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "mode": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "session_id", "mode", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "session.created",
+  "session_id": "session-abc123def456",
+  "mode": "chat",
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### SessionMessageReceivedEvent
+
+| Field        | Type     | Required |
+| ------------ | -------- | -------- |
+| `type`       | `string` | yes      |
+| `session_id` | `string` | yes      |
+| `content`    | `string` | yes      |
+| `timestamp`  | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "session.message_received",
+      "type": "string",
+      "const": "session.message_received"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "content": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "session_id", "content", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "session.message_received",
+  "session_id": "session-abc123def456",
+  "content": "Summarize README.md",
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### SessionWaitingForInputEvent
+
+| Field         | Type     | Required |
+| ------------- | -------- | -------- |
+| `type`        | `string` | yes      |
+| `session_id`  | `string` | yes      |
+| `last_run_id` | `string` | yes      |
+| `timestamp`   | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "session.waiting_for_input",
+      "type": "string",
+      "const": "session.waiting_for_input"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "last_run_id": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "session_id", "last_run_id", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "session.waiting_for_input",
+  "session_id": "session-abc123def456",
+  "last_run_id": "20260516-100000-abc123",
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### SessionResumedEvent
+
+| Field        | Type     | Required |
+| ------------ | -------- | -------- |
+| `type`       | `string` | yes      |
+| `session_id` | `string` | yes      |
+| `timestamp`  | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "session.resumed",
+      "type": "string",
+      "const": "session.resumed"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "session_id", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "session.resumed",
+  "session_id": "session-abc123def456",
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+### SessionClosedEvent
+
+| Field        | Type     | Required |
+| ------------ | -------- | -------- |
+| `type`       | `string` | yes      |
+| `session_id` | `string` | yes      |
+| `timestamp`  | `string` | yes      |
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "type": {
+      "default": "session.closed",
+      "type": "string",
+      "const": "session.closed"
+    },
+    "session_id": {
+      "type": "string"
+    },
+    "timestamp": {
+      "type": "string"
+    }
+  },
+  "required": ["type", "session_id", "timestamp"],
+  "additionalProperties": false
+}
+```
+
+**Example:**
+
+```json
+{
+  "type": "session.closed",
+  "session_id": "session-abc123def456",
+  "timestamp": "2026-05-16T10:00:00.001Z"
+}
+```
+
+## Error Codes
+
+| Code   | Name              | Meaning                               |
+| ------ | ----------------- | ------------------------------------- |
+| -32700 | Parse Error       | Invalid JSON received                 |
+| -32600 | Invalid Request   | Missing required JSON-RPC fields      |
+| -32601 | Method Not Found  | Unknown method                        |
+| -32602 | Invalid Params    | Parameter validation failed           |
+| -32603 | Internal Error    | Handler raised an unhandled exception |
+| -32000 | Application Error | e.g. another run already in progress  |