$worker

context-manager

Name: context-manager
Author: iii

v1.1.0

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

iiiverified

332 installs108 in 7d25 today

install

$iii worker add context-manager

binarycontext tokens compaction pruning llm

macOS: arm64 · x64
Linux: arm64 · armv7 · x64
Windows: arm64 · x64 · x86

6functions 0triggers 0skills 2deps v1.1.0version

repoiii-hq/workers

exact versions are immutable; binary and bundle artifacts are digest-pinned.

functions

context::assemble

function

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.

request

messagesone of[]
Full candidate history, oldest first.
one of (4)
variant 1
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
rolestringrequiredenum: user
timestampinteger· int64required
Milliseconds since epoch.
variant 2
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum: assistant
stop_reasonstringrequiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum: function_result
timestampinteger· int64required
Milliseconds since epoch.
variant 4
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum: custom
timestampinteger· int64required
Milliseconds since epoch.
modelobjectrequired
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`.
- idstringrequired
  Model id, e.g. `claude-sonnet-4`.
- limitsany of
  Inline token limits; when present no router lookup happens.
  any of (2)
  variant 1
  context_windowinteger· uint64requiredmin 0
  Total context window in tokens.
  input_limitinteger· uint64min 0
  Usable input budget when distinct from `context_window`.
  max_output_tokensinteger· uint64requiredmin 0
  Maximum output tokens the model can produce per call.
  variant 2
  valuenull
- providerstring
  Provider id, e.g. `anthropic`; disambiguates when a model id exists on multiple providers.
optionsany of
any of (2)
variant 1
allow_compactionboolean
Default true.
allow_pruneboolean
Default true.
lease_keystring
Compaction mutual-exclusion key (e.g. a session id); default: hash of the message set.
previous_summarystring
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.
protected_functionsstring[]
`function_id`s exempt from the normal prune pass. Emergency safety reduction may still replace their oversized results.
request_overhead_tokensinteger· uint64min 0
Estimated tokens for final provider request fields and framing not otherwise represented by the prompt, messages, or tools.
reserved_tokensinteger· uint64min 0
Override the default reserve (`min(20000, 10% of context_window)`).
tail_turnsinteger· uintmin 0
user+assistant pairs always kept verbatim (default 2).
thinking_levelany of
Reserve the model's thinking budget for this tier.
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: minimal, low, medium, high, xhigh
variant 2
valuenull
variant 2
valuenull
system_promptstring
Base system prompt to prepend/merge.
toolsobject[]
Model-facing invocation schemas included in every budget count.
- descriptionstringrequired
- execution_modeany of
  any of (2)
  variant 1
  valuestringenum: parallel, sequential
  variant 2
  valuenull
- labelstring
- namestringrequired
  Invocation surface name (`agent_trigger`, `submit_result`, or a function id in native exposure mode).
- parametersunknown
  JSON Schema for the function parameters.

response

appliedobjectrequired
What the pipeline actually did this call.
- compactedbooleanrequired
- initial_token_countinteger· uint64requiredmin 0
  Full estimated request size before pruning or compaction, including the system prompt, tool schemas, and provider framing overhead.
- prunedbooleanrequired
- pruned_tokensinteger· uint64requiredmin 0
- summarized_head_tokensinteger· uint64min 0
  Unambiguous alias for `tokens_before`; retained separately so callers do not mistake the summarised head for the full pre-compaction request.
- summarystring
  Present when compacted; the caller should persist it and pass it back as `options.previous_summary` (compaction round trip).
- tail_start_indexinteger· uintmin 0
  Present when compacted: index into the request messages where the verbatim tail begins (`null` = everything was summarised).
- tokens_beforeinteger· uint64min 0
  Present when compacted: estimated tokens of the summarised head.
effective_max_output_tokensinteger· uint64requiredmin 0
Effective output allocation used to derive `usable`. This is the router-resolved request limit, not the model catalog ceiling.
messagesone of[]required
Budgeted, ready to send to llm-router.
one of (4)
variant 1
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
rolestringrequiredenum: user
timestampinteger· int64required
Milliseconds since epoch.
variant 2
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum: assistant
stop_reasonstringrequiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum: function_result
timestampinteger· int64required
Milliseconds since epoch.
variant 4
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum: custom
timestampinteger· int64required
Milliseconds since epoch.
model_resolvedstringrequiredenum: inline, router, fallback
How the model limits were resolved.
system_promptstringrequired
token_countinteger· uint64requiredmin 0
Estimated tokens of the returned context, including the system prompt, tools, and request overhead. Always at most `usable`.
usableinteger· uint64requiredmin 0
The budget the context was fit into.

context::compact

function

Summarise the head of a history into a single compaction summary, keeping a recent tail verbatim. Transient: the caller persists the result.

request

messagesone of[]
Full candidate history, oldest first.
one of (4)
variant 1
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
rolestringrequiredenum: user
timestampinteger· int64required
Milliseconds since epoch.
variant 2
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum: assistant
stop_reasonstringrequiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum: function_result
timestampinteger· int64required
Milliseconds since epoch.
variant 4
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum: custom
timestampinteger· int64required
Milliseconds since epoch.
modelobjectrequired
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`.
- idstringrequired
  Model id, e.g. `claude-sonnet-4`.
- limitsany of
  Inline token limits; when present no router lookup happens.
  any of (2)
  variant 1
  context_windowinteger· uint64requiredmin 0
  Total context window in tokens.
  input_limitinteger· uint64min 0
  Usable input budget when distinct from `context_window`.
  max_output_tokensinteger· uint64requiredmin 0
  Maximum output tokens the model can produce per call.
  variant 2
  valuenull
- providerstring
  Provider id, e.g. `anthropic`; disambiguates when a model id exists on multiple providers.
optionsany of
any of (2)
variant 1
lease_keystring
Mutual-exclusion key (e.g. a session id); default: hash of the message set.
preserve_recent_tokensinteger· uint64min 0
Override the adaptive verbatim-tail token budget.
previous_summarystring
Anchor from a prior compaction so summaries converge instead of growing; the summariser updates it rather than starting over.
tail_turnsinteger· uintmin 0
user+assistant pairs kept verbatim (default 2).
variant 2
valuenull

response

one of (4)

variant 1

statusstringrequiredenum: ok
summarystringrequired
tail_start_indexinteger· uintmin 0
Index into the request `messages` where the verbatim tail begins; `null` when everything was summarised.
tokens_afterinteger· uint64requiredmin 0
Estimated tokens of summary + verbatim tail.
tokens_beforeinteger· uint64requiredmin 0
Estimated tokens of the summarised head.
used_prior_summarybooleanrequired

variant 2

statusstringrequiredenum: busy

variant 3

statusstringrequiredenum: empty

variant 4

statusstringrequiredenum: overflow

context::count-tokens

function

Estimate token usage for a set of messages (+ optional invocation schemas / system prompt) vs a model.

request

messagesone of[]
Messages to estimate, oldest first.
one of (4)
variant 1
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
rolestringrequiredenum: user
timestampinteger· int64required
Milliseconds since epoch.
variant 2
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum: assistant
stop_reasonstringrequiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum: function_result
timestampinteger· int64required
Milliseconds since epoch.
variant 4
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum: custom
timestampinteger· int64required
Milliseconds since epoch.
modelall ofrequired
Tokenizer selection; falls back to a generic estimator.
all of (1)
variant 1
idstringrequired
Model id, e.g. `claude-sonnet-4`.
limitsany of
Inline token limits; when present no router lookup happens.
… expand 2 nestedcollapse
any of (2)
variant 1
context_windowinteger· uint64requiredmin 0
Total context window in tokens.
input_limitinteger· uint64min 0
Usable input budget when distinct from `context_window`.
max_output_tokensinteger· uint64requiredmin 0
Maximum output tokens the model can produce per call.
variant 2
valuenull
providerstring
Provider id, e.g. `anthropic`; disambiguates when a model id exists on multiple providers.
system_promptstring
Counted on top of the messages when present.
toolsobject[]
Invocation schema(s) to include in the estimate (typically the single `agent_trigger` entry).
- descriptionstringrequired
- execution_modeany of
  any of (2)
  variant 1
  valuestringenum: parallel, sequential
  variant 2
  valuenull
- labelstring
- namestringrequired
  Invocation surface name (`agent_trigger`, `submit_result`, or a function id in native exposure mode).
- parametersunknown
  JSON Schema for the function parameters.

response

by_roleany of
Breakdown of the message tokens by role (system prompt and tools are not part of any role bucket).
any of (2)
variant 1
assistantinteger· uint64requiredmin 0
custominteger· uint64requiredmin 0
function_resultinteger· uint64requiredmin 0
userinteger· uint64requiredmin 0
variant 2
valuenull
estimatorstringrequiredenum: tokenizer, heuristic
Which estimator produced the count.
tokensinteger· uint64requiredmin 0
Total estimate: messages + system prompt + tools.

context::on-config-change

function

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.

request

idstring
Configuration id that changed (advisory; the handler re-fetches the value).

response

okbooleanrequired

context::on-models-changed

function

Internal: flush the model-budget cache when the router's catalog changes.

request

providerstring

response

okbooleanrequired

context::prune

function

Replace verbose function outputs with placeholders without summarising. A cheaper first pass before compaction.

request

messagesone of[]
Messages to prune, oldest first.
one of (4)
variant 1
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
rolestringrequiredenum: user
timestampinteger· int64required
Milliseconds since epoch.
variant 2
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum: assistant
stop_reasonstringrequiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum: function_result
timestampinteger· int64required
Milliseconds since epoch.
variant 4
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum: custom
timestampinteger· int64required
Milliseconds since epoch.
modelany of
Only used for token math; the heuristic estimator needs no model, so this is optional.
any of (2)
variant 1
idstringrequired
Model id, e.g. `claude-sonnet-4`.
limitsany of
Inline token limits; when present no router lookup happens.
… expand 2 nestedcollapse
any of (2)
variant 1
context_windowinteger· uint64requiredmin 0
Total context window in tokens.
input_limitinteger· uint64min 0
Usable input budget when distinct from `context_window`.
max_output_tokensinteger· uint64requiredmin 0
Maximum output tokens the model can produce per call.
variant 2
valuenull
providerstring
Provider id, e.g. `anthropic`; disambiguates when a model id exists on multiple providers.
variant 2
valuenull
optionsany of
any of (2)
variant 1
max_output_charsinteger· uintmin 0
Per-output verbosity threshold in chars (default 2000): outputs at or under it are never pruned.
min_free_tokensinteger· uint64min 0
Skip the pass entirely when it would free less (default 20000).
protect_recent_tokensinteger· uint64min 0
Newest function-output tokens never pruned (default 40000).
protected_functionsstring[]
`function_id`s whose outputs are never pruned.
variant 2
valuenull

response

messagesone of[]required
Same array with pruned outputs replaced by placeholders — no message or block is ever removed.
one of (4)
variant 1
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
rolestringrequiredenum: user
timestampinteger· int64required
Milliseconds since epoch.
variant 2
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
error_kindany of
… expand 2 nestedcollapse
any of (2)
variant 1
valuestringenum: auth_expired, rate_limited, context_overflow, transient, permanent
variant 2
valuenull
error_messagestring
modelstringrequired
native_stop_reasonstring
Provider's raw finish reason, passed through untouched.
providerstringrequired
rolestringrequiredenum: assistant
stop_reasonstringrequiredenum: end, length, function_call, aborted, error
Why an assistant message stopped generating.
timestampinteger· int64required
Milliseconds since epoch.
usageany of
… expand 2 nestedcollapse
any of (2)
variant 1
cache_readinteger· uint64min 0
cache_writeinteger· uint64min 0
cost_usdnumber· double
inputinteger· uint64min 0
outputinteger· uint64min 0
reasoninginteger· uint64min 0
variant 2
valuenull
warningsstring[]
Report-and-continue notices (e.g. dropped unsupported param).
variant 3
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
detailsunknown
Opaque structured payload kept alongside the rendered content.
function_call_idstringrequired
Echoes the `function_call` block id this result answers.
function_idstringrequired
is_errorboolean
rolestringrequiredenum: function_result
timestampinteger· int64required
Milliseconds since epoch.
variant 4
contentone of[]required
… expand 5 nestedcollapse
one of (5)
variant 1
textstringrequired
typestringrequiredenum: text
variant 2
datastringrequired
Base64-encoded image bytes.
mimestringrequired
MIME type, e.g. `image/png`.
typestringrequiredenum: image
variant 3
signaturestring
textstringrequired
typestringrequiredenum: thinking
variant 4
argumentsunknown
Model-produced arguments (JSON).
function_idstringrequired
The iii function id to invoke.
idstringrequired
Unique per call, echoed by the result.
typestringrequiredenum: function_call
variant 5
contentunknown[]required
function_call_idstringrequired
is_errorboolean
typestringrequiredenum: function_result
custom_typestringrequired
App-defined discriminator.
detailsunknown
displaystring
rolestringrequiredenum: custom
timestampinteger· int64required
Milliseconds since epoch.
pruned_partsinteger· uint64requiredmin 0
Outputs replaced with placeholders.
pruned_tokensinteger· uint64requiredmin 0
Estimated tokens freed.
scanned_partsinteger· uint64requiredmin 0
Prunable outputs examined.

triggers

no triggers registered