session-manager
v1.0.32Durable, reactive, branching store of typed conversation entries with six emitted trigger types.
Install
bash
iii trigger compose::add worker=session-manager@1.0.32Run in your project with the iii engine running. Exact versions are immutable and digest-pinned.
Agent-ready brief for v1.0.32
Install, config, dependencies, readme, skills and API reference, all in one place. Fetch as agent-context.md for an LLM to consume.
Full markdown
The same content rendered as discrete blocks below is exposed as a single markdown document at
/workers/session-manager.md?version=1.0.32. Paste it into an LLM prompt or pipe it through curl from a worker.Install
iii trigger compose::add worker=session-manager@1.0.32Dependencies
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 fires a trigger type consumers bind to, 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 trigger compose::add worker=session-manageriii trigger 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, InitOptions, TriggerRequest};
use serde_json::json;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
let iii = register_worker("ws://localhost:49134", InitOptions::default());
let created = iii.trigger(TriggerRequest {
function_id: "session::create".into(),
payload: json!({ "title": "Weather question", "metadata": { "owner": "u_1" } }),
action: None,
timeout_ms: Some(5_000),
}).await?;
let session_id = created["session_id"].as_str().unwrap().to_string();
iii.trigger(TriggerRequest {
function_id: "session::append".into(),
payload: json!({
"session_id": session_id,
"message": {
"role": "user",
"content": [{ "type": "text", "text": "What's the weather?" }],
"timestamp": 1717800000000_i64
}
}),
action: None,
timeout_ms: Some(5_000),
}).await?;
let transcript = iii.trigger(TriggerRequest {
function_id: "session::messages".into(),
payload: json!({ "session_id": session_id }),
action: None,
timeout_ms: Some(5_000),
}).await?;
println!("{transcript:#?}");
Ok(())
}To render live instead of polling, register a handler function and bind it to a trigger type (the two-step reactive pattern):
use iii_sdk::{IIIError, RegisterFunction, RegisterTriggerInput};
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::<_, IIIError>(json!({ "ok": true }))
}),
);
iii.register_trigger(RegisterTriggerInput {
trigger_type: "session::message-updated".into(),
function_id: "my-ui::on-message-updated".into(),
config: json!({ "session_id": session_id, "roles": ["assistant"] }),
metadata: None,
})?;Streaming an assistant reply uses the same primitives: append an
(initially empty) assistant message, then call session::update-message
as tokens arrive — each update fires session::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 worker info 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.
Custom trigger types
Six trigger types cover every mutation. Each binding's config filters
what reaches the handler; all configs additionally accept
metadata — a subset-equality match against SessionMeta.metadata
(the tenancy hook, e.g. { "owner": "u_1" }). Malformed configs are
rejected at registration.
| Trigger type | Fires when | Config filters |
|---|---|---|
session::created |
A session is created (create / ensure / fork) | metadata |
session::message-added |
An entry is appended | session_id, roles, metadata |
session::message-updated |
A message's content changes (streaming deltas) | session_id, roles, metadata |
session::status-changed |
Status moves between idle/working/done/error | session_id, metadata |
session::meta-updated |
Title/description/metadata change | session_id, metadata |
session::deleted |
A session and its entries are removed | session_id, metadata |
Delivery is fire-and-forget, at-least-once, and unordered — reconcile
message updates by revision (keep the highest) and transcript order
by the parent chain, never by arrival order.
Storage adapters
Two adapters, selected by an adapter block (a name plus a nested
config):
fs(default) — one append-only JSONL file per session underdata_dir(.jsonl meta/entry/leafrecords, replayed last-wins on startup, file removed on session delete. This is the durable, single-instance setup. An append is oneappendrecord (entry, leaf and metadata together) with acommitmarker 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 adata_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 internalsession::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 delivers to its own
subscribers and forwards an envelope to every attached bridged
instance over its internal session::store::events feed; each bridge
re-emits through its local trigger types with its own subscribers'
filters. With several bridged instances attached to one main, a
mutation made anywhere reaches every instance's subscribers exactly
once. (Consequence: an originator's own subscribers hear events after
the round trip through the main — same at-least-once, unordered
contract as always.)
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 binds a
configuration trigger 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::* triggers so open subscribers (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 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
cargo test --test bdd -- --tags @engine # requires a running `iii`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
trigger fan-out, 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); fires session::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; fires session::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; fires session::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` and every trigger config can filter on.",
"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` and every trigger config can filter on.",
"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; fires session::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; fires session::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` and every trigger config can filter on.",
"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 fired `session::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); fires session::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` and every trigger config can filter on.",
"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` and every trigger config can filter on.",
"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` and every trigger config can filter on.",
"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": "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": {
"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"
]
},
"cursor": {
"description": "Opaque pagination cursor from a previous response.",
"type": [
"string",
"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_trigger` 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_trigger` 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 subscribers) 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": "Internal `session::on-config-change` trigger payload. The handler re-fetches the authoritative configuration, so this carries 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": "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; fires session::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` and every trigger config can filter on.",
"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; fires session::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` and every trigger config can filter on.",
"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` and every trigger config can filter on.",
"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` and every trigger config can filter on.",
"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 store protocol: ingest a bridged instance's event envelopes and fan them out to local subscribers and every attached bridge.",
"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. `session_metadata` rides along so `metadata` filters keep working at every edge (the spec payloads do not carry it).",
"properties": {
"payload": {
"description": "The spec payload for that trigger type."
},
"session_metadata": {
"additionalProperties": true,
"description": "`SessionMeta.metadata` as of the mutation.",
"type": [
"object",
"null"
]
},
"trigger_type": {
"description": "One of the six public trigger type ids.",
"type": "string"
}
},
"required": [
"payload",
"trigger_type"
],
"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` and every trigger config can filter on.",
"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); fires session::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"
}
}
],
"triggers": [
{
"description": "A new session exists (via session::create or session::fork).",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Config accepted by `session::created` bindings. The spec defines no filters for this type beyond the universal `metadata` match.",
"properties": {
"metadata": {
"additionalProperties": true,
"description": "Equality match against `SessionMeta.metadata`: every key given here must equal the stored value (subset match).",
"type": [
"object",
"null"
]
}
},
"title": "CreatedBindingConfig",
"type": "object"
},
"metadata": {},
"name": "session::created",
"return_schema": {}
},
{
"description": "A session and its entries were removed.",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Config accepted by `session::status-changed`, `session::meta-updated` and `session::deleted` bindings.",
"properties": {
"metadata": {
"additionalProperties": true,
"description": "Equality match against `SessionMeta.metadata` (subset match).",
"type": [
"object",
"null"
]
},
"session_id": {
"description": "Only deliver events for this session.",
"type": [
"string",
"null"
]
}
},
"title": "SessionBindingConfig",
"type": "object"
},
"metadata": {},
"name": "session::deleted",
"return_schema": {}
},
{
"description": "A message entry was appended to a session.",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"definitions": {
"Role": {
"description": "Message role discriminator.",
"enum": [
"user",
"assistant",
"function_result",
"custom"
],
"type": "string"
}
},
"description": "Config accepted by `session::message-added` and `session::message-updated` bindings.",
"properties": {
"metadata": {
"additionalProperties": true,
"description": "Equality match against `SessionMeta.metadata` (subset match).",
"type": [
"object",
"null"
]
},
"roles": {
"description": "Only deliver events whose message role is in this list. `kind: \"custom\"` entries carry no role and never match a `roles` filter.",
"items": {
"$ref": "#/definitions/Role"
},
"type": [
"array",
"null"
]
},
"session_id": {
"description": "Only deliver events for this session.",
"type": [
"string",
"null"
]
}
},
"title": "MessageBindingConfig",
"type": "object"
},
"metadata": {},
"name": "session::message-added",
"return_schema": {}
},
{
"description": "A message entry's content changed (e.g. streaming deltas).",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"definitions": {
"Role": {
"description": "Message role discriminator.",
"enum": [
"user",
"assistant",
"function_result",
"custom"
],
"type": "string"
}
},
"description": "Config accepted by `session::message-added` and `session::message-updated` bindings.",
"properties": {
"metadata": {
"additionalProperties": true,
"description": "Equality match against `SessionMeta.metadata` (subset match).",
"type": [
"object",
"null"
]
},
"roles": {
"description": "Only deliver events whose message role is in this list. `kind: \"custom\"` entries carry no role and never match a `roles` filter.",
"items": {
"$ref": "#/definitions/Role"
},
"type": [
"array",
"null"
]
},
"session_id": {
"description": "Only deliver events for this session.",
"type": [
"string",
"null"
]
}
},
"title": "MessageBindingConfig",
"type": "object"
},
"metadata": {},
"name": "session::message-updated",
"return_schema": {}
},
{
"description": "A session's title/description/metadata changed.",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Config accepted by `session::status-changed`, `session::meta-updated` and `session::deleted` bindings.",
"properties": {
"metadata": {
"additionalProperties": true,
"description": "Equality match against `SessionMeta.metadata` (subset match).",
"type": [
"object",
"null"
]
},
"session_id": {
"description": "Only deliver events for this session.",
"type": [
"string",
"null"
]
}
},
"title": "SessionBindingConfig",
"type": "object"
},
"metadata": {},
"name": "session::meta-updated",
"return_schema": {}
},
{
"description": "A session's status changed (idle/working/done/error).",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"description": "Config accepted by `session::status-changed`, `session::meta-updated` and `session::deleted` bindings.",
"properties": {
"metadata": {
"additionalProperties": true,
"description": "Equality match against `SessionMeta.metadata` (subset match).",
"type": [
"object",
"null"
]
},
"session_id": {
"description": "Only deliver events for this session.",
"type": [
"string",
"null"
]
}
},
"title": "SessionBindingConfig",
"type": "object"
},
"metadata": {},
"name": "session::status-changed",
"return_schema": {}
},
{
"description": "Internal: event-envelope feed for bridged session-manager instances. Not for direct consumption — bind the six public session::* types instead.",
"invocation_schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Config accepted by [`STORE_EVENTS`] bindings: none. The feed is unfiltered by design — each bridged instance filters locally.",
"title": "StoreEventsBindingConfig",
"type": "object"
},
"metadata": {},
"name": "session::store::events",
"return_schema": {}
}
]
}