# context-manager

> Turns a raw conversation history plus a target model into a model-ready context — token counting, function-result pruning, and history compaction.

| field | value |
|-------|-------|
| version | 1.1.6 |
| type | binary |
| license | Apache-2.0 |
| repo | https://github.com/iii-hq/workers |
| supported_targets | aarch64-apple-darwin, x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu, x86_64-unknown-linux-musl, armv7-unknown-linux-gnueabihf |
| author | iii |

## installation

```sh
iii trigger compose::add worker=context-manager@1.1.6
```

## dependencies

- `configuration` @ `0.x`
- `llm-router` @ `^1.4.12`

## readme

# context-manager

Turns a raw conversation history plus a target model into a **model-ready
context**: a system prompt and an ordered message list that fits inside the
model's usable token budget. It owns *what the model sees this turn* — token
counting, function-result pruning, and history compaction (summarisation) —
and nothing else. It is stateless with respect to conversation storage: pass
messages in, get results back, persist them yourself (or with
[`session-manager`](https://github.com/iii-hq/workers/tree/main/session-manager)). Summarisation and model-limit
lookups go through `llm-router` when installed; token counting and pruning
work standalone.

## Install

```bash
iii trigger compose::add worker=context-manager
```

`iii trigger compose::add` declares the worker in `worker-compose.yaml` and
starts it as part of the Compose project. Runtime configuration lives in the `configuration` worker
(enabled by default in the engine): at boot the worker registers its schema and
fetches the authoritative value, and it hot-reloads on change — every field,
with no restart (`summarizer_timeout_ms` is read per call; a `lease_dir` change
rebuilds and swaps the lease store). An optional `--config <file>.yaml` only
seeds the first registration.

## Quickstart

Build a budgeted context before every model call:

```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 result = iii.trigger(TriggerRequest {
        function_id: "context::assemble".into(),
        payload: json!({
            "messages": [
                { "role": "user", "content": [{ "type": "text", "text": "hi" }], "timestamp": 1 }
            ],
            // Inline limits keep the call standalone; pass only `id`/`provider`
            // to resolve limits through llm-router instead.
            "model": { "id": "claude-sonnet-4",
                       "limits": { "context_window": 200000, "max_output_tokens": 8000 } },
            "system_prompt": "You are a helpful assistant."
        }),
        action: None,
        timeout_ms: Some(30_000),
    }).await?;

    // -> { system_prompt, messages, token_count, usable, model_resolved,
    //      applied: { pruned, pruned_tokens, capped_parts, capped_tokens,
    //                 compacted, summary?, tail_start_index? } }
    println!("{result:#?}");
    Ok(())
}
```

The compaction round trip: when `applied.compacted` is true, **persist
`applied.summary`** and the boundary your storage maps `applied.tail_start_index`
to. On later calls pass only the post-compaction window as `messages` plus the
stored summary as `options.previous_summary` — the summary is rendered into the
system prompt under `# Conversation summary`, and any further compaction
*updates* it instead of starting over. Callers that skip persistence stay
correct at the cost of one summariser call per over-budget request.

Before token accounting, `context::assemble` normalizes images in its cloned
model-facing view. A known catalog model receives placeholders unless it
explicitly declares vision support. For a known vision model, tool images age
after the next assistant response and user images age when a later user turn
begins after a response. Inline limits and unresolved models keep images. Live
images cost a fixed 4,096-token heuristic budget; base64 bytes are never counted
as text. The caller's transcript is unchanged.

Before pruning or compaction runs, assemble unconditionally caps any message-level
or inline function result over `max_result_tokens` (default 20000; 0 disables the
pass) to a bounded `[…result capped: was ~N tokens; middle omitted; re-call
{function_id} with narrower arguments if the omitted middle is needed]` head+tail
view. Text uses provider-visible newline separators and each image costs the fixed
4,096-token allowance — see Configuration below.

Every successful `context::assemble` response satisfies `token_count <= usable`.
Callers should include the complete `tools` array and set
`options.request_overhead_tokens` for response-format and provider-specific request
fields. If ordinary pruning and compaction are insufficient, assembly replaces
oversized function results in its model-facing copy with bounded references to the
full result retained in the session transcript. Requests that still cannot fit fail
with `context/overflow`; callers must not issue a provider request in that case.

The other three functions: `context::count-tokens` (estimate messages + tools +
system prompt vs a model), `context::prune` (replace eligible old function outputs
with `[output of {function_id} pruned: was ~N tokens; re-call it if still
needed]` placeholders, no LLM involved), and `context::compact` (summarise the
head, keep a recent tail verbatim — returns `ok | busy | empty | overflow`).

## Configuration

```yaml
reserved_tokens_cap: 20000     # default reserve = min(cap, pct% of context window)
reserved_pct: 10
tail_turns: 2                  # user+assistant pairs kept verbatim by compaction
protect_recent_tokens: 40000   # newest function-output tokens never pruned
decay_user_turns: 0            # prune after this many subsequent user turns; 0 disables decay
protected_user_turns: 2        # recent user turns exempt from normal pruning; 0 disables this guard
min_free_tokens: 20000         # skip pruning when it would free less
max_output_chars: 2000         # larger outputs are immediately eligible; smaller ones may decay
max_result_tokens: 20000       # per-result ceiling for assemble's unconditional cap pass; 0 disables
lease_ttl_secs: 300            # compaction mutual-exclusion lease TTL
allow_fallback_limits: true    # conservative 8192/1024 when limits can't resolve
summarizer_timeout_ms: 320000  # outer budget for one router::chat summariser call
```

Other details (and the defaults' single source of truth) live in
[`src/config.rs`](src/config.rs).

## Local development & testing

```bash
cargo test                          # unit + BDD (engine scenarios soft-skip)
cargo test --test bdd -- --tags @pure    # no engine required
UPDATE_GOLDENS=1 cargo test --test schemas   # regenerate wire-schema goldens
```

## api reference

```json
{
  "functions": [
    {
      "description": "Serve the context-manager worker's injected console UI assets (content function for its console:script / console:style triggers).",
      "metadata": {
        "internal": true
      },
      "name": "context-manager::ui-content",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Input of the content function: the console asks for one asset by path.",
        "properties": {
          "path": {
            "description": "The asset path from the trigger config (e.g. `state/page.js`).",
            "type": "string"
          }
        },
        "required": [
          "path"
        ],
        "title": "UiContentInput",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Output of the content function.",
        "properties": {
          "content": {
            "description": "The asset source, verbatim.",
            "type": "string"
          },
          "content_type": {
            "description": "MIME type the console should serve the asset with.",
            "type": "string"
          }
        },
        "required": [
          "content",
          "content_type"
        ],
        "title": "UiContentResult",
        "type": "object"
      }
    },
    {
      "description": "Build the model-ready context (system prompt + budgeted messages) from a history; applies prune and/or compaction as needed to fit the model's usable token budget.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "context::assemble",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentFunction": {
            "description": "An invocation-surface schema entry (README.md § AgentFunction) — accepted by `context::count-tokens` so callers can include the `agent_trigger` schema in their estimate.",
            "properties": {
              "description": {
                "type": "string"
              },
              "execution_mode": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/ExecutionMode"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "label": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "description": "Invocation surface name (`agent_trigger`, `submit_result`, or a function id in native exposure mode).",
                "type": "string"
              },
              "parameters": {
                "default": null,
                "description": "JSON Schema for the function parameters."
              }
            },
            "required": [
              "description",
              "name"
            ],
            "type": "object"
          },
          "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, ...). No provider wire mapping — `context::assemble` excludes these from the model-facing list.",
                "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"
              }
            ]
          },
          "AssembleOptions": {
            "properties": {
              "allow_compaction": {
                "default": null,
                "description": "Default true.",
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "allow_prune": {
                "default": null,
                "description": "Default true.",
                "type": [
                  "boolean",
                  "null"
                ]
              },
              "lease_key": {
                "default": null,
                "description": "Compaction mutual-exclusion key (e.g. a session id); default: hash of the message set.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "max_result_tokens": {
                "default": null,
                "description": "Per-result cap override for this call; `null` uses the worker config (default 20000), `0` disables the cap pass.",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "previous_summary": {
                "default": null,
                "description": "Persisted summary from a prior compaction (see the spec's \"The compaction round trip\"); rendered into the system prompt and used as the anchor if compaction triggers again.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "protected_functions": {
                "default": null,
                "description": "`function_id`s exempt from the normal prune pass. Emergency safety reduction may still replace their oversized results.",
                "items": {
                  "type": "string"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "request_overhead_tokens": {
                "default": null,
                "description": "Estimated tokens for final provider request fields and framing not otherwise represented by the prompt, messages, or tools.",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "reserved_tokens": {
                "default": null,
                "description": "Override the default reserve (`min(20000, 10% of context_window)`).",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "tail_turns": {
                "default": null,
                "description": "user+assistant pairs always kept verbatim (default 2).",
                "format": "uint",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "thinking_level": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/ThinkingLevel"
                  },
                  {
                    "type": "null"
                  }
                ],
                "default": null,
                "description": "Reserve the model's thinking budget for this tier."
              }
            },
            "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"
          },
          "ExecutionMode": {
            "enum": [
              "parallel",
              "sequential"
            ],
            "type": "string"
          },
          "ModelInput": {
            "description": "How callers identify the target model (context-manager.md § Model input). Inline `limits` keep the call standalone; `id`/`provider` alone defer limit resolution to `router::models::budget`.",
            "properties": {
              "id": {
                "description": "Model id, e.g. `claude-sonnet-4`.",
                "type": "string"
              },
              "limits": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/ModelLimits"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Inline token limits; when present no router lookup happens."
              },
              "provider": {
                "description": "Provider id, e.g. `anthropic`; disambiguates when a model id exists on multiple providers.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id"
            ],
            "type": "object"
          },
          "ModelLimits": {
            "description": "Token limits a caller may supply inline to stay fully standalone.",
            "properties": {
              "context_window": {
                "description": "Total context window in tokens.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "input_limit": {
                "description": "Usable input budget when distinct from `context_window`.",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "max_output_tokens": {
                "description": "Maximum output tokens the model can produce per call.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "context_window",
              "max_output_tokens"
            ],
            "type": "object"
          },
          "StopReason": {
            "description": "Why an assistant message stopped generating.",
            "enum": [
              "end",
              "length",
              "function_call",
              "aborted",
              "error"
            ],
            "type": "string"
          },
          "ThinkingLevel": {
            "description": "Reasoning-effort tier; levels map to provider-native knobs via `Model.thinking_budgets`.",
            "enum": [
              "minimal",
              "low",
              "medium",
              "high",
              "xhigh"
            ],
            "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": "Full candidate history, oldest first.",
            "items": {
              "$ref": "#/definitions/AgentMessage"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "model": {
            "$ref": "#/definitions/ModelInput"
          },
          "options": {
            "anyOf": [
              {
                "$ref": "#/definitions/AssembleOptions"
              },
              {
                "type": "null"
              }
            ]
          },
          "parts": {
            "additionalProperties": {
              "type": "string"
            },
            "default": null,
            "description": "Named auxiliary texts to count individually with the same estimator. Counted in `breakdown.by_part` only; never added to the assembled context.",
            "type": [
              "object",
              "null"
            ]
          },
          "system_prompt": {
            "default": null,
            "description": "Base system prompt to prepend/merge.",
            "type": [
              "string",
              "null"
            ]
          },
          "tools": {
            "default": null,
            "description": "Model-facing invocation schemas included in every budget count.",
            "items": {
              "$ref": "#/definitions/AgentFunction"
            },
            "type": [
              "array",
              "null"
            ]
          }
        },
        "required": [
          "model"
        ],
        "title": "AssembleRequest",
        "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, ...). No provider wire mapping — `context::assemble` excludes these from the model-facing list.",
                "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"
              }
            ]
          },
          "Applied": {
            "description": "What the pipeline actually did this call.",
            "properties": {
              "capped_parts": {
                "description": "Results rewritten by the unconditional per-result cap pass.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "capped_tokens": {
                "description": "Estimated tokens freed by the cap pass.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "compacted": {
                "type": "boolean"
              },
              "initial_token_count": {
                "description": "Full estimated request size before capping, pruning, or compaction, including the system prompt, tool schemas, and provider framing overhead.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "pruned": {
                "type": "boolean"
              },
              "pruned_tokens": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "summarized_head_tokens": {
                "description": "Unambiguous alias for `tokens_before`; retained separately so callers do not mistake the summarised head for the full pre-compaction request.",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "summary": {
                "description": "Present when compacted; the caller should persist it and pass it back as `options.previous_summary` (compaction round trip).",
                "type": [
                  "string",
                  "null"
                ]
              },
              "tail_start_index": {
                "description": "Present when compacted: index into the request messages where the verbatim tail begins (`null` = everything was summarised).",
                "format": "uint",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "tokens_before": {
                "description": "Present when compacted: estimated tokens of the summarised head.",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "required": [
              "capped_parts",
              "capped_tokens",
              "compacted",
              "initial_token_count",
              "pruned",
              "pruned_tokens"
            ],
            "type": "object"
          },
          "AssembleBreakdown": {
            "description": "Where the returned `token_count` sits, by category — the same sums the pipeline already maintains, exposed so callers can render a context breakdown without re-counting: `token_count` equals the by_role sum plus `system_prompt_tokens`, `tools_tokens`, and the request overhead.",
            "properties": {
              "by_part": {
                "additionalProperties": {
                  "format": "uint64",
                  "minimum": 0,
                  "type": "integer"
                },
                "description": "Per-part estimates for the request's `parts`, keyed by the caller's names; present when the request carried `parts`.",
                "type": [
                  "object",
                  "null"
                ]
              },
              "by_role": {
                "allOf": [
                  {
                    "$ref": "#/definitions/ByRoleTokens"
                  }
                ],
                "description": "The returned messages' tokens by role."
              },
              "estimator": {
                "$ref": "#/definitions/EstimatorName"
              },
              "system_prompt_tokens": {
                "description": "Estimated tokens of the returned system prompt (any compaction summary section included).",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "tools_tokens": {
                "description": "Estimated tokens of the invocation schemas.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "by_role",
              "estimator",
              "system_prompt_tokens",
              "tools_tokens"
            ],
            "type": "object"
          },
          "ByRoleTokens": {
            "description": "Per-role token breakdown of the `messages` array.",
            "properties": {
              "assistant": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "custom": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "function_result": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "user": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "assistant",
              "custom",
              "function_result",
              "user"
            ],
            "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"
          },
          "EstimatorName": {
            "description": "Which estimator produced the count.",
            "enum": [
              "tokenizer",
              "heuristic"
            ],
            "type": "string"
          },
          "ModelResolvedWire": {
            "description": "How the model limits were resolved.",
            "enum": [
              "inline",
              "router",
              "fallback"
            ],
            "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": {
          "applied": {
            "$ref": "#/definitions/Applied"
          },
          "breakdown": {
            "$ref": "#/definitions/AssembleBreakdown"
          },
          "effective_max_output_tokens": {
            "description": "Effective output allocation used to derive `usable`. This is the router-resolved request limit, not the model catalog ceiling.",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "messages": {
            "description": "Budgeted, ready to send to llm-router.",
            "items": {
              "$ref": "#/definitions/AgentMessage"
            },
            "type": "array"
          },
          "model_resolved": {
            "$ref": "#/definitions/ModelResolvedWire"
          },
          "system_prompt": {
            "type": "string"
          },
          "token_count": {
            "description": "Estimated tokens of the returned context, including the system prompt, tools, and request overhead. Always at most `usable`.",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "usable": {
            "description": "The budget the context was fit into.",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "applied",
          "breakdown",
          "effective_max_output_tokens",
          "messages",
          "model_resolved",
          "system_prompt",
          "token_count",
          "usable"
        ],
        "title": "AssembleResponse",
        "type": "object"
      }
    },
    {
      "description": "Summarise the head of a history into a single compaction summary, keeping a recent tail verbatim. Transient: the caller persists the result.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "context::compact",
      "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, ...). No provider wire mapping — `context::assemble` excludes these from the model-facing list.",
                "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"
              }
            ]
          },
          "CompactOptions": {
            "properties": {
              "lease_key": {
                "default": null,
                "description": "Mutual-exclusion key (e.g. a session id); default: hash of the message set.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "preserve_recent_tokens": {
                "default": null,
                "description": "Override the adaptive verbatim-tail token budget.",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "previous_summary": {
                "default": null,
                "description": "Anchor from a prior compaction so summaries converge instead of growing; the summariser updates it rather than starting over.",
                "type": [
                  "string",
                  "null"
                ]
              },
              "tail_turns": {
                "default": null,
                "description": "user+assistant pairs kept verbatim (default 2).",
                "format": "uint",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "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"
          },
          "ModelInput": {
            "description": "How callers identify the target model (context-manager.md § Model input). Inline `limits` keep the call standalone; `id`/`provider` alone defer limit resolution to `router::models::budget`.",
            "properties": {
              "id": {
                "description": "Model id, e.g. `claude-sonnet-4`.",
                "type": "string"
              },
              "limits": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/ModelLimits"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Inline token limits; when present no router lookup happens."
              },
              "provider": {
                "description": "Provider id, e.g. `anthropic`; disambiguates when a model id exists on multiple providers.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id"
            ],
            "type": "object"
          },
          "ModelLimits": {
            "description": "Token limits a caller may supply inline to stay fully standalone.",
            "properties": {
              "context_window": {
                "description": "Total context window in tokens.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "input_limit": {
                "description": "Usable input budget when distinct from `context_window`.",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "max_output_tokens": {
                "description": "Maximum output tokens the model can produce per call.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "context_window",
              "max_output_tokens"
            ],
            "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": {
            "description": "Full candidate history, oldest first.",
            "items": {
              "$ref": "#/definitions/AgentMessage"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "model": {
            "$ref": "#/definitions/ModelInput"
          },
          "options": {
            "anyOf": [
              {
                "$ref": "#/definitions/CompactOptions"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "model"
        ],
        "title": "CompactRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Discriminated on `status`.",
        "oneOf": [
          {
            "description": "Compaction ran; the caller should persist `summary` and map `tail_start_index` onto its own storage ids.",
            "properties": {
              "status": {
                "enum": [
                  "ok"
                ],
                "type": "string"
              },
              "summary": {
                "type": "string"
              },
              "tail_start_index": {
                "description": "Index into the request `messages` where the verbatim tail begins; `null` when everything was summarised.",
                "format": "uint",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "tokens_after": {
                "description": "Estimated tokens of summary + verbatim tail.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "tokens_before": {
                "description": "Estimated tokens of the summarised head.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "used_prior_summary": {
                "type": "boolean"
              }
            },
            "required": [
              "status",
              "summary",
              "tokens_after",
              "tokens_before",
              "used_prior_summary"
            ],
            "type": "object"
          },
          {
            "description": "A compaction lease is held; the caller may retry.",
            "properties": {
              "status": {
                "enum": [
                  "busy"
                ],
                "type": "string"
              }
            },
            "required": [
              "status"
            ],
            "type": "object"
          },
          {
            "description": "Nothing to compact.",
            "properties": {
              "status": {
                "enum": [
                  "empty"
                ],
                "type": "string"
              }
            },
            "required": [
              "status"
            ],
            "type": "object"
          },
          {
            "description": "The summariser is unavailable or itself overflowed.",
            "properties": {
              "status": {
                "enum": [
                  "overflow"
                ],
                "type": "string"
              }
            },
            "required": [
              "status"
            ],
            "type": "object"
          }
        ],
        "title": "CompactResponse"
      }
    },
    {
      "description": "Estimate token usage for a set of messages (+ optional invocation schemas / system prompt) vs a model.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "context::count-tokens",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "AgentFunction": {
            "description": "An invocation-surface schema entry (README.md § AgentFunction) — accepted by `context::count-tokens` so callers can include the `agent_trigger` schema in their estimate.",
            "properties": {
              "description": {
                "type": "string"
              },
              "execution_mode": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/ExecutionMode"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "label": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "description": "Invocation surface name (`agent_trigger`, `submit_result`, or a function id in native exposure mode).",
                "type": "string"
              },
              "parameters": {
                "default": null,
                "description": "JSON Schema for the function parameters."
              }
            },
            "required": [
              "description",
              "name"
            ],
            "type": "object"
          },
          "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, ...). No provider wire mapping — `context::assemble` excludes these from the model-facing list.",
                "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"
          },
          "ExecutionMode": {
            "enum": [
              "parallel",
              "sequential"
            ],
            "type": "string"
          },
          "ModelInput": {
            "description": "How callers identify the target model (context-manager.md § Model input). Inline `limits` keep the call standalone; `id`/`provider` alone defer limit resolution to `router::models::budget`.",
            "properties": {
              "id": {
                "description": "Model id, e.g. `claude-sonnet-4`.",
                "type": "string"
              },
              "limits": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/ModelLimits"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Inline token limits; when present no router lookup happens."
              },
              "provider": {
                "description": "Provider id, e.g. `anthropic`; disambiguates when a model id exists on multiple providers.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id"
            ],
            "type": "object"
          },
          "ModelLimits": {
            "description": "Token limits a caller may supply inline to stay fully standalone.",
            "properties": {
              "context_window": {
                "description": "Total context window in tokens.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "input_limit": {
                "description": "Usable input budget when distinct from `context_window`.",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "max_output_tokens": {
                "description": "Maximum output tokens the model can produce per call.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "context_window",
              "max_output_tokens"
            ],
            "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": {
            "description": "Messages to estimate, oldest first.",
            "items": {
              "$ref": "#/definitions/AgentMessage"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "model": {
            "allOf": [
              {
                "$ref": "#/definitions/ModelInput"
              }
            ],
            "description": "Tokenizer selection; falls back to a generic estimator."
          },
          "parts": {
            "additionalProperties": {
              "type": "string"
            },
            "default": null,
            "description": "Named auxiliary texts to count individually with the same estimator (for example the segments a system prompt is built from). Counted in `by_part` only; never added to `tokens`.",
            "type": [
              "object",
              "null"
            ]
          },
          "system_prompt": {
            "default": null,
            "description": "Counted on top of the messages when present.",
            "type": [
              "string",
              "null"
            ]
          },
          "tools": {
            "default": null,
            "description": "Invocation schema(s) to include in the estimate (typically the single `agent_trigger` entry).",
            "items": {
              "$ref": "#/definitions/AgentFunction"
            },
            "type": [
              "array",
              "null"
            ]
          }
        },
        "required": [
          "model"
        ],
        "title": "CountTokensRequest",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "definitions": {
          "ByRoleTokens": {
            "description": "Per-role token breakdown of the `messages` array.",
            "properties": {
              "assistant": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "custom": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "function_result": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "user": {
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "assistant",
              "custom",
              "function_result",
              "user"
            ],
            "type": "object"
          },
          "EstimatorName": {
            "description": "Which estimator produced the count.",
            "enum": [
              "tokenizer",
              "heuristic"
            ],
            "type": "string"
          }
        },
        "properties": {
          "by_part": {
            "additionalProperties": {
              "format": "uint64",
              "minimum": 0,
              "type": "integer"
            },
            "description": "Per-part estimates for the request's `parts`, keyed by the caller's names; present when the request carried `parts`.",
            "type": [
              "object",
              "null"
            ]
          },
          "by_role": {
            "anyOf": [
              {
                "$ref": "#/definitions/ByRoleTokens"
              },
              {
                "type": "null"
              }
            ],
            "description": "Breakdown of the message tokens by role (system prompt and tools are not part of any role bucket)."
          },
          "estimator": {
            "$ref": "#/definitions/EstimatorName"
          },
          "tokens": {
            "description": "Total estimate: messages + system prompt + tools.",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "tools_tokens": {
            "description": "The `tools` share of `tokens`; present when the request carried `tools`.",
            "format": "uint64",
            "minimum": 0,
            "type": [
              "integer",
              "null"
            ]
          }
        },
        "required": [
          "estimator",
          "tokens"
        ],
        "title": "CountTokensResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal: hot-reload context-manager from the authoritative configuration when it changes — rebuilds the compaction lease store on a lease_dir change and swaps the per-call tuning snapshot otherwise.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "context::on-config-change",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Internal `context::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 `context::on-config-change` handler.",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OnConfigChangeResponse",
        "type": "object"
      }
    },
    {
      "description": "Internal: flush the model-budget cache when the router's catalog changes.",
      "metadata": {
        "internal": true,
        "trace_hidden": true
      },
      "name": "context::on-models-changed",
      "request_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "`router::models::changed` payload — `{ provider, count }`. The handler flushes everything regardless, so the fields are advisory only.",
        "properties": {
          "provider": {
            "default": null,
            "type": [
              "string",
              "null"
            ]
          }
        },
        "title": "OnModelsChangedEvent",
        "type": "object"
      },
      "response_schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "description": "Ack returned by the internal `context::on-models-changed` handler.",
        "properties": {
          "ok": {
            "type": "boolean"
          }
        },
        "required": [
          "ok"
        ],
        "title": "OnModelsChangedResponse",
        "type": "object"
      }
    },
    {
      "description": "Replace eligible old function outputs with placeholders without summarising. A cheaper first pass before compaction.",
      "metadata": {
        "trace_hidden": true
      },
      "name": "context::prune",
      "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, ...). No provider wire mapping — `context::assemble` excludes these from the model-facing list.",
                "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"
          },
          "ModelInput": {
            "description": "How callers identify the target model (context-manager.md § Model input). Inline `limits` keep the call standalone; `id`/`provider` alone defer limit resolution to `router::models::budget`.",
            "properties": {
              "id": {
                "description": "Model id, e.g. `claude-sonnet-4`.",
                "type": "string"
              },
              "limits": {
                "anyOf": [
                  {
                    "$ref": "#/definitions/ModelLimits"
                  },
                  {
                    "type": "null"
                  }
                ],
                "description": "Inline token limits; when present no router lookup happens."
              },
              "provider": {
                "description": "Provider id, e.g. `anthropic`; disambiguates when a model id exists on multiple providers.",
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id"
            ],
            "type": "object"
          },
          "ModelLimits": {
            "description": "Token limits a caller may supply inline to stay fully standalone.",
            "properties": {
              "context_window": {
                "description": "Total context window in tokens.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              },
              "input_limit": {
                "description": "Usable input budget when distinct from `context_window`.",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "max_output_tokens": {
                "description": "Maximum output tokens the model can produce per call.",
                "format": "uint64",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "context_window",
              "max_output_tokens"
            ],
            "type": "object"
          },
          "PruneOptions": {
            "properties": {
              "decay_user_turns": {
                "default": null,
                "description": "Prune outputs after this many subsequent user turns. `null` uses worker config (default 0); `0` disables age-based pruning.",
                "format": "uint",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "max_output_chars": {
                "default": null,
                "description": "Per-output verbosity threshold in chars (default 2000). Outputs at or under it can still be pruned after the configured decay age.",
                "format": "uint",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "min_free_tokens": {
                "default": null,
                "description": "Skip the pass entirely when it would free less (default 20000).",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "protect_recent_tokens": {
                "default": null,
                "description": "Newest function-output tokens kept by normal pruning (default 40000).",
                "format": "uint64",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              },
              "protected_functions": {
                "default": null,
                "description": "`function_id`s whose outputs are never pruned.",
                "items": {
                  "type": "string"
                },
                "type": [
                  "array",
                  "null"
                ]
              },
              "protected_user_turns": {
                "default": null,
                "description": "Most recent user turns exempt from normal pruning. `null` uses worker config (default 2); `0` disables only this exemption.",
                "format": "uint",
                "minimum": 0,
                "type": [
                  "integer",
                  "null"
                ]
              }
            },
            "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": {
            "description": "Messages to prune, oldest first.",
            "items": {
              "$ref": "#/definitions/AgentMessage"
            },
            "type": [
              "array",
              "null"
            ]
          },
          "model": {
            "anyOf": [
              {
                "$ref": "#/definitions/ModelInput"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Only used for token math; the heuristic estimator needs no model, so this is optional."
          },
          "options": {
            "anyOf": [
              {
                "$ref": "#/definitions/PruneOptions"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "title": "PruneRequest",
        "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, ...). No provider wire mapping — `context::assemble` excludes these from the model-facing list.",
                "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": "Same array with pruned outputs replaced by placeholders — no message or block is ever removed.",
            "items": {
              "$ref": "#/definitions/AgentMessage"
            },
            "type": "array"
          },
          "pruned_parts": {
            "description": "Outputs replaced with placeholders.",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "pruned_tokens": {
            "description": "Estimated tokens freed.",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          },
          "scanned_parts": {
            "description": "Prunable outputs examined.",
            "format": "uint64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "messages",
          "pruned_parts",
          "pruned_tokens",
          "scanned_parts"
        ],
        "title": "PruneResponse",
        "type": "object"
      }
    }
  ],
  "triggers": []
}
```