# session-manager

> Durable, reactive, branching store of typed conversation entries with six emitted trigger types.

| field | value |
|-------|-------|
| version | 1.0.0 |
| type | binary |
| repo | https://github.com/iii-hq/workers |
| supported_targets | x86_64-apple-darwin, aarch64-apple-darwin, i686-pc-windows-msvc, x86_64-pc-windows-msvc, aarch64-pc-windows-msvc, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-unknown-linux-musl, armv7-unknown-linux-gnueabihf |
| author | iii |

## installation

```sh
iii worker add session-manager@1.0.0
```

## dependencies

- `configuration` @ `^0.19.0`

## readme

# 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](../harness) family drives, and
it is independently useful as a real-time chat store for any app.

## Install

```bash
iii worker add session-manager
```

`iii worker add` fetches the binary, writes a config block into
`~/.iii/config.yaml`, and the engine starts the worker on the next
`iii start`.

## Quickstart

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

```rust
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):

```rust
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 (14 `session::*` functions: lifecycle,
messages, branching/fork) is documented in the spec and on each
function's registered schema — see `iii worker info session-manager`.

## 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 under
  `data_dir` (`<encoded_session_id>.jsonl`): typed `meta` / `entry` /
  `leaf` records, replayed last-wins on startup, file removed on
  session delete. This is the durable, single-instance setup.
- **`bridge`** — this instance keeps all domain logic (idempotency,
  revisions, branching, locks) but stores through a **main** instance
  running its own session-manager (`adapter name: fs`) on another iii
  engine, via the internal `session::store::*` protocol.

Event propagation in a bridge topology: the main is the single fan-out
point. A bridged instance publishes each mutation's events to the main
(`session::store::publish-events`); the main 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.

```yaml
adapter:
  name: fs                                   # fs | bridge
  config:
    data_dir: ~/.iii/data/session-manager    # fs: one <session_id>.jsonl per session

# 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()`](src/config.rs) as `initial_value`.
Optionally pass `--config <path>` to seed from a YAML file instead (one-time,
never overwrites an existing stored value). `${VAR:default}` placeholders in
stored values are expanded by the configuration worker on every read.

## Local development & testing

```bash
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/`](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):
[`architecture/integration.md`](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`](architecture/internals.md) is the
maintainer deep-dive (module map, invariants, storage formats, event
pipeline, testing architecture).

## api reference

```json
{
  "functions": [
    {
      "description": "Append one entry (idempotent on entry_id); fires session::message-added.",
      "metadata": {},
      "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": {
                  "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": {
                  "data": {
                    "description": "Base64-encoded image bytes.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "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": {},
      "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": {
                  "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": {
                  "data": {
                    "description": "Base64-encoded image bytes.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "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": {},
      "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": {},
      "name": "session::create",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "description": {
            "description": "Session description. Default \"\".",
            "type": [
              "string",
              "null"
            ]
          },
          "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": {
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "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 cause, set on `error`, cleared on any other status.",
                "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": {},
      "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": "Idempotently ensure a session with a given id exists; fires session::created only when it creates.",
      "metadata": {},
      "name": "session::ensure",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "properties": {
          "description": {
            "description": "Description applied only when the session is created.",
            "type": [
              "string",
              "null"
            ]
          },
          "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": {
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "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 cause, set on `error`, cleared on any other status.",
                "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": {},
      "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": {
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "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 cause, set on `error`, cleared on any other status.",
                "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": {},
      "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": {
          "GetResponse": {
            "description": "`null` when the session is unknown.",
            "properties": {
              "meta": {
                "$ref": "#/definitions/SessionMeta"
              }
            },
            "required": [
              "meta"
            ],
            "type": "object"
          },
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "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 cause, set on `error`, cleared on any other status.",
                "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 a single entry by id (null when unknown).",
      "metadata": {},
      "name": "session::get-message",
      "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": "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": {
                  "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": {
                  "data": {
                    "description": "Base64-encoded image bytes.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "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": {},
      "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"
          },
          "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"
            ]
          },
          "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": {
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "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 cause, set on `error`, cleared on any other status.",
                "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": "Load the active path as messages with entry ids, oldest first; pagination and role filtering.",
      "metadata": {},
      "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": {
          "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"
            ]
          },
          "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": {
                  "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": {
                  "data": {
                    "description": "Base64-encoded image bytes.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "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"
                  }
                ]
              }
            },
            "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": "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": {},
      "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": "Move the active path to end at a given entry (branch switch).",
      "metadata": {},
      "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": "Update a session's title/description/metadata; fires session::meta-updated.",
      "metadata": {},
      "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": {
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "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 cause, set on `error`, cleared on any other status.",
                "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": {},
      "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 stored as `status_reason` — kept on `error`, cleared on any other status.",
            "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: clear a session's active leaf pointer.",
      "metadata": {},
      "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 every entry of a session.",
      "metadata": {},
      "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": {},
      "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": {},
      "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 SessionEntry (null when unknown).",
      "metadata": {},
      "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": {
                  "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": {
                  "data": {
                    "description": "Base64-encoded image bytes.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "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": {},
      "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": {
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "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 cause, set on `error`, cleared on any other status.",
                "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 entry of a session.",
      "metadata": {},
      "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": {
                  "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": {
                  "data": {
                    "description": "Base64-encoded image bytes.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "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": {},
      "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": {
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "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 cause, set on `error`, cleared on any other status.",
                "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": {},
      "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 SessionEntry.",
      "metadata": {},
      "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": {
                  "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": {
                  "data": {
                    "description": "Base64-encoded image bytes.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "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": {},
      "name": "session::store::put-meta",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "SessionMeta": {
            "description": "A session's metadata record.",
            "properties": {
              "created_at": {
                "description": "Milliseconds since epoch.",
                "format": "int64",
                "type": "integer"
              },
              "description": {
                "type": "string"
              },
              "forked_from": {
                "description": "Source session id when created by `session::fork`.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "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 cause, set on `error`, cleared on any other status.",
                "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": {},
      "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": {},
      "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": {
                  "data": {
                    "description": "Base64-encoded image bytes.",
                    "type": "string"
                  },
                  "mime": {
                    "description": "MIME type, e.g. `image/png`.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "image"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "data",
                  "mime",
                  "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": {
          "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"
          }
        },
        "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": {},
      "metadata": {},
      "name": "session::created",
      "return_schema": {}
    },
    {
      "description": "A session and its entries were removed.",
      "invocation_schema": {},
      "metadata": {},
      "name": "session::deleted",
      "return_schema": {}
    },
    {
      "description": "A message entry was appended to a session.",
      "invocation_schema": {},
      "metadata": {},
      "name": "session::message-added",
      "return_schema": {}
    },
    {
      "description": "A message entry's content changed (e.g. streaming deltas).",
      "invocation_schema": {},
      "metadata": {},
      "name": "session::message-updated",
      "return_schema": {}
    },
    {
      "description": "A session's title/description/metadata changed.",
      "invocation_schema": {},
      "metadata": {},
      "name": "session::meta-updated",
      "return_schema": {}
    },
    {
      "description": "A session's status changed (idle/working/done/error).",
      "invocation_schema": {},
      "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": {},
      "metadata": {},
      "name": "session::store::events",
      "return_schema": {}
    }
  ]
}
```