$worker
context-manager
v1.1.0Turns a raw conversation history plus a target model into a model-ready context — token counting, function-result pruning, and history compaction.
iiiverifiedinstall
$iii worker add context-manager
- macOS: arm64 · x64
- Linux: arm64 · armv7 · x64
- Windows: arm64 · x64 · x86
repoiii-hq/workers
exact versions are immutable; binary and bundle artifacts are digest-pinned.
agent-ready brief for v1.1.0
install + config + dependencies + readme + api reference, all in one place. fetch as agent-context.md for an llm to consume.
full markdown
the same content rendered as discrete blocks below is exposed as a single markdown document at
/workers/context-manager.md. paste it into an llm prompt or pipe it through curl from a worker.install
install
$iii worker add context-manager@1.1.0
dependencies
readme
README.md
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). Summarisation and model-limit
lookups go through llm-router when installed; token counting and pruning
work standalone.
Install
iii worker add context-manageriii worker add fetches the binary and the engine starts the worker on the
next iii start. 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 only
seeds the first registration.
Quickstart
Build a budgeted context before every model call:
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, 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.
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 verbose function outputs
with [output pruned: was ~N tokens] placeholders, no LLM involved), and
context::compact (summarise the head, keep a recent tail verbatim — returns
ok | busy | empty | overflow).
Configuration
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
min_free_tokens: 20000 # skip pruning when it would free less
max_output_chars: 2000 # outputs at or under this size are never pruned
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 callOther details (and the defaults' single source of truth) live in
src/config.rs.
Local development & testing
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 goldensapi reference (json)
agent-api-reference.json
{
"functions": [
{
"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"
]
},
"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"
}
]
},
"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": {
"compacted": {
"type": "boolean"
},
"initial_token_count": {
"description": "Full estimated request size before 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": [
"compacted",
"initial_token_count",
"pruned",
"pruned_tokens"
],
"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"
},
"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"
},
"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",
"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."
},
"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_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"
}
},
"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 verbose 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": {
"max_output_chars": {
"default": null,
"description": "Per-output verbosity threshold in chars (default 2000): outputs at or under it are never pruned.",
"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 never pruned (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"
]
}
},
"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": []
}