Skip to content

session-manager

v1.1.0

Durable, reactive, branching store of typed conversation entries with six observable session event functions.

license: Apache-2.0chatconversationhistorysession

Install

bash
iii trigger compose::add worker=session-manager

Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.

Agent-ready brief for v1.1.0
Install, config, dependencies, readme, skills and API reference, all in one place. Fetch as agent-context.md for an LLM to consume.
The same content rendered as discrete blocks below is exposed as a single markdown document at /registry/workers/session-manager.md. Paste it into an LLM prompt or pipe it through curl from a worker.

Install

iii trigger compose::add worker=session-manager@1.1.0

Dependencies

Dependency · 1Version

Readme

README.md

session-manager

Durable, reactive store for conversations. A session is an append-only log of typed message entries (user, assistant, function_result, custom — with optional fork branches) plus a small metadata record (title, description, coarse status, app-defined metadata). Any worker or client appends and reads over the bus; every mutation calls one of six event functions that consumers observe, so a chat UI, bot, or dashboard renders live with no polling and no separate publish call. It runs no agent logic — it is the conversation database the harness family drives, and it is independently useful as a real-time chat store for any app.

Install

iii call compose::add worker=session-manager

iii call compose::add resolves the worker and its dependencies, writes exact declarations to worker-compose.yaml, and reconciles the Compose project.

Quickstart

Create a session, append a message, read the transcript back:

use iii_sdk::{register_worker, CallRequest, InitOptions};
use serde_json::json;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let iii = register_worker("ws://localhost:49134", InitOptions::default());

    let created = iii
        .call(CallRequest::new(
            "session::create",
            json!({ "title": "Weather question", "metadata": { "owner": "u_1" } }),
        ))
        .await?;
    let session_id = created["session_id"].as_str().unwrap().to_string();

    iii.call(CallRequest::new(
        "session::append",
        json!({
            "session_id": session_id,
            "message": {
                "role": "user",
                "content": [{ "type": "text", "text": "What's the weather?" }],
                "timestamp": 1717800000000_i64
            }
        }),
    ))
    .await?;

    let transcript = iii
        .call(CallRequest::new(
            "session::messages",
            json!({ "session_id": session_id }),
        ))
        .await?;

    println!("{transcript:#?}");
    Ok(())
}

To render live instead of polling, register a handler function and observe an event function with it:

use iii_sdk::{Deliver, Error, RegisterFunction, Source};
use serde_json::{json, Value};

iii.register_function(
    "my-ui::on-message-updated",
    RegisterFunction::new_async(|event: Value| async move {
        // full updated message + monotonic revision; keep the highest
        println!("{} rev {}", event["entry_id"], event["revision"]);
        Ok::<_, Error>(json!({ "ok": true }))
    }),
);

// one session's assistant messages, as they stream
iii.observe(
    Source::function("session::on-message-updated")
        .filters(json!({
            "input.session_id": { "$eq": session_id },
            "input.message.role": { "$in": ["assistant"] },
        }))
        .deliver(Deliver::Output),
    "my-ui::on-message-updated",
);

Streaming an assistant reply uses the same primitives: append an (initially empty) assistant message, then call session::update-message as tokens arrive — each update calls session::on-message-updated with an incremented revision.

The full function surface (21 session::* functions: lifecycle, messages, branching/fork, attachments) is documented in the spec and on each function's registered schema — see iii call engine::workers::info name=session-manager. session::messages items carry the entry origin (hook annotations — e.g. which memory bank fed a generate), so consumers can render provenance without a second lookup.

Sessions can be mentioned in a chat as @session(id="<session_id>") (see crates/mention-contract). Two internal functions provide it: session::mention::search ranks sessions by title words or id (top-level chats before sub-agents, e2e sessions and the asking session left out) and session::mention::get returns the pill, preview card and agent summary — never the parked draft — and declares the provider, whose details call is session::get.

Event functions

The worker hosts one function per kind of mutation. Each is private (only this worker calls it), and its handler returns the event it is called with, so an observer receives the event. The worker calls a function only while something observes it. None takes args (an observer that passes args gets INVALID_ARGS from the engine); observers select events with filters on the event's fields. iii delivers each call to every observer whose filters match.

Every event carries session_metadata: the session's SessionMeta.metadata (the tenancy hook, e.g. { "owner": "u_1" }) as of the mutation, omitted when the session has none. session::on-meta-updated carries the metadata after the update, session::on-deleted the metadata the session had before deletion.

Function Args Called when Event (what observers receive)
session::on-created none; filter on input.session_id, input.session_metadata.<key> A session is created (create / ensure / fork) { session_id, title, description, status, forked_from?, created_at, session_metadata? }
session::on-message-added none; filter on input.session_id, input.message.role, input.session_metadata.<key> An entry is appended { session_id, entry_id, parent_id, message?, custom?, origin?, timestamp, session_metadata? }
session::on-message-updated none; filter as session::on-message-added A message's content changes (streaming deltas) { session_id, entry_id, message, revision, origin?, timestamp, session_metadata? }
session::on-status-changed none; filter on input.session_id, input.session_metadata.<key> Status moves between idle/working/done/error, or its reason changes { session_id, status, previous_status, status_reason?, timestamp, session_metadata? }
session::on-meta-updated none; filter as session::on-status-changed Title/description/metadata change { session_id, title, description, metadata?, timestamp, session_metadata? }
session::on-deleted none; filter as session::on-status-changed A session and its entries are removed { session_id, timestamp, session_metadata? }
session::store::on-events none Internal, fs-mode instances only: once per event, for bridged instances (see Storage adapters) { function_id, payload, session_metadata? }: function_id names the event function, payload is its event without session_metadata

A custom entry (kind: "custom") carries custom and no message, so a filter on input.message.role never matches it; a custom message has role custom.

// one session's transcript, every role
iii.observe(
    Source::function("session::on-message-added")
        .filters(json!({ "input.session_id": { "$eq": session_id } }))
        .deliver(Deliver::Output),
    "my-ui::on-message-added",
);

// one tenant's sessions appearing and going away
iii.observe(
    Source::function("session::on-created")
        .filters(json!({ "input.session_metadata.owner": { "$eq": "u_1" } }))
        .deliver(Deliver::Output),
    "my-ui::on-session-created",
);
iii.observe(
    Source::function("session::on-deleted")
        .filters(json!({ "input.session_metadata.owner": { "$eq": "u_1" } }))
        .deliver(Deliver::Output),
    "my-ui::on-session-deleted",
);

// every status change (a spinner per session)
iii.observe(
    Source::function("session::on-status-changed").deliver(Deliver::Output),
    "my-ui::on-status-changed",
);

Calls are fire-and-forget and unordered, and an event can be lost (the mutation is durable either way). A reload replays the current state, so the same entry can arrive again. Reconcile message updates by revision (keep the highest) and transcript order by the parent chain, never by arrival order; recover with a read-back (session::messages, session::get).

What the worker observes

  • configuration::on-updated, filtered to the configuration:updated events of its own entry (input.id, input.event_type), with session::on-config-change as the target, which re-reads the entry and applies it.
  • On a bridged instance, the main instance's session::store::on-events, with a relay function it registers on the main's engine (session::bridge::recv::<uuid>) as the target.

Storage adapters

Two adapters, selected by an adapter block (a name plus a nested config):

  • fs (default) — one append-only JSONL file per session under data_dir (<encoded_session_id>.jsonl): typed meta / entry / leaf records, replayed last-wins on startup, file removed on session delete. This is the durable, single-instance setup. An append is one append record (entry, leaf and metadata together) with a commit marker per committed entry; a build from before these record types skips them as malformed lines, so do not roll back to an older session-manager once this version has written to a data_dir: the entries appended since would not replay, and older metadata would return without an error.
  • bridge — this instance keeps all domain logic (idempotency, revisions, branching, locks) but stores through a main instance running its own session-manager (adapter name: fs) on another iii engine, via the internal session::store::* protocol.

Event propagation in a bridge topology: the main is the single fan-out point. A bridged instance publishes each mutation's events to the main (session::store::publish-events); the main calls its own event functions and, once per event, its internal session::store::on-events with an envelope, which every attached bridged instance observes; each bridge calls its local event functions with the envelope's event, and iii applies its local observers' filters. With several bridged instances attached to one main, a mutation made anywhere calls every instance's event functions once. (Consequence: an originator's own observers receive events after the round trip through the main — the same fire-and-forget, unordered delivery as on any instance.)

The session::store::* functions are deployment plumbing served only by fs-mode instances — deny them to agents like every other mutating surface.

Configuration

Runtime settings live in the configuration worker under id session-manager. At startup the worker registers its JSON Schema, fetches the live, env-expanded value via configuration::get, and observes configuration::on-updated (see What the worker observes) so changes apply without a restart. Persisted values default to ./data/configuration/session-manager.yaml (the configuration worker's fs adapter) — edit that file directly or call configuration::set and the change propagates. adapter is an adjacently tagged enum, so the console's worker-config form renders a variant picker (fs / bridge) and only the selected adapter's config fields (data_dir, or url / timeout_ms), plus the list limits — all as editable inputs.

adapter:
  name: fs                                   # fs | bridge
  config:
    data_dir: data/session-manager           # relative to III_COMPOSE_DIR

# adapter:
#   name: bridge
#   config:
#     url: ws://127.0.0.1:49134   # main engine WebSocket URL
#     timeout_ms: 5000            # per store/publish call timeout

default_list_limit: 50   # page size when list/messages omit `limit`
max_list_limit: 500      # hard cap on any requested `limit`

Reload policy. Every field hot-reloads on configuration:updated, no restart required. default_list_limit / max_list_limit swap the shared snapshot the list/messages calls read. A change to the adapter (fs↔bridge, a new data_dir, a bridge url/timeout) rebuilds the store and event plumbing and swaps it in atomically; the new store's current state is then replayed through the session::on-* event functions so open observers (the console sidebar/transcript, the harness, ...) stay live without a refetch. A reload that cannot be built (e.g. an unreadable data_dir, or a self-referential bridge url) keeps the previous runtime (last-good) and is surfaced by session::config-status. An invalid bridge config is still rejected at parse time, and at boot a misconfigured bridge is fatal (it never silently falls back to a local fs store). Switching data_dir or bridge url changes the backing storage immediately and does not migrate existing sessions.

First boot. When no value is stored yet for id session-manager, the worker registers WorkerConfig::default() as initial_value. Optionally pass --config <path> to seed from a YAML file instead (one-time, never overwrites an existing stored value). ${VAR:default} placeholders in stored values are expanded by the configuration worker on every read.

Local development & testing

cargo run --release -- --url ws://127.0.0.1:49134
cargo test                       # unit + manifest + BDD (engine scenarios self-skip)
cargo test --test bdd -- --tags @pure    # no engine required
III_ENGINE_WS_URL=ws://127.0.0.1:<port> cargo test --test bdd -- --tags @engine
                                 # requires a running `iii` with no session-manager

The @engine scenarios register their own session-manager surface on the engine they reach (III_ENGINE_WS_URL, default ws://127.0.0.1:49134), so they skip an engine that already runs session-manager, or whose workers or functions cannot be listed, rather than write into its store: point them at a bare engine on a free port. The check is repeated before every @engine scenario (a session-manager that takes the ids after an engine restart skips the rest of the run); a takeover in the middle of a scenario can still reach the rest of that scenario.

The BDD suite under tests/features/ is the behavioural contract: @pure scenarios drive the production handlers against a real fs store over a tempdir with deterministic ids/clock (including restart-replay scenarios); @engine scenarios drive the same code over a live engine, including JSONL persistence readbacks, real observers with filters, and full bridge propagation (two bridged instances

  • the main, asserting who received what, exactly once).

Architecture documentation

Deep documentation lives in architecture/: architecture/integration.md is the self-contained handoff contract for workers that build on this one (functions, events, filters, error codes, patterns, topologies); architecture/internals.md is the maintainer deep-dive (module map, invariants, storage formats, event pipeline, testing architecture).

API reference (JSON)

agent-api-reference.json
{
  "functions": [
    {
      "description": "Append one entry (idempotent on entry_id); calls session::on-message-added.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::append",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "CustomPayload": {
            "description": "Bookkeeping payload of a `kind: \"custom\"` session entry.",
            "properties": {
              "custom_type": {
                "description": "App-defined discriminator (e.g. `\"compaction\"`).",
                "type": "string"
              },
              "data": {
                "default": null,
                "description": "Opaque app data."
              }
            },
            "required": [
              "custom_type"
            ],
            "type": "object"
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "properties": {
          "custom": {
            "anyOf": [
              {
                "$ref": "#/definitions/CustomPayload"
              },
              {
                "type": "null"
              }
            ],
            "description": "Append a bookkeeping `kind: \"custom\"` entry instead of a message (e.g. the harness's compaction record). Custom entries do not count toward `message_count` and are only returned by `session::messages` when `include_custom` is set."
          },
          "entry_id": {
            "description": "Caller-supplied id for idempotent appends: appending an id that already exists is a no-op — the existing entry is returned and no event fires.",
            "type": [
              "string",
              "null"
            ]
          },
          "message": {
            "anyOf": [
              {
                "$ref": "#/definitions/AgentMessage"
              },
              {
                "type": "null"
              }
            ],
            "description": "The message to append (a `kind: \"message\"` entry). Exactly one of `message` / `custom` must be supplied."
          },
          "origin": {
            "additionalProperties": true,
            "description": "Opaque correlation (e.g. `{ \"turn_id\": ... }`), echoed on events.",
            "type": [
              "object",
              "null"
            ]
          },
          "parent_id": {
            "description": "Override the parent (default: active leaf). Appending always moves the active leaf to the new entry.",
            "type": [
              "string",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "AppendRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "entry_id": {
            "type": "string"
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "entry_id",
          "timestamp"
        ],
        "title": "AppendResponse",
        "type": "object"
      }
    },
    {
      "description": "Append several message entries in order; calls session::on-message-added per entry.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::append-many",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "properties": {
          "messages": {
            "description": "Messages appended in order, each chained to the previous one. Not idempotent — use `session::append` with `entry_id` where redelivery is possible.",
            "items": {
              "$ref": "#/definitions/AgentMessage"
            },
            "type": "array"
          },
          "origin": {
            "additionalProperties": true,
            "description": "Opaque correlation echoed on every emitted event.",
            "type": [
              "object",
              "null"
            ]
          },
          "parent_id": {
            "description": "Parent of the first appended entry (default: active leaf).",
            "type": [
              "string",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "messages",
          "session_id"
        ],
        "title": "AppendManyRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "entry_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "last_entry_id": {
            "type": "string"
          }
        },
        "required": [
          "entry_ids",
          "last_entry_id"
        ],
        "title": "AppendManyResponse",
        "type": "object"
      }
    },
    {
      "description": "Report the last configuration hot-reload outcome: last_outcome (applied|rejected), last_error, and rejected_reloads (count since boot). A rejected outcome or non-zero count means a stored config was refused and the active storage adapter diverged from the central store. Takes no arguments.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::config-status",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Input of `session::config-status` — takes no arguments. A struct (not `Value`) keeps the request schema concrete; the engine-injected `_caller_worker_id` (and any other unknown field) is ignored.",
        "title": "ConfigStatusRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "ReloadOutcome": {
            "description": "Outcome of the most recent hot-reload attempt, exposed via `session::config-status`.",
            "oneOf": [
              {
                "description": "The live runtime reflects the most recent configuration the worker loaded.",
                "enum": [
                  "applied"
                ],
                "type": "string"
              },
              {
                "description": "The most recent `configuration:updated` delivered a value the worker could NOT build (e.g. an unreadable `data_dir` or a self-referential bridge url); the previous runtime is still active and the central store has DIVERGED from what this worker is running.",
                "enum": [
                  "rejected"
                ],
                "type": "string"
              }
            ]
          }
        },
        "description": "Operator-visible hot-reload status. `rejected_reloads > 0` (or `last_outcome == Rejected`) means a stored config was refused and the worker is running an older adapter than the central store — actionable divergence.",
        "properties": {
          "last_error": {
            "description": "Build error from the most recent rejected reload (why it was refused).",
            "type": [
              "string",
              "null"
            ]
          },
          "last_outcome": {
            "$ref": "#/definitions/ReloadOutcome"
          },
          "rejected_reloads": {
            "description": "Cumulative count of rejected reloads since boot (never reset).",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "last_outcome",
          "rejected_reloads"
        ],
        "title": "ReloadStatus",
        "type": "object"
      }
    },
    {
      "description": "Create a session at status idle; calls session::on-created.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::create",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          }
        },
        "properties": {
          "description": {
            "description": "Session description. Default \"\".",
            "type": [
              "string",
              "null"
            ]
          },
          "kind": {
            "anyOf": [
              {
                "$ref": "#/definitions/SessionKind"
              },
              {
                "type": "null"
              }
            ],
            "description": "Session kind. Default `user`."
          },
          "metadata": {
            "additionalProperties": true,
            "description": "App-defined metadata persisted onto `SessionMeta` — the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
            "type": [
              "object",
              "null"
            ]
          },
          "title": {
            "description": "Session title; may be refined later with `session::set-meta`. Default \"\".",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "CreateRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "draft": {
                "description": "Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "draft_attachments": {
                "description": "Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.",
                "items": {
                  "$ref": "#/definitions/AttachmentMeta"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "allOf": [
                  {
                    "$ref": "#/definitions/SessionKind"
                  }
                ],
                "default": "user",
                "description": "Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`."
              },
              "message_count": {
                "description": "Number of `kind: \"message\"` entries (custom entries are bookkeeping and not counted).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "metadata": {
                "additionalProperties": true,
                "description": "App-defined; the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "session_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/definitions/SessionStatus"
              },
              "status_reason": {
                "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "updated_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "created_at",
              "description",
              "message_count",
              "session_id",
              "status",
              "title",
              "updated_at"
            ],
            "type": "object"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "properties": {
          "meta": {
            "$ref": "#/definitions/SessionMeta"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "meta",
          "session_id"
        ],
        "title": "CreateResponse",
        "type": "object"
      }
    },
    {
      "description": "Delete a session and its entries; calls session::on-deleted.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::delete",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "DeleteRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "deleted": {
            "description": "False when the session did not exist (no event fires).",
            "type": "boolean"
          }
        },
        "required": [
          "deleted"
        ],
        "title": "DeleteResponse",
        "type": "object"
      }
    },
    {
      "description": "Delete one stored attachment no transcript entry references (e.g. a chip removed from the composer); also drops it from the draft. Event-silent.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::delete-attachment",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "attachment_id": {
            "type": "string"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "attachment_id",
          "session_id"
        ],
        "title": "DeleteAttachmentRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "deleted": {
            "description": "`false` when the attachment was already absent (a silent no-op).",
            "type": "boolean"
          }
        },
        "required": [
          "deleted"
        ],
        "title": "DeleteAttachmentResponse",
        "type": "object"
      }
    },
    {
      "description": "Idempotently ensure a session with a given id exists; calls session::on-created only when it creates.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::ensure",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          }
        },
        "properties": {
          "description": {
            "description": "Description applied only when the session is created.",
            "type": [
              "string",
              "null"
            ]
          },
          "kind": {
            "anyOf": [
              {
                "$ref": "#/definitions/SessionKind"
              },
              {
                "type": "null"
              }
            ],
            "description": "Kind applied only when the session is created. Defaults to `user`."
          },
          "metadata": {
            "additionalProperties": true,
            "description": "Metadata applied only when the session is created.",
            "type": [
              "object",
              "null"
            ]
          },
          "session_id": {
            "description": "Caller-chosen session id to ensure.",
            "type": "string"
          },
          "title": {
            "description": "Title applied only when the session is created.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "session_id"
        ],
        "title": "EnsureRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "draft": {
                "description": "Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "draft_attachments": {
                "description": "Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.",
                "items": {
                  "$ref": "#/definitions/AttachmentMeta"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "allOf": [
                  {
                    "$ref": "#/definitions/SessionKind"
                  }
                ],
                "default": "user",
                "description": "Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`."
              },
              "message_count": {
                "description": "Number of `kind: \"message\"` entries (custom entries are bookkeeping and not counted).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "metadata": {
                "additionalProperties": true,
                "description": "App-defined; the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "session_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/definitions/SessionStatus"
              },
              "status_reason": {
                "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "updated_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "created_at",
              "description",
              "message_count",
              "session_id",
              "status",
              "title",
              "updated_at"
            ],
            "type": "object"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "properties": {
          "created": {
            "description": "True when this call created the session (and called `session::on-created`).",
            "type": "boolean"
          },
          "meta": {
            "$ref": "#/definitions/SessionMeta"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "created",
          "meta",
          "session_id"
        ],
        "title": "EnsureResponse",
        "type": "object"
      }
    },
    {
      "description": "Copy history up to an entry into a new session (copy-on-fork); calls session::on-created.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::fork",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "entry_id": {
            "description": "Fork point: the root -> entry path is copied (copy-on-fork, fresh entry ids) and becomes the new session's active path.",
            "type": "string"
          },
          "session_id": {
            "description": "Source session.",
            "type": "string"
          },
          "title": {
            "description": "Title for the new session (default: the source's title).",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "entry_id",
          "session_id"
        ],
        "title": "ForkRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "draft": {
                "description": "Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "draft_attachments": {
                "description": "Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.",
                "items": {
                  "$ref": "#/definitions/AttachmentMeta"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "allOf": [
                  {
                    "$ref": "#/definitions/SessionKind"
                  }
                ],
                "default": "user",
                "description": "Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`."
              },
              "message_count": {
                "description": "Number of `kind: \"message\"` entries (custom entries are bookkeeping and not counted).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "metadata": {
                "additionalProperties": true,
                "description": "App-defined; the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "session_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/definitions/SessionStatus"
              },
              "status_reason": {
                "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "updated_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "created_at",
              "description",
              "message_count",
              "session_id",
              "status",
              "title",
              "updated_at"
            ],
            "type": "object"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "properties": {
          "meta": {
            "$ref": "#/definitions/SessionMeta"
          },
          "session_id": {
            "description": "The new session's id (`forked_from` is set on its meta).",
            "type": "string"
          }
        },
        "required": [
          "meta",
          "session_id"
        ],
        "title": "ForkResponse",
        "type": "object"
      }
    },
    {
      "description": "Read one session's metadata (null when unknown).",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::get",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "GetRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "anyOf": [
          {
            "$ref": "#/definitions/GetResponse"
          },
          {
            "type": "null"
          }
        ],
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "GetResponse": {
            "description": "`null` when the session is unknown.",
            "properties": {
              "meta": {
                "$ref": "#/definitions/SessionMeta"
              }
            },
            "required": [
              "meta"
            ],
            "type": "object"
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "draft": {
                "description": "Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "draft_attachments": {
                "description": "Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.",
                "items": {
                  "$ref": "#/definitions/AttachmentMeta"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "allOf": [
                  {
                    "$ref": "#/definitions/SessionKind"
                  }
                ],
                "default": "user",
                "description": "Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`."
              },
              "message_count": {
                "description": "Number of `kind: \"message\"` entries (custom entries are bookkeeping and not counted).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "metadata": {
                "additionalProperties": true,
                "description": "App-defined; the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "session_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/definitions/SessionStatus"
              },
              "status_reason": {
                "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "updated_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "created_at",
              "description",
              "message_count",
              "session_id",
              "status",
              "title",
              "updated_at"
            ],
            "type": "object"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "title": "Nullable_GetResponse"
      }
    },
    {
      "description": "Read one stored attachment's metadata and bytes (null when unknown).",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::get-attachment",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "attachment_id": {
            "type": "string"
          },
          "include_data": {
            "description": "Include the bytes (`data`, standard base64). Default true; pass false for a metadata-only read.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "attachment_id",
          "session_id"
        ],
        "title": "GetAttachmentRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "anyOf": [
          {
            "$ref": "#/definitions/GetAttachmentResponse"
          },
          {
            "type": "null"
          }
        ],
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "GetAttachmentResponse": {
            "description": "`null` when the session or attachment is unknown.",
            "properties": {
              "attachment": {
                "$ref": "#/definitions/AttachmentMeta"
              },
              "data": {
                "description": "Standard base64 of the bytes; `null` when `include_data` was false.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "attachment"
            ],
            "type": "object"
          }
        },
        "title": "Nullable_GetAttachmentResponse"
      }
    },
    {
      "description": "Read a single entry by id (null when unknown).",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::get-message",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "entry_id": {
            "type": "string"
          },
          "include_image_data": {
            "description": "Default true. When false, `image` blocks that carry an `attachment_id` come back with `data: \"\"` (same rule as `session::messages`).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "entry_id",
          "session_id"
        ],
        "title": "GetMessageRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "anyOf": [
          {
            "$ref": "#/definitions/GetMessageResponse"
          },
          {
            "type": "null"
          }
        ],
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "GetMessageResponse": {
            "description": "`null` when the session or entry is unknown.",
            "properties": {
              "entry": {
                "$ref": "#/definitions/SessionEntry"
              }
            },
            "required": [
              "entry"
            ],
            "type": "object"
          },
          "SessionEntry": {
            "description": "The entry envelope giving each stored item identity, ordering and a parent link (used for forking), discriminated by `kind`.",
            "oneOf": [
              {
                "description": "A transcript message.",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "message"
                    ],
                    "type": "string"
                  },
                  "message": {
                    "$ref": "#/definitions/AgentMessage"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "id",
                  "kind",
                  "message",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Bookkeeping *about* the conversation that is not a message at all (e.g. the harness's compaction record).",
                "properties": {
                  "custom_type": {
                    "type": "string"
                  },
                  "data": {
                    "default": null
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "custom_type",
                  "id",
                  "kind",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "title": "Nullable_GetMessageResponse"
      }
    },
    {
      "description": "List sessions with pagination, ordering, and status/metadata filters.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::list",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "ListOrder": {
            "description": "Sort order for `session::list`.",
            "enum": [
              "created_asc",
              "created_desc",
              "updated_desc"
            ],
            "type": "string"
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "properties": {
          "cursor": {
            "description": "Opaque pagination cursor from a previous response.",
            "type": [
              "string",
              "null"
            ]
          },
          "kinds": {
            "description": "Only sessions whose kind is one of these. Omit for every kind; an empty list matches nothing.",
            "items": {
              "$ref": "#/definitions/SessionKind"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "limit": {
            "description": "Page size. Default 50, clamped to the configured maximum.",
            "format": "uint",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "metadata": {
            "additionalProperties": true,
            "description": "Equality filter against `SessionMeta.metadata` (tenancy): every given key must equal the stored value.",
            "type": [
              "object",
              "null"
            ]
          },
          "order": {
            "anyOf": [
              {
                "$ref": "#/definitions/ListOrder"
              },
              {
                "type": "null"
              }
            ],
            "description": "Sort order. Default `updated_desc`."
          },
          "status": {
            "anyOf": [
              {
                "$ref": "#/definitions/SessionStatus"
              },
              {
                "type": "null"
              }
            ],
            "description": "Only sessions with this status."
          }
        },
        "title": "ListRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "draft": {
                "description": "Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "draft_attachments": {
                "description": "Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.",
                "items": {
                  "$ref": "#/definitions/AttachmentMeta"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "allOf": [
                  {
                    "$ref": "#/definitions/SessionKind"
                  }
                ],
                "default": "user",
                "description": "Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`."
              },
              "message_count": {
                "description": "Number of `kind: \"message\"` entries (custom entries are bookkeeping and not counted).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "metadata": {
                "additionalProperties": true,
                "description": "App-defined; the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "session_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/definitions/SessionStatus"
              },
              "status_reason": {
                "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "updated_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "created_at",
              "description",
              "message_count",
              "session_id",
              "status",
              "title",
              "updated_at"
            ],
            "type": "object"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "properties": {
          "next_cursor": {
            "description": "Present when more pages remain.",
            "type": [
              "string",
              "null"
            ]
          },
          "sessions": {
            "items": {
              "$ref": "#/definitions/SessionMeta"
            },
            "type": "array"
          }
        },
        "required": [
          "sessions"
        ],
        "title": "ListResponse",
        "type": "object"
      }
    },
    {
      "description": "List the metadata of every attachment stored for a session.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::list-attachments",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "ListAttachmentsRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          }
        },
        "properties": {
          "attachments": {
            "description": "Oldest first (`created_at`, then `attachment_id`).",
            "items": {
              "$ref": "#/definitions/AttachmentMeta"
            },
            "type": "array"
          }
        },
        "required": [
          "attachments"
        ],
        "title": "ListAttachmentsResponse",
        "type": "object"
      }
    },
    {
      "description": "Resolve a @session(id=…) chat mention to its pill, preview card and agent summary; null for an unknown id. Declares the session mention provider.",
      "metadata": {
        "internal": true,
        "mention": {
          "color": "neutral",
          "description": "A chat session, by session id; its transcript reads through session::messages-tail",
          "details": {
            "function_id": "session::get",
            "id_field": "session_id"
          },
          "icon": "session",
          "label": "Sessions",
          "name": "session",
          "search": "session::mention::search",
          "v": 1
        },
        "trace_hidden": true
      },
      "name": "session::mention::get",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Input of a provider's get function.",
        "properties": {
          "id": {
            "description": "The id from the token.",
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "title": "MentionGetRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "anyOf": [
          {
            "$ref": "#/definitions/MentionView"
          },
          {
            "type": "null"
          }
        ],
        "definitions": {
          "MentionField": {
            "description": "One labelled value of a preview card.",
            "properties": {
              "label": {
                "type": "string"
              },
              "tone": {
                "description": "`neutral`, `info`, `success`, `warning` or `danger`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "value": {
                "type": "string"
              }
            },
            "required": [
              "label",
              "value"
            ],
            "type": "object"
          },
          "MentionOpen": {
            "anyOf": [
              {
                "properties": {
                  "context": true,
                  "page": {
                    "description": "Console page id (as registered with `host.pages`).",
                    "type": "string"
                  }
                },
                "required": [
                  "page"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "session": {
                    "description": "Session id to select.",
                    "type": "string"
                  }
                },
                "required": [
                  "session"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "url": {
                    "type": "string"
                  }
                },
                "required": [
                  "url"
                ],
                "type": "object"
              }
            ],
            "description": "What clicking a mention opens: an injected console page, a chat session, or an http(s) URL."
          },
          "MentionView": {
            "description": "What a chat surface renders for one mention, and what an agent reads. A get function answers `null` for an id it does not know.",
            "properties": {
              "color": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "data": {
                "description": "The domain object, for a worker's own preview renderer."
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "fields": {
                "description": "Labelled values for the preview card (status, assignee, …).",
                "items": {
                  "$ref": "#/definitions/MentionField"
                },
                "type": "array"
              },
              "hint": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "icon": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "id": {
                "description": "The canonical id (may differ from the one asked for, e.g. a key resolved to a uuid).",
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "open": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/MentionOpen"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "What clicking the mention opens."
              },
              "summary": {
                "description": "One line for an agent: what the item is and its state. Defaults to the label, hint, description and fields.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "updated_at": {
                "description": "RFC 3339 time of the item's last change.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "label"
            ],
            "type": "object"
          }
        },
        "title": "Nullable_MentionView"
      }
    },
    {
      "description": "Search sessions for the chat @session mention menu, by title words or session id; best match first.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::mention::search",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "MentionSearchContext": {
            "description": "The chat a search was asked from.",
            "properties": {
              "session_id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "working_dir": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "description": "Input of a provider's search function.",
        "properties": {
          "context": {
            "anyOf": [
              {
                "$ref": "#/definitions/MentionSearchContext"
              },
              {
                "type": "null"
              }
            ],
            "description": "Where the search was asked from, for providers that rank by it."
          },
          "limit": {
            "description": "Maximum rows (default 8, at most 50).",
            "format": "uint",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "query": {
            "default": "",
            "description": "What the user typed after `@<name>:`. Empty asks for the most relevant recent items.",
            "type": "string"
          }
        },
        "title": "MentionSearchRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "MentionItem": {
            "description": "One search row.",
            "properties": {
              "color": {
                "description": "Overrides the provider's color for this row.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "description": {
                "description": "One line after the label (\"in progress · high\").",
                "type": [
                  "string",
                  "null"
                ]
              },
              "hint": {
                "description": "A short human handle shown before the label (\"KAN-12\").",
                "type": [
                  "string",
                  "null"
                ]
              },
              "icon": {
                "description": "Overrides the provider's icon for this row.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "id": {
                "description": "The id written into the token; stable for the item's lifetime.",
                "type": "string"
              },
              "label": {
                "description": "The item's name (\"Fix login redirect\").",
                "type": "string"
              }
            },
            "required": [
              "id",
              "label"
            ],
            "type": "object"
          }
        },
        "description": "Output of a provider's search function, best match first.",
        "properties": {
          "items": {
            "items": {
              "$ref": "#/definitions/MentionItem"
            },
            "type": "array"
          }
        },
        "required": [
          "items"
        ],
        "title": "MentionSearchResponse",
        "type": "object"
      }
    },
    {
      "description": "Load the active path as messages with entry ids, oldest first; pagination and role filtering.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::messages",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "ContentProjection": {
            "description": "How much of each message `session::messages` returns.",
            "enum": [
              "full",
              "usage"
            ],
            "type": "string"
          },
          "Role": {
            "description": "Message role discriminator.",
            "enum": [
              "user",
              "assistant",
              "function_result",
              "custom"
            ],
            "type": "string"
          }
        },
        "properties": {
          "after_entry_id": {
            "description": "Return only entries strictly after this entry id on the requested path (incremental fetch from a known watermark). Errors `session/invalid_cursor` when the entry is not on the path — e.g. after a fork moved the active leaf — so callers fall back to a full load. Ignored when `cursor` is set.",
            "type": [
              "string",
              "null"
            ]
          },
          "content": {
            "anyOf": [
              {
                "$ref": "#/definitions/ContentProjection"
              },
              {
                "type": "null"
              }
            ],
            "description": "Default `\"full\"`. `\"usage\"` returns each message without the content a usage reader never looks at: assistant content keeps only its `function_call` blocks (with `arguments: null`); user, function result and custom-role content is empty and their `details` null; `origin` is left out. Role, usage, model/provider, stop reason, timestamps, `is_error` and `function_id` stay, so every message still parses as an `AgentMessage`. `kind: \"custom\"` entries (`include_custom`) come back as stored."
          },
          "cursor": {
            "description": "Opaque pagination cursor from a previous response.",
            "type": [
              "string",
              "null"
            ]
          },
          "custom_types": {
            "description": "With `include_custom`, only the custom entries of these `custom_type`s (e.g. a usage reader skipping compaction summaries). Absent keeps every type.",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "from_entry_id": {
            "description": "Treat this entry as the leaf: return its parent chain, root -> entry, oldest first (branch view).",
            "type": [
              "string",
              "null"
            ]
          },
          "include_custom": {
            "description": "Interleave `kind: \"custom\"` entries at their path position. Default false.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "include_image_data": {
            "description": "Default true. When false, `image` blocks that carry an `attachment_id` come back with `data: \"\"`; the reader fetches the bytes on demand with `session::get-attachment`. Images without a stored original are returned inline regardless. Lets a UI open a long, picture-heavy transcript without pulling every image first; model-bound readers keep the default.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "limit": {
            "description": "Page size. Default 50, clamped to the configured maximum.",
            "format": "uint",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "roles": {
            "description": "Only messages with these roles. Setting this also excludes `kind: \"custom\"` entries (it is an explicit narrowing to roles).",
            "items": {
              "$ref": "#/definitions/Role"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "MessagesRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "CustomPayload": {
            "description": "Bookkeeping payload of a `kind: \"custom\"` session entry.",
            "properties": {
              "custom_type": {
                "description": "App-defined discriminator (e.g. `\"compaction\"`).",
                "type": "string"
              },
              "data": {
                "default": null,
                "description": "Opaque app data."
              }
            },
            "required": [
              "custom_type"
            ],
            "type": "object"
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "MessageItem": {
            "description": "One item of the active path: exactly one of `message` / `custom`.",
            "properties": {
              "custom": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/CustomPayload"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "entry_id": {
                "type": "string"
              },
              "message": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/AgentMessage"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "origin": {
                "additionalProperties": true,
                "description": "The entry's writer-supplied origin (turn correlation plus hook annotations, e.g. which memory bank and facts fed the generate). Absent on custom entries and on entries written without one.",
                "type": [
                  "object",
                  "null"
                ]
              }
            },
            "required": [
              "entry_id"
            ],
            "type": "object"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "properties": {
          "messages": {
            "items": {
              "$ref": "#/definitions/MessageItem"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Present when more pages remain.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "messages"
        ],
        "title": "MessagesResponse",
        "type": "object"
      }
    },
    {
      "description": "Full entries for a span (from/to) or list (entry_ids) of the active path — how a reader fetches the calls a collapsed run left out.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::messages-range",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "cursor": {
            "description": "Opaque pagination cursor from a previous response.",
            "type": [
              "string",
              "null"
            ]
          },
          "entry_ids": {
            "description": "Specific entries, returned in path order (duplicates folded).",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "from_entry_id": {
            "description": "With `to_entry_id`: every entry of the active path from this one to `to_entry_id`, both inclusive, oldest first. Exactly one selector (`from_entry_id`+`to_entry_id`, or `entry_ids`) is required.",
            "type": [
              "string",
              "null"
            ]
          },
          "include_image_data": {
            "description": "Default true. When false, `image` blocks that carry an `attachment_id` come back with `data: \"\"` (as `session::messages`).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "limit": {
            "description": "Page size in entries. Default 50, clamped to the configured maximum; a long run comes back in several pages.",
            "format": "uint",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "to_entry_id": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "session_id"
        ],
        "title": "MessagesRangeRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "CustomPayload": {
            "description": "Bookkeeping payload of a `kind: \"custom\"` session entry.",
            "properties": {
              "custom_type": {
                "description": "App-defined discriminator (e.g. `\"compaction\"`).",
                "type": "string"
              },
              "data": {
                "default": null,
                "description": "Opaque app data."
              }
            },
            "required": [
              "custom_type"
            ],
            "type": "object"
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "TailItem": {
            "description": "One item of the page: exactly one of `message` / `custom`. Same fields as `session::messages` items plus `elided`.",
            "properties": {
              "custom": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/CustomPayload"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "elided": {
                "description": "Present and true when this entry sits inside a collapsed activity run and the heavy parts of its message were left out: `function_call` blocks keep `id` + `function_id` but carry `arguments: {}` (an `agent_call` wrapper call keeps its string `function` + `description` label and drops `payload`), `function_result` messages keep `function_call_id` + `is_error` with `content: []` and `details: null`, thinking is dropped, text is kept. `session::messages-range` returns the whole entry.",
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "entry_id": {
                "type": "string"
              },
              "message": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/AgentMessage"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "origin": {
                "additionalProperties": true,
                "description": "The entry's writer-supplied origin, as on `session::messages`.",
                "type": [
                  "object",
                  "null"
                ]
              }
            },
            "required": [
              "entry_id"
            ],
            "type": "object"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "properties": {
          "messages": {
            "description": "Oldest first; never `elided`.",
            "items": {
              "$ref": "#/definitions/TailItem"
            },
            "type": "array"
          },
          "next_cursor": {
            "description": "Present when more entries of the selection remain.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "messages"
        ],
        "title": "MessagesRangeResponse",
        "type": "object"
      }
    },
    {
      "description": "Newest page of the active path, walking backwards in block-aligned pages (a tool run never splits) with activity runs collapsed to placeholders; the reader a chat UI opens a session with.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::messages-tail",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "before_entry_id": {
            "description": "Exclusive upper bound: return the page ending just before the block that contains this entry (the oldest entry the caller already has). Omitted = the newest page. `session/invalid_cursor` when the entry is not on the active path (e.g. after a fork moved the leaf), so callers reload from the top.",
            "type": [
              "string",
              "null"
            ]
          },
          "include_custom": {
            "description": "Interleave `kind: \"custom\"` entries at their path position. Default TRUE here (unlike `session::messages`): a transcript reader wants compaction markers and wake records in place.",
            "type": [
              "boolean",
              "null"
            ]
          },
          "include_image_data": {
            "description": "Default true. When false, `image` blocks that carry an `attachment_id` come back with `data: \"\"` (as `session::messages`).",
            "type": [
              "boolean",
              "null"
            ]
          },
          "limit": {
            "description": "Page size in *blocks* (an entry, or one whole activity run), not entries: a page is \"N conversational steps\", and a tool run of 300 calls counts once. Default 50, clamped to the configured maximum.",
            "format": "uint",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "until_entry_id": {
            "description": "Extend the page backwards until the block containing this entry is included, ignoring `limit` (deep links: \"go to message\"). No-op when the entry is already within the page or newer than it. `session/invalid_cursor` when not on the active path.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "session_id"
        ],
        "title": "MessagesTailRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "CustomPayload": {
            "description": "Bookkeeping payload of a `kind: \"custom\"` session entry.",
            "properties": {
              "custom_type": {
                "description": "App-defined discriminator (e.g. `\"compaction\"`).",
                "type": "string"
              },
              "data": {
                "default": null,
                "description": "Opaque app data."
              }
            },
            "required": [
              "custom_type"
            ],
            "type": "object"
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "TailItem": {
            "description": "One item of the page: exactly one of `message` / `custom`. Same fields as `session::messages` items plus `elided`.",
            "properties": {
              "custom": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/CustomPayload"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "elided": {
                "description": "Present and true when this entry sits inside a collapsed activity run and the heavy parts of its message were left out: `function_call` blocks keep `id` + `function_id` but carry `arguments: {}` (an `agent_call` wrapper call keeps its string `function` + `description` label and drops `payload`), `function_result` messages keep `function_call_id` + `is_error` with `content: []` and `details: null`, thinking is dropped, text is kept. `session::messages-range` returns the whole entry.",
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "entry_id": {
                "type": "string"
              },
              "message": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/AgentMessage"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "origin": {
                "additionalProperties": true,
                "description": "The entry's writer-supplied origin, as on `session::messages`.",
                "type": [
                  "object",
                  "null"
                ]
              }
            },
            "required": [
              "entry_id"
            ],
            "type": "object"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "properties": {
          "has_more": {
            "description": "True when older blocks exist before this page.",
            "type": "boolean"
          },
          "messages": {
            "description": "Oldest first, like `session::messages`.",
            "items": {
              "$ref": "#/definitions/TailItem"
            },
            "type": "array"
          },
          "oldest_entry_id": {
            "description": "The first entry of this page: pass it as `before_entry_id` to fetch the page before. Absent on an empty page.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "has_more",
          "messages"
        ],
        "title": "MessagesTailResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal: hot-reload session-manager from the authoritative configuration when it changes — rebuilds the storage adapter and event plumbing on an adapter change (replaying current state to the session event observers) and swaps the list limits otherwise.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::on-config-change",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "The `configuration::on-updated` event, delivered to the internal `session::on-config-change` handler as output. The handler re-fetches the authoritative configuration, so it reads only the (advisory) configuration id; a struct (not `Value`) keeps the request schema concrete and unknown fields are ignored.",
        "properties": {
          "id": {
            "default": null,
            "description": "Configuration id that changed (advisory; the handler re-fetches the value).",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "OnConfigChangeEvent",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Ack returned by the internal `session::on-config-change` handler.",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OnConfigChangeResponse",
        "type": "object"
      }
    },
    {
      "description": "A session was created (session::create, session::ensure or session::fork). Observe it with filters on input.session_id and input.session_metadata.<key>; the event carries the session's metadata as session_metadata.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::on-created",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "created_at": {
            "format": "int64",
            "type": "integer"
          },
          "description": {
            "type": "string"
          },
          "forked_from": {
            "description": "Source session id when created by fork.",
            "type": [
              "string",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/definitions/SessionStatus"
              }
            ],
            "description": "`\"idle\"` on create."
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "created_at",
          "description",
          "session_id",
          "status",
          "title"
        ],
        "title": "WithSessionMetadata_for_SessionCreatedEvent",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "created_at": {
            "format": "int64",
            "type": "integer"
          },
          "description": {
            "type": "string"
          },
          "forked_from": {
            "description": "Source session id when created by fork.",
            "type": [
              "string",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/definitions/SessionStatus"
              }
            ],
            "description": "`\"idle\"` on create."
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "created_at",
          "description",
          "session_id",
          "status",
          "title"
        ],
        "title": "WithSessionMetadata_for_SessionCreatedEvent",
        "type": "object"
      }
    },
    {
      "description": "A session and its entries were removed; session_metadata is the metadata it had before deletion. Observe it with filters on input.session_id and input.session_metadata.<key>.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::on-deleted",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "session_id",
          "timestamp"
        ],
        "title": "WithSessionMetadata_for_SessionDeletedEvent",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "session_id",
          "timestamp"
        ],
        "title": "WithSessionMetadata_for_SessionDeletedEvent",
        "type": "object"
      }
    },
    {
      "description": "An entry was appended to a session. Observe it with filters on input.session_id, input.message.role and input.session_metadata.<key>; custom entries carry `custom` and no message.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::on-message-added",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "CustomPayload": {
            "description": "Bookkeeping payload of a `kind: \"custom\"` session entry.",
            "properties": {
              "custom_type": {
                "description": "App-defined discriminator (e.g. `\"compaction\"`).",
                "type": "string"
              },
              "data": {
                "default": null,
                "description": "Opaque app data."
              }
            },
            "required": [
              "custom_type"
            ],
            "type": "object"
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "custom": {
            "anyOf": [
              {
                "$ref": "#/definitions/CustomPayload"
              },
              {
                "type": "null"
              }
            ]
          },
          "entry_id": {
            "type": "string"
          },
          "message": {
            "anyOf": [
              {
                "$ref": "#/definitions/AgentMessage"
              },
              {
                "type": "null"
              }
            ]
          },
          "origin": {
            "additionalProperties": true,
            "description": "Writer-supplied correlation (e.g. `{ turn_id }`).",
            "type": [
              "object",
              "null"
            ]
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "entry_id",
          "session_id",
          "timestamp"
        ],
        "title": "WithSessionMetadata_for_MessageAddedEvent",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "CustomPayload": {
            "description": "Bookkeeping payload of a `kind: \"custom\"` session entry.",
            "properties": {
              "custom_type": {
                "description": "App-defined discriminator (e.g. `\"compaction\"`).",
                "type": "string"
              },
              "data": {
                "default": null,
                "description": "Opaque app data."
              }
            },
            "required": [
              "custom_type"
            ],
            "type": "object"
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "custom": {
            "anyOf": [
              {
                "$ref": "#/definitions/CustomPayload"
              },
              {
                "type": "null"
              }
            ]
          },
          "entry_id": {
            "type": "string"
          },
          "message": {
            "anyOf": [
              {
                "$ref": "#/definitions/AgentMessage"
              },
              {
                "type": "null"
              }
            ]
          },
          "origin": {
            "additionalProperties": true,
            "description": "Writer-supplied correlation (e.g. `{ turn_id }`).",
            "type": [
              "object",
              "null"
            ]
          },
          "parent_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "entry_id",
          "session_id",
          "timestamp"
        ],
        "title": "WithSessionMetadata_for_MessageAddedEvent",
        "type": "object"
      }
    },
    {
      "description": "A message entry's content changed (e.g. streaming deltas); keep the highest revision per entry. Observe it with filters on input.session_id, input.message.role and input.session_metadata.<key>.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::on-message-updated",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "entry_id": {
            "type": "string"
          },
          "message": {
            "allOf": [
              {
                "$ref": "#/definitions/AgentMessage"
              }
            ],
            "description": "The full updated message (consumers apply snapshots last-write-wins by `revision`)."
          },
          "origin": {
            "additionalProperties": true,
            "description": "Writer-supplied correlation (e.g. `{ turn_id }`).",
            "type": [
              "object",
              "null"
            ]
          },
          "revision": {
            "description": "Monotonic per entry; consumers keep the highest.",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "entry_id",
          "message",
          "revision",
          "session_id",
          "timestamp"
        ],
        "title": "WithSessionMetadata_for_MessageUpdatedEvent",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "entry_id": {
            "type": "string"
          },
          "message": {
            "allOf": [
              {
                "$ref": "#/definitions/AgentMessage"
              }
            ],
            "description": "The full updated message (consumers apply snapshots last-write-wins by `revision`)."
          },
          "origin": {
            "additionalProperties": true,
            "description": "Writer-supplied correlation (e.g. `{ turn_id }`).",
            "type": [
              "object",
              "null"
            ]
          },
          "revision": {
            "description": "Monotonic per entry; consumers keep the highest.",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "entry_id",
          "message",
          "revision",
          "session_id",
          "timestamp"
        ],
        "title": "WithSessionMetadata_for_MessageUpdatedEvent",
        "type": "object"
      }
    },
    {
      "description": "A session's title/description/metadata changed. Observe it with filters on input.session_id and input.session_metadata.<key>.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::on-meta-updated",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "description": {
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "type": [
              "object",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "description",
          "session_id",
          "timestamp",
          "title"
        ],
        "title": "WithSessionMetadata_for_MetaUpdatedEvent",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "description": {
            "type": "string"
          },
          "metadata": {
            "additionalProperties": true,
            "type": [
              "object",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "description",
          "session_id",
          "timestamp",
          "title"
        ],
        "title": "WithSessionMetadata_for_MetaUpdatedEvent",
        "type": "object"
      }
    },
    {
      "description": "A session's status changed (idle/working/done/error). Observe it with filters on input.session_id and input.session_metadata.<key>.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "session::on-status-changed",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "previous_status": {
            "$ref": "#/definitions/SessionStatus"
          },
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "status": {
            "$ref": "#/definitions/SessionStatus"
          },
          "status_reason": {
            "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
            "type": [
              "string",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "previous_status",
          "session_id",
          "status",
          "timestamp"
        ],
        "title": "WithSessionMetadata_for_StatusChangedEvent",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "description": "What an event function is called with and returns, so what its observers observe: the event's fields plus the session's metadata.",
        "properties": {
          "previous_status": {
            "$ref": "#/definitions/SessionStatus"
          },
          "session_id": {
            "type": "string"
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation (for `session::on-deleted`, as of just before deletion); omitted when the session has none. Observers filter on `input.session_metadata.<key>`.",
            "type": [
              "object",
              "null"
            ]
          },
          "status": {
            "$ref": "#/definitions/SessionStatus"
          },
          "status_reason": {
            "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
            "type": [
              "string",
              "null"
            ]
          },
          "timestamp": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "previous_status",
          "session_id",
          "status",
          "timestamp"
        ],
        "title": "WithSessionMetadata_for_StatusChangedEvent",
        "type": "object"
      }
    },
    {
      "description": "Store an attachment's original bytes (base64) for a session and return the `file` content block that references it; event-silent.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::put-attachment",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "data": {
            "description": "The bytes as standard (padded) base64. Decoded size must not exceed the configured `max_attachment_bytes`.",
            "type": "string"
          },
          "mime": {
            "description": "MIME type; pass `application/octet-stream` when unknown.",
            "type": "string"
          },
          "name": {
            "description": "Original filename (non-empty).",
            "type": "string"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "mime",
          "name",
          "session_id"
        ],
        "title": "PutAttachmentRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          }
        },
        "properties": {
          "attachment": {
            "$ref": "#/definitions/AttachmentMeta"
          },
          "block": {
            "allOf": [
              {
                "$ref": "#/definitions/ContentBlock"
              }
            ],
            "description": "Ready-made `type: \"file\"` content block referencing the attachment, to embed in the message's `content`."
          }
        },
        "required": [
          "attachment",
          "block"
        ],
        "title": "PutAttachmentResponse",
        "type": "object"
      }
    },
    {
      "description": "Move the active path to end at a given entry (branch switch).",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::set-active-leaf",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "entry_id": {
            "description": "The entry the active path should end at. Subsequent `session::append` without `parent_id` chains from here.",
            "type": "string"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "entry_id",
          "session_id"
        ],
        "title": "SetActiveLeafRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "active_leaf": {
            "type": "string"
          }
        },
        "required": [
          "active_leaf"
        ],
        "title": "SetActiveLeafResponse",
        "type": "object"
      }
    },
    {
      "description": "Park (or clear) the session's unsent composer input — text and attachment ids; event-silent, read back on SessionMeta.draft / draft_attachments.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::set-draft",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "attachment_ids": {
            "description": "Attachments parked with the draft, by id (uploaded beforehand with `session::put-attachment`; an unknown id is `session/invalid_request`). Omit to leave the parked attachments unchanged — a text-only save must not drop them — or send `[]` to clear them.",
            "items": {
              "type": "string"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "draft": {
            "description": "The unsent input to park. Omit, or send empty/whitespace-only text, to clear the stored draft text.",
            "type": [
              "string",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "SetDraftRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          }
        },
        "properties": {
          "attachments": {
            "description": "The parked attachments as stored after this call, in request order.",
            "items": {
              "$ref": "#/definitions/AttachmentMeta"
            },
            "type": "array"
          },
          "draft": {
            "description": "The draft text as stored after this call (`null` when cleared).",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "attachments"
        ],
        "title": "SetDraftResponse",
        "type": "object"
      }
    },
    {
      "description": "Update a session's title/description/metadata; calls session::on-meta-updated.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::set-meta",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "description": {
            "description": "New description (omit to keep the current one).",
            "type": [
              "string",
              "null"
            ]
          },
          "metadata": {
            "additionalProperties": true,
            "description": "New metadata object — **replaces** the stored one wholesale.",
            "type": [
              "object",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "title": {
            "description": "New title (omit to keep the current one).",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "session_id"
        ],
        "title": "SetMetaRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "draft": {
                "description": "Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "draft_attachments": {
                "description": "Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.",
                "items": {
                  "$ref": "#/definitions/AttachmentMeta"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "allOf": [
                  {
                    "$ref": "#/definitions/SessionKind"
                  }
                ],
                "default": "user",
                "description": "Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`."
              },
              "message_count": {
                "description": "Number of `kind: \"message\"` entries (custom entries are bookkeeping and not counted).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "metadata": {
                "additionalProperties": true,
                "description": "App-defined; the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "session_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/definitions/SessionStatus"
              },
              "status_reason": {
                "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "updated_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "created_at",
              "description",
              "message_count",
              "session_id",
              "status",
              "title",
              "updated_at"
            ],
            "type": "object"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "properties": {
          "meta": {
            "$ref": "#/definitions/SessionMeta"
          }
        },
        "required": [
          "meta"
        ],
        "title": "SetMetaResponse",
        "type": "object"
      }
    },
    {
      "description": "Set status idle/working/done/error; calls session::on-status-changed (no-op when unchanged).",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::set-status",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "properties": {
          "reason": {
            "description": "Short cause/phase stored as `status_reason` — kept on `error` (failure cause), `working` (live phase detail), and `done` (for terminal detail such as `stopped`); cleared on `idle`.",
            "type": [
              "string",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "status": {
            "allOf": [
              {
                "$ref": "#/definitions/SessionStatus"
              }
            ],
            "description": "Target status: `idle` / `working` / `done` / `error`."
          }
        },
        "required": [
          "session_id",
          "status"
        ],
        "title": "SetStatusRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "properties": {
          "previous_status": {
            "$ref": "#/definitions/SessionStatus"
          },
          "status": {
            "$ref": "#/definitions/SessionStatus"
          }
        },
        "required": [
          "previous_status",
          "status"
        ],
        "title": "SetStatusResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: atomically commit one session append.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::commit-append",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "SessionEntry": {
            "description": "The entry envelope giving each stored item identity, ordering and a parent link (used for forking), discriminated by `kind`.",
            "oneOf": [
              {
                "description": "A transcript message.",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "message"
                    ],
                    "type": "string"
                  },
                  "message": {
                    "$ref": "#/definitions/AgentMessage"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "id",
                  "kind",
                  "message",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Bookkeeping *about* the conversation that is not a message at all (e.g. the harness's compaction record).",
                "properties": {
                  "custom_type": {
                    "type": "string"
                  },
                  "data": {
                    "default": null
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "custom_type",
                  "id",
                  "kind",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "properties": {
          "entry": {
            "$ref": "#/definitions/SessionEntry"
          },
          "parent_explicit": {
            "type": "boolean"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "entry",
          "parent_explicit",
          "session_id"
        ],
        "title": "CommitAppendRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "SessionEntry": {
            "description": "The entry envelope giving each stored item identity, ordering and a parent link (used for forking), discriminated by `kind`.",
            "oneOf": [
              {
                "description": "A transcript message.",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "message"
                    ],
                    "type": "string"
                  },
                  "message": {
                    "$ref": "#/definitions/AgentMessage"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "id",
                  "kind",
                  "message",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Bookkeeping *about* the conversation that is not a message at all (e.g. the harness's compaction record).",
                "properties": {
                  "custom_type": {
                    "type": "string"
                  },
                  "data": {
                    "default": null
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "custom_type",
                  "id",
                  "kind",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "draft": {
                "description": "Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "draft_attachments": {
                "description": "Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.",
                "items": {
                  "$ref": "#/definitions/AttachmentMeta"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "allOf": [
                  {
                    "$ref": "#/definitions/SessionKind"
                  }
                ],
                "default": "user",
                "description": "Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`."
              },
              "message_count": {
                "description": "Number of `kind: \"message\"` entries (custom entries are bookkeeping and not counted).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "metadata": {
                "additionalProperties": true,
                "description": "App-defined; the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "session_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/definitions/SessionStatus"
              },
              "status_reason": {
                "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "updated_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "created_at",
              "description",
              "message_count",
              "session_id",
              "status",
              "title",
              "updated_at"
            ],
            "type": "object"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "properties": {
          "committed": {
            "type": "boolean"
          },
          "entry": {
            "$ref": "#/definitions/SessionEntry"
          },
          "meta": {
            "$ref": "#/definitions/SessionMeta"
          }
        },
        "required": [
          "committed",
          "entry",
          "meta"
        ],
        "title": "CommitAppendResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: clear a session's active leaf pointer.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::delete-active-leaf",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "SessionIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OkResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: delete one attachment (deleted: false when unknown).",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::delete-attachment",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "attachment_id": {
            "type": "string"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "attachment_id",
          "session_id"
        ],
        "title": "AttachmentIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "deleted": {
            "type": "boolean"
          }
        },
        "required": [
          "deleted"
        ],
        "title": "DeletedResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: delete every attachment of a session.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::delete-attachments",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "SessionIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OkResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: delete every entry of a session.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::delete-entries",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "SessionIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OkResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: delete one SessionMeta.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::delete-meta",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "SessionIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OkResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: read a session's active leaf pointer.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::get-active-leaf",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "SessionIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "entry_id": {
            "description": "`null` when the session has no active leaf.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "ActiveLeafResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: read one attachment (metadata + base64 bytes; null when unknown).",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::get-attachment",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "attachment_id": {
            "type": "string"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "attachment_id",
          "session_id"
        ],
        "title": "AttachmentIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "anyOf": [
          {
            "$ref": "#/definitions/StoredAttachment"
          },
          {
            "type": "null"
          }
        ],
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "StoredAttachment": {
            "description": "One stored attachment as the protocol moves it: metadata plus the bytes as standard base64.",
            "properties": {
              "data": {
                "type": "string"
              },
              "meta": {
                "$ref": "#/definitions/AttachmentMeta"
              }
            },
            "required": [
              "data",
              "meta"
            ],
            "type": "object"
          }
        },
        "title": "Nullable_StoredAttachment"
      }
    },
    {
      "description": "Internal store protocol: read one SessionEntry (null when unknown).",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::get-entry",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "entry_id": {
            "type": "string"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "entry_id",
          "session_id"
        ],
        "title": "EntryIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "anyOf": [
          {
            "$ref": "#/definitions/SessionEntry"
          },
          {
            "type": "null"
          }
        ],
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "SessionEntry": {
            "description": "The entry envelope giving each stored item identity, ordering and a parent link (used for forking), discriminated by `kind`.",
            "oneOf": [
              {
                "description": "A transcript message.",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "message"
                    ],
                    "type": "string"
                  },
                  "message": {
                    "$ref": "#/definitions/AgentMessage"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "id",
                  "kind",
                  "message",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Bookkeeping *about* the conversation that is not a message at all (e.g. the harness's compaction record).",
                "properties": {
                  "custom_type": {
                    "type": "string"
                  },
                  "data": {
                    "default": null
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "custom_type",
                  "id",
                  "kind",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "title": "Nullable_SessionEntry"
      }
    },
    {
      "description": "Internal store protocol: read one SessionMeta (null when unknown).",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::get-meta",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "SessionIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "anyOf": [
          {
            "$ref": "#/definitions/SessionMeta"
          },
          {
            "type": "null"
          }
        ],
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "draft": {
                "description": "Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "draft_attachments": {
                "description": "Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.",
                "items": {
                  "$ref": "#/definitions/AttachmentMeta"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "allOf": [
                  {
                    "$ref": "#/definitions/SessionKind"
                  }
                ],
                "default": "user",
                "description": "Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`."
              },
              "message_count": {
                "description": "Number of `kind: \"message\"` entries (custom entries are bookkeeping and not counted).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "metadata": {
                "additionalProperties": true,
                "description": "App-defined; the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "session_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/definitions/SessionStatus"
              },
              "status_reason": {
                "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "updated_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "created_at",
              "description",
              "message_count",
              "session_id",
              "status",
              "title",
              "updated_at"
            ],
            "type": "object"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "title": "Nullable_SessionMeta"
      }
    },
    {
      "description": "Internal store protocol: list every attachment's metadata of a session.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::list-attachments",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "SessionIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          }
        },
        "properties": {
          "attachments": {
            "items": {
              "$ref": "#/definitions/AttachmentMeta"
            },
            "type": "array"
          }
        },
        "required": [
          "attachments"
        ],
        "title": "ListAttachmentsResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: list every entry of a session.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::list-entries",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "session_id"
        ],
        "title": "SessionIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "SessionEntry": {
            "description": "The entry envelope giving each stored item identity, ordering and a parent link (used for forking), discriminated by `kind`.",
            "oneOf": [
              {
                "description": "A transcript message.",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "message"
                    ],
                    "type": "string"
                  },
                  "message": {
                    "$ref": "#/definitions/AgentMessage"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "id",
                  "kind",
                  "message",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Bookkeeping *about* the conversation that is not a message at all (e.g. the harness's compaction record).",
                "properties": {
                  "custom_type": {
                    "type": "string"
                  },
                  "data": {
                    "default": null
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "custom_type",
                  "id",
                  "kind",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "properties": {
          "entries": {
            "items": {
              "$ref": "#/definitions/SessionEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "entries"
        ],
        "title": "ListEntriesResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: list every SessionMeta.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::list-metas",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "title": "ListMetasRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "draft": {
                "description": "Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "draft_attachments": {
                "description": "Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.",
                "items": {
                  "$ref": "#/definitions/AttachmentMeta"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "allOf": [
                  {
                    "$ref": "#/definitions/SessionKind"
                  }
                ],
                "default": "user",
                "description": "Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`."
              },
              "message_count": {
                "description": "Number of `kind: \"message\"` entries (custom entries are bookkeeping and not counted).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "metadata": {
                "additionalProperties": true,
                "description": "App-defined; the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "session_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/definitions/SessionStatus"
              },
              "status_reason": {
                "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "updated_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "created_at",
              "description",
              "message_count",
              "session_id",
              "status",
              "title",
              "updated_at"
            ],
            "type": "object"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "properties": {
          "metas": {
            "items": {
              "$ref": "#/definitions/SessionMeta"
            },
            "type": "array"
          }
        },
        "required": [
          "metas"
        ],
        "title": "ListMetasResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal: the event-envelope feed bridged session-manager instances observe. Called by an fs-mode instance once per event. Observe the six session::on-* functions instead.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::on-events",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Wire form of an [`EmittableEvent`] for cross-instance propagation: what `session::store::on-events` observers receive, and what `session::store::publish-events` takes.",
        "properties": {
          "function_id": {
            "description": "The event function the event belongs to (`session::on-created`, ...).",
            "type": "string"
          },
          "payload": {
            "description": "The event, without the session metadata."
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation.",
            "type": [
              "object",
              "null"
            ]
          }
        },
        "required": [
          "function_id",
          "payload"
        ],
        "title": "EventEnvelope",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Wire form of an [`EmittableEvent`] for cross-instance propagation: what `session::store::on-events` observers receive, and what `session::store::publish-events` takes.",
        "properties": {
          "function_id": {
            "description": "The event function the event belongs to (`session::on-created`, ...).",
            "type": "string"
          },
          "payload": {
            "description": "The event, without the session metadata."
          },
          "session_metadata": {
            "additionalProperties": true,
            "description": "`SessionMeta.metadata` as of the mutation.",
            "type": [
              "object",
              "null"
            ]
          }
        },
        "required": [
          "function_id",
          "payload"
        ],
        "title": "EventEnvelope",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: ingest a bridged instance's event envelopes and call this instance's session::on-* event functions and session::store::on-events with them.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::publish-events",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "EventEnvelope": {
            "description": "Wire form of an [`EmittableEvent`] for cross-instance propagation: what `session::store::on-events` observers receive, and what `session::store::publish-events` takes.",
            "properties": {
              "function_id": {
                "description": "The event function the event belongs to (`session::on-created`, ...).",
                "type": "string"
              },
              "payload": {
                "description": "The event, without the session metadata."
              },
              "session_metadata": {
                "additionalProperties": true,
                "description": "`SessionMeta.metadata` as of the mutation.",
                "type": [
                  "object",
                  "null"
                ]
              }
            },
            "required": [
              "function_id",
              "payload"
            ],
            "type": "object"
          }
        },
        "properties": {
          "events": {
            "description": "Event envelopes produced by a bridged instance's mutation.",
            "items": {
              "$ref": "#/definitions/EventEnvelope"
            },
            "type": "array"
          }
        },
        "required": [
          "events"
        ],
        "title": "PublishEventsRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "published": {
            "description": "Number of well-formed envelopes accepted and fanned out.",
            "format": "uint",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "published"
        ],
        "title": "PublishEventsResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: write one attachment (metadata + base64 bytes).",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::put-attachment",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          }
        },
        "properties": {
          "data": {
            "description": "Standard (padded) base64 of the bytes.",
            "type": "string"
          },
          "meta": {
            "$ref": "#/definitions/AttachmentMeta"
          }
        },
        "required": [
          "data",
          "meta"
        ],
        "title": "PutAttachmentRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OkResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: write one SessionEntry.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::put-entry",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentMessage": {
            "description": "The canonical transcript message union, discriminated by `role`.",
            "oneOf": [
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "role": {
                    "enum": [
                      "user"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "agent": {
                    "description": "The AGENT worker that produced this turn (`claude-code`, `pi`), when one says so. Distinct from `provider`, which names who served the model: two agents can run the same model, and a reader given only a model cannot tell which agent answered. Optional, because the harness's own turns have no agent worker to name.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "error_kind": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/ErrorKind"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "error_message": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "model": {
                    "type": "string"
                  },
                  "native_stop_reason": {
                    "description": "Provider's raw finish reason, passed through untouched.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "provider": {
                    "type": "string"
                  },
                  "role": {
                    "enum": [
                      "assistant"
                    ],
                    "type": "string"
                  },
                  "stop_reason": {
                    "$ref": "#/definitions/StopReason"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  },
                  "usage": {
                    "anyOf": [
                      {
                        "$ref": "#/definitions/Usage"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "warnings": {
                    "description": "Report-and-continue notices (e.g. dropped unsupported param).",
                    "items": {
                      "type": "string"
                    },
                    "type": [
                      "array",
                      "null"
                    ]
                  }
                },
                "required": [
                  "content",
                  "model",
                  "provider",
                  "role",
                  "stop_reason",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "details": {
                    "default": null,
                    "description": "Opaque structured payload kept alongside the rendered content."
                  },
                  "function_call_id": {
                    "description": "Echoes the `function_call` block id this result answers.",
                    "type": "string"
                  },
                  "function_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "default": false,
                    "type": "boolean"
                  },
                  "role": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "function_id",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Escape hatch for app-specific transcript items (system notices, UI markers, attachments, ...).",
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "custom_type": {
                    "description": "App-defined discriminator.",
                    "type": "string"
                  },
                  "details": true,
                  "display": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "role": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch.",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "content",
                  "custom_type",
                  "role",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "ErrorKind": {
            "description": "Coarse error classification carried by failed assistant messages.",
            "enum": [
              "auth_expired",
              "rate_limited",
              "context_overflow",
              "transient",
              "permanent"
            ],
            "type": "string"
          },
          "SessionEntry": {
            "description": "The entry envelope giving each stored item identity, ordering and a parent link (used for forking), discriminated by `kind`.",
            "oneOf": [
              {
                "description": "A transcript message.",
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "message"
                    ],
                    "type": "string"
                  },
                  "message": {
                    "$ref": "#/definitions/AgentMessage"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "id",
                  "kind",
                  "message",
                  "timestamp"
                ],
                "type": "object"
              },
              {
                "description": "Bookkeeping *about* the conversation that is not a message at all (e.g. the harness's compaction record).",
                "properties": {
                  "custom_type": {
                    "type": "string"
                  },
                  "data": {
                    "default": null
                  },
                  "id": {
                    "type": "string"
                  },
                  "kind": {
                    "enum": [
                      "custom"
                    ],
                    "type": "string"
                  },
                  "origin": {
                    "additionalProperties": true,
                    "description": "Opaque writer-supplied correlation (e.g. `{ turn_id }`).",
                    "type": [
                      "object",
                      "null"
                    ]
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "revision": {
                    "default": 0,
                    "description": "Starts at 0; increments on every content update.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "timestamp": {
                    "description": "Milliseconds since epoch (entry creation time).",
                    "format": "int64",
                    "type": "integer"
                  }
                },
                "required": [
                  "custom_type",
                  "id",
                  "kind",
                  "timestamp"
                ],
                "type": "object"
              }
            ]
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "properties": {
          "entry": {
            "$ref": "#/definitions/SessionEntry"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "entry",
          "session_id"
        ],
        "title": "PutEntryRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OkResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: write one SessionMeta.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::put-meta",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AttachmentMeta": {
            "description": "Metadata of one stored attachment. The bytes live in the session's attachment store (`session::get-attachment`), never inline in the transcript: a message references them through a [`ContentBlock::File`] block carrying the same `attachment_id`.",
            "properties": {
              "attachment_id": {
                "description": "Store-generated id (`a_<uuid>`), unique within the session.",
                "type": "string"
              },
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "mime": {
                "description": "MIME type, as uploaded (`application/octet-stream` when unknown).",
                "type": "string"
              },
              "name": {
                "description": "Original filename, as uploaded.",
                "type": "string"
              },
              "session_id": {
                "type": "string"
              },
              "sha256": {
                "description": "Lowercase hex SHA-256 of the bytes.",
                "type": "string"
              },
              "size": {
                "description": "Decoded byte length.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "attachment_id",
              "created_at",
              "mime",
              "name",
              "session_id",
              "sha256",
              "size"
            ],
            "type": "object"
          },
          "SessionKind": {
            "description": "Who a session is for. `user` (the default) is a human-facing chat — what the console lists by default; `automation` is a machine-driven run; `e2e` is a session created by an end-to-end suite (harness-e2e). Consumers filter on it (`session::list` `kinds`); the store never changes behaviour on it.",
            "enum": [
              "user",
              "automation",
              "e2e"
            ],
            "type": "string"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "draft": {
                "description": "Unsent composer input parked on the session (`session::set-draft`), so a client reload restores what the user was typing. Never set by `session::set-meta`; absent when nothing is parked.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "draft_attachments": {
                "description": "Attachments parked with the draft (`session::set-draft` `attachment_ids`), resolved to their stored metadata so a client can rebuild the composer's chips and fetch the bytes back. Absent when none are parked; never copied by `session::fork`.",
                "items": {
                  "$ref": "#/definitions/AttachmentMeta"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "kind": {
                "allOf": [
                  {
                    "$ref": "#/definitions/SessionKind"
                  }
                ],
                "default": "user",
                "description": "Who the session is for (`user` by default, `automation`, `e2e`). Fixed at creation — `session::set-meta` never changes it. Records written before this field existed read back as `user`."
              },
              "message_count": {
                "description": "Number of `kind: \"message\"` entries (custom entries are bookkeeping and not counted).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "metadata": {
                "additionalProperties": true,
                "description": "App-defined; the tenancy hook (e.g. `{ \"owner\": \"u_1\" }`) that `session::list` filters on and every session event carries as `session_metadata`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "session_id": {
                "type": "string"
              },
              "status": {
                "$ref": "#/definitions/SessionStatus"
              },
              "status_reason": {
                "description": "Short lifecycle detail retained on `working`, `done`, and `error`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": "string"
              },
              "updated_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "created_at",
              "description",
              "message_count",
              "session_id",
              "status",
              "title",
              "updated_at"
            ],
            "type": "object"
          },
          "SessionStatus": {
            "description": "Coarse session lifecycle status, rendered directly by consumers.",
            "enum": [
              "idle",
              "working",
              "done",
              "error"
            ],
            "type": "string"
          }
        },
        "properties": {
          "meta": {
            "$ref": "#/definitions/SessionMeta"
          }
        },
        "required": [
          "meta"
        ],
        "title": "PutMetaRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OkResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal store protocol: move a session's active leaf pointer.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::store::set-active-leaf",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "entry_id": {
            "type": "string"
          },
          "session_id": {
            "type": "string"
          }
        },
        "required": [
          "entry_id",
          "session_id"
        ],
        "title": "EntryIdRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OkResponse",
        "type": "object"
      }
    },
    {
      "description": "Replace a message entry's content (optimistic concurrency via expected_revision); calls session::on-message-updated.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "session::update-message",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "ContentBlock": {
            "description": "The atomic unit of message content. A message's `content` is an ordered array of these.",
            "oneOf": [
              {
                "properties": {
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "text"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "attachment_id": {
                    "description": "The stored original this inline copy was made from, when the writer also parked it with `session::put-attachment`. Lets a transcript reader skip the inline bytes and fetch them lazily; model-bound consumers ignore it.",
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "data": {
                    "description": "Base64-encoded image bytes. Empty when the reader asked for `include_image_data: false` and the block carries an `attachment_id`: the original is then one `session::get-attachment` away.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "type"
                ],
                "type": "object"
              },
              {
                "description": "Reference to an attachment kept in the session's attachment store (`session::put-attachment` / `session::get-attachment`). The bytes are never inline; consumers that hand content to a model drop this block and rely on the text expansion that travels beside it.",
                "properties": {
                  "attachment_id": {
                    "description": "Id returned by `session::put-attachment`.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `application/pdf`.",
                    "type": "string"
                  },
                  "name": {
                    "description": "Original filename.",
                    "type": "string"
                  },
                  "size": {
                    "description": "Original byte length.",
                    "format": "uint64",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "type": {
                    "enum": [
                      "file"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attachment_id",
                  "mime",
                  "name",
                  "size",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "signature": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "text": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "thinking"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "text",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "arguments": {
                    "default": null,
                    "description": "Model-produced arguments (JSON)."
                  },
                  "function_id": {
                    "description": "The iii function id to invoke.",
                    "type": "string"
                  },
                  "id": {
                    "description": "Unique per call, echoed by the result.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "function_call"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "function_id",
                  "id",
                  "type"
                ],
                "type": "object"
              },
              {
                "properties": {
                  "content": {
                    "items": {
                      "$ref": "#/definitions/ContentBlock"
                    },
                    "type": "array"
                  },
                  "function_call_id": {
                    "type": "string"
                  },
                  "is_error": {
                    "type": [
                      "boolean",
                      "null"
                    ]
                  },
                  "type": {
                    "enum": [
                      "function_result"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "content",
                  "function_call_id",
                  "type"
                ],
                "type": "object"
              }
            ]
          },
          "Usage": {
            "description": "Token / cost accounting reported by providers.",
            "properties": {
              "cache_read": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cache_write": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "cost_usd": {
                "format": "double",
                "type": [
                  "number",
                  "null"
                ]
              },
              "input": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "output": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reasoning": {
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        },
        "properties": {
          "content": {
            "description": "New content for the message (full replacement).",
            "items": {
              "$ref": "#/definitions/ContentBlock"
            },
            "type": "array"
          },
          "details": {
            "description": "New `details` — only for `function_result` / `custom` messages."
          },
          "entry_id": {
            "type": "string"
          },
          "expected_revision": {
            "description": "Optimistic concurrency: when supplied and it does not match the entry's current revision, nothing is written and `{ updated: false, revision }` returns the current revision.",
            "format": "uint64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          },
          "origin": {
            "additionalProperties": true,
            "description": "Opaque correlation echoed on the event.",
            "type": [
              "object",
              "null"
            ]
          },
          "session_id": {
            "type": "string"
          },
          "usage": {
            "anyOf": [
              {
                "$ref": "#/definitions/Usage"
              },
              {
                "type": "null"
              }
            ],
            "description": "Final token/cost accounting — only for `assistant` messages. Omit for streaming content updates that do not yet have terminal usage."
          }
        },
        "required": [
          "content",
          "entry_id",
          "session_id"
        ],
        "title": "UpdateMessageRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "revision": {
            "description": "The entry's revision after this call (unchanged on a mismatch).",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "updated": {
            "type": "boolean"
          }
        },
        "required": [
          "revision",
          "updated"
        ],
        "title": "UpdateMessageResponse",
        "type": "object"
      }
    }
  ]
}

Search the registry

Find workers, kits and executables, or jump to a page.