Workflow
Runs a goal as kanban tickets, one workflow run per phase: explores and designs first (explorers, competing designs, refuters and a planner in one run), plans the tickets as subtasks of one run ticket, starts every wave as a workflow::start run whose nodes are the ticket phases (work, then a check that loops the work back on a fail), reads each run's result when its notification arrives, and loops in bounded rounds until done, dry, stalled, out of rounds or over budget. A code goal gets the dev flow: one worktree per ticket, integration on a run branch, one tests-and-check run per integrated wave, a branch review and a kept branch.
- Model
- Inherited
- Effort
- high
- Extends
- iiibuilt-in
- Icon
- agent
- Color
- green
- Visibility
- Listed
- Composer placeholder
- “Describe the goal, e.g. “Add a CSV export to the reports page, with tests””
No skills preloaded.
workflow::
startworkflowv0.3.5Schema Run a multi-agent workflow and return {run_id, next} immediately. Declarative DAG: fan-out, barrier/join, durable, crash-resumable. Shape: {"nodes":{"a":{"task":"…"},"b":{"task":"…","reads":"a"}}}; a node omits `model` to run on your model. To get the result make the `harness::observe` call that `next` gives and END YOUR TURN — it arrives as a `[notification]` when the run ends; workers pass `notify`. Never poll workflow::status in a loop.
request - caller_fs_rootstring
Caller's folder. On a call from an agent turn the `workflow::stamp-reply` hook replaces it with the turn's `metadata.fs_scope.root`; the harness refuses `workflow::start` as a binding target and `fp` as a pipe step, since both skip that hook. Every node session runs in it. Omit it to use the harness default folder.
- caller_session_idstring
Orchestrator session, stamped by the `workflow::stamp-reply` hook from the caller's turn; never trusted from the agent.
- default_functionsunknown
Dispatch policy inherited by every node that omits `functions` (same shape); when unset those nodes get everything except `workflow::*`, `configuration::*`, `approval::*`, `harness::hook::*` and `harness::send`.
- idempotency_keystring
Dedupe key; a repeated key returns the original `run_id` instead of launching a duplicate run.
- inputunknown
Any JSON value. Every node without `reads` or `fanout` receives it.
- max_concurrencyinteger· uint32min 0
At most this many node sessions live at once (running, or reserved for a send); further ready nodes wait for a slot. At least 1; unset means no cap.
- nodesobjectrequired
One sub-agent session per node, keyed by node id; an id must not contain `#`, `.` or `/`.
- notifyany of
Completion callback called once when the run reaches a terminal state, instead of polling `workflow::status`.
any of (2)Variant 1- function_idstringrequired
Function id to call on terminal state, e.g. `"myworker::wf-done"`.
- queuestring
Queue for durable delivery; defaults to the worker's `"workflow-notify"` queue.
Variant 2valuenull - outputany of
What the run returns: a node id returns that node's result as is, an array of ids an object keyed by id. A node of a loop, the loop node or a body node, returns its last pass. Omit it to return every node no other node reads (one such node: its result as is).
any of (2)Variant 1any of (2)Variant 1valuestringVariant 2itemsstring[]Variant 2valuenull - titlestring
Display title of the run, trimmed and cut to 80 characters. Omitted on a call from an agent turn, the `workflow::stamp-reply` hook fills it from the call's description.
response - nextunknown
For an agent caller: the `harness::observe` call that delivers the run's outcome to this session. Make it exactly as given, then end the turn.
- run_idstringrequired
workflow::
statusworkflowv0.3.5Schema Return a snapshot of a workflow run (status, per-node state with unstarted nodes as pending, node_errors, node_results, phases, result, result_error), or null if not found. `details: true` adds node_details: label, phase, model, session, timings, live usage and harness status per node (at most 100 nodes). Each call costs a turn: do not poll in a loop; observe `workflow::on-run-completed` with args `{run_id}`, or pass `notify` to workflow::start, to be pushed the outcome.
request - detailsboolean
Also return `node_details` (at most 100 nodes: running first, then pending, failed, cancelled, done). Reads each node's usage and harness status live.
- run_idstringrequired
The `run_id` returned by `workflow::start`.
response any of (2)Variant 1- created_atinteger· int64required
- details_truncatedboolean
`node_details` was cut at 100 nodes.
- node_detailsobject
Only with `details: true`: per-node detail keyed by node uid.
- node_errorsobject
Errors for nodes that failed, keyed by node uid — e.g. "no provider registered for model …". Present so a caller can diagnose a `failed` run without digging into stored state. Omitted when no node carries an error.
- node_resultsobject
Nodes that have a stored result: node uid → result_ref (its key in state). Fetch the value with `workflow::node-result { run_id, node_uid }`. Lets a caller recover partial work from a run that failed partway (the run-level `result` is only set on a Completed run). Omitted when empty.
- nodesobjectrequired
Per-node state keyed by node uid. Definition nodes that have not started are `pending`; an unexpanded fanout is listed once under its node id.
- phasesobject
Node uid counts per definition `phase` (`failed` includes `cancelled`); nodes without a phase are left out. Omitted when empty.
- resultunknown
- result_errorstring
Run-level failure summary (set when `status == failed`).
- run_idstringrequired
- statusstringrequiredenum running, awaiting_nodes, completed, failed, cancelled
- titlestring
The run's display title, when it has one.
- updated_atinteger· int64required
Variant 2valuenullworkflow::
node-resultworkflowv0.3.5Schema Fetch the stored JSON result of one node: `node_uid` is the node id, '{node_id}#{i}' for a fanout item, or '{node_id}#it{k}' for loop pass k ('#it0' is the first pass; the bare id of a node in a loop is its last pass; workflow::status lists the done passes under `node_results`). Returns {result: null} when that node is not done.
request - node_uidstringrequired
The node id, `"{node_id}#{i}"` for a fanout item, or `"{node_id}#it{k}"` for loop pass k (`#it0` is the first pass); the bare id of a loop node or body node returns its last pass. `uid` is accepted as an alias.
- run_idstringrequired
The `run_id` returned by `workflow::start`.
response - resultunknown
The node's stored JSON result, or null if the node has not completed (or produced no stored result). Always serialized — even when absent it is an explicit `{ "result": null }`, so callers never special-case a missing key.
workflow::
stopworkflowv0.3.5Schema Cancel a workflow run, cascading harness::stop to each live node session.
request - run_idstringrequired
response - stoppingbooleanrequired
harness::
observeharnessv1.9.14Schema Observe a function for the current harness session: each time it runs, omit `target` to be notified in this session with what it returned, or name a non-harness `target.function_id` to call with it. Pass the function's `args` when it takes them and `filters` on its `input.<field>` to choose calls. Set `lifecycle.expires_in_ms` on every wake except a timer, to how long the work should take; a one-shot wake without it expires after 10 minutes with a notice. Returns `{ observer_id, once }`; a `note` is advice about the observer, which was created either way. Call-target results are discarded and do not return to this session.
request - actionstring
User-facing text saying what happened, shown with each delivery.
- argsobject
Args for the worker that hosts the function, a JSON object; its description says which it takes: cron `{ "expression" }`, database `{ "db", "table"?, "ops"? }`, `harness::on-timer` `{ "in_ms" }` or `{ "at" }` (epoch ms). Omit for a function that takes none.
- conditionsobject[]
Delivery-time gates, in order; each is an iii function answering `{ decision: "allow" | "skip", payload?, reason? }`.
- configunknown
Passed to the condition function AS its `condition_config`: give its fields (e.g. `id`, `expect`) directly, not wrapped in `condition_config`.
- function_idstringrequired
- filtersobject
Which calls reach this observer, a JSON object of explicit operators on the call's fields: `{ "input.scope": { "$eq": "run" } }`.
- function_idstringrequired
The function to observe: `state::on-changed`, `cron::on-tick`, `harness::on-timer`, `database::on-row-changed`, or any other function. What it returns is the event.
- labelstring
A short human label echoed back in the notification text.
- lifecycleany of
When the observer stops delivering; top-level `once` is the shorthand.
any of (2)Variant 1- expires_in_msinteger· int64
Relative deadline: the observer stops this many milliseconds after it was created (the only deadline form). Set it on every wake except a timer, to how long the work should take: if nothing fires by then, the session is woken with a notice. A one-shot wake without it expires after 10 minutes.
- max_firesinteger· uint64min 0
Lifetime delivery budget; the observer is removed on its Nth delivery.
- onceboolean
Remove the observer after its first delivery (same as top-level `once`).
Variant 2valuenull - namespacestring
Where the function is hosted; omitted: this harness's namespace, then `default`, then Compose's.
- onceboolean
Remove the observer after its first delivery; defaults to true for a wake (no `target`) and `harness::on-timer`, false for a call target and `cron::on-tick`.
- targetany of
The function called with each event: `{ function_id, payload?, event_into? }` — the fixed payload and the JSON pointer where the event is injected into it (default `/event`). Omit it to be notified in this session instead. `harness::spawn` is never a valid target.
any of (2)Variant 1- event_intostring
JSON pointer where the event lands inside the payload (default `/event`).
- function_idstringrequired
- payloadunknown
Payload template; the delivered event is injected into it at `event_into`.
Variant 2valuenull
response - notestring
Advisory only — the observer was CREATED. Says what applied by default or what looks suspicious in its wiring (e.g. a filter naming a key someone already wrote). Read it and act on it if it applies.
- observer_idstringrequired
- oncebooleanrequired
The effective `once` flag applied (after the per-function default).
harness::
unobserveharnessv1.9.14Schema Remove an observer the current harness session created (`id` is the observer_id harness::observe returned).
request - idstringrequired
response - removedbooleanrequired
harness::
observers:: listharnessv1.9.14Schema List the observers a session created with harness::observe: observer id, observed function with its args and filters, target (absent = notifies the owner), label, conditions, lifecycle, and fire count. In-turn calls may omit `session_id`.
request - session_idstring
Owner session whose observers to list; in-turn calls may omit it (the calling session is injected).
response - observersobject[]required
- actionstring
Human-readable event text declared as `action`.
- argsunknown
- conditionsobject[]
- configunknown
Passed to the condition function AS its `condition_config`: give its fields (e.g. `id`, `expect`) directly, not wrapped in `condition_config`.
- function_idstringrequired
- created_atinteger· int64required
- expires_atinteger· int64
- filtersunknown
- firesinteger· uint64requiredmin 0
- function_idstring
The observed function.
- labelstring
- max_firesinteger· uint64min 0
- namespacestring
Where the observed function is hosted, when the observer names it.
- observer_idstringrequired
- oncebooleanrequired
- targetstring
The function a delivery calls. Absent for a wake — the delivery notifies the owner session.
harness::
metricsharnessv1.9.14Schema Aggregate durable model usage, function outcomes, and available trace/span observability for the session tree `root_session_id` belongs to (`session_id` is accepted as an alias, and a sub-agent id is resolved to its root). `complete` is true only after every session in the durable tree has reached a terminal turn. Pass `omit_context: true` when you only need the counters and cost: each session's context snapshot is then left out.
request one of (2)Variant 1Empty objectVariant 2Empty objectresponse - by_sessionobject[]required
- by_modelobject[]
The same counters per model that generated a step, ordered by provider then model. Absent when nothing generated, and from a harness that predates it.
- cache_read_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- cache_write_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- cost_usdnumber· doublerequired
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- function_callsinteger· uint64requiredmin 0
- input_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- modelstringrequired
- output_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- providerstringrequired
- reasoning_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- turnsinteger· uint64requiredmin 0
Model steps (assistant messages) this model generated.
- unreported_generationsinteger· uint64min 0
Generations stored with no usage at all: a stream cut before the provider reported, a request refused before a provider saw it, or one still streaming. The transcript does not say which, so none counts as zero: while this is non-zero every counter is a lower bound. Absent when zero.
- cache_read_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- cache_write_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- contextany of
The session's latest per-generation context snapshot (categories, budget, usage) — absent for sessions that have not generated since snapshots landed.
any of (2)Variant 1- categoriesobjectrequired
Where the request's tokens sit. Categories are assembly-time estimates; `hook_guidance` is the measured growth after assembly (pre-generate hook appends and orphan-repair patches), 0 when the request left assembly unchanged.
Show 6 nestedHide nested
- hook_guidanceinteger· uint64min 0
- messagesobjectrequired
Estimated tokens of the assembled window's messages, by role.
Show 4 nestedHide nested
- assistantinteger· uint64requiredmin 0
- custominteger· uint64requiredmin 0
- function_resultinteger· uint64requiredmin 0
- userinteger· uint64requiredmin 0
- overheadinteger· uint64requiredmin 0
Provider framing plus response_format / provider_options fields.
- skillsinteger· uint64min 0
Selected skill bodies contained in the system prompt.
- system_promptinteger· uint64requiredmin 0
Final assembled system prompt excluding tokens attributed to `skills`: identity, per-step aids, and any compaction summary section.
- toolsinteger· uint64requiredmin 0
Function schemas exposed to the model.
- compactedbooleanrequired
The context carries a conversation summary: compacted on this step, or anchored on an earlier compaction entry (a previous step, the console's `/compact`). The summary's tokens count in `system_prompt`.
- effective_max_output_tokensinteger· uint64requiredmin 0
Output allocation `usable` was derived against.
- estimatorstring
Which estimator produced the numbers (`heuristic` until the context-manager resolves a real tokenizer). Absent when the context-manager predates the breakdown response.
- freeinteger· uint64requiredmin 0
- modelstringrequired
- prefix_divergencesobject[]
Already-sent rows this session's requests rewrote, newest last (at most [`MAX_PREFIX_DIVERGENCES`]), carried from step to step.
Show 9 nestedHide nested
- cache_readinteger· uint64min 0
`usage.cache_read` of the rewriting request: what the provider still reused.
- call_idstring
- causestring
What rewrote the row, as far as the harness can tell: `prune` (context-manager pruned or reduced function results to fit the budget that step) or `system_prompt` (row 0: a compaction summary or a prompt change).
- indexinteger· uint64min 0
First row (0 = system prompt, then one per message) that differs from the session's previous request. Absent when only the provider's wire mapping changed.
- prev_leninteger· uint64min 0
Rows the previous request carried.
- provider_notestring
The provider's own wire-level finding, cause included, when it reported one (a final-message warning starting with [`PROVIDER_PREFIX_NOTE`]).
- rolestring
- stepinteger· uint64requiredmin 0
- turn_idstringrequired
- prompt_sections_fallbackstring
Why no shared prefix went out: `disabled` (config), `no_stable_prefix` (empty identity prompt) or `prefix_rewritten` (a pre_generate hook replaced the prompt head; its prompt still wins, it just shares nothing).
- prompt_surface_digeststring
Identity of the shared prompt prefix this generation went out with (`sha256:` of the stable section) — present only when the request carried `system_sections`. A local identity, never a provider hit; `usage.cache_read` is the reuse signal.
- providerstring
- session_cost_usdnumber· double
Running cost of the whole session in USD, accumulated across every generation step. `usage.cost_usd` is one step's bill — on providers with steep cache discounts the per-step number swings two orders of magnitude, so a chip showing it alone reads as a bouncing total.
- session_idstringrequired
- stepinteger· uint64requiredmin 0
- summarized_head_tokensinteger· uint64min 0
Size of the history that summary replaced.
- timestampinteger· int64required
- totalinteger· uint64requiredmin 0
Final request estimate: categories plus post-assembly growth.
- turn_idstringrequired
- usableinteger· uint64requiredmin 0
The input budget the window was fit into.
- usageany of
Actual provider usage for this generation, stamped after the terminal frame; absent when the provider returned none (or the generation never completed).
Show 2 nestedHide nested
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 2valuenull
Variant 2valuenull - cost_usdnumber· doublerequired
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- depthinteger· uint32requiredmin 0
- function_call_errorsinteger· uint64requiredmin 0
- function_callsinteger· uint64requiredmin 0
- input_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- output_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- parent_session_idstring
- reasoning_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- session_idstringrequired
- turnsinteger· uint64requiredmin 0
- unreported_generationsinteger· uint64min 0
Generations stored with no usage at all: a stream cut before the provider reported, a request refused before a provider saw it, or one still streaming. The transcript does not say which, so none counts as zero: while this is non-zero every counter is a lower bound. Absent when zero.
- completebooleanrequired
- root_session_idstringrequired
- totalsobjectrequired
- by_modelobject[]
The same counters per model that generated a step, ordered by provider then model. Absent when nothing generated, and from a harness that predates it.
- cache_read_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- cache_write_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- cost_usdnumber· doublerequired
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- function_callsinteger· uint64requiredmin 0
- input_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- modelstringrequired
- output_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- providerstringrequired
- reasoning_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- turnsinteger· uint64requiredmin 0
Model steps (assistant messages) this model generated.
- unreported_generationsinteger· uint64min 0
Generations stored with no usage at all: a stream cut before the provider reported, a request refused before a provider saw it, or one still streaming. The transcript does not say which, so none counts as zero: while this is non-zero every counter is a lower bound. Absent when zero.
- cache_read_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- cache_write_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- cost_usdnumber· doublerequired
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- function_call_errorsinteger· uint64requiredmin 0
- function_callsinteger· uint64requiredmin 0
- input_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- output_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- reasoning_tokensinteger· uint64requiredmin 0
Summed over the generations that reported usage. One of them may lack this counter and is left out; `null` means none reported it or more than one lacked it — never a measured zero, so the key is always present and a reader can tell the two apart. A generation with no usage at all is counted in `unreported_generations` instead and makes this a lower bound.
- sessionsinteger· uint64requiredmin 0
- turnsinteger· uint64requiredmin 0
- unreported_generationsinteger· uint64min 0
Generations stored with no usage at all: a stream cut before the provider reported, a request refused before a provider saw it, or one still streaming. The transcript does not say which, so none counts as zero: while this is non-zero every counter is a lower bound. Absent when zero.
- tracesany of
Trace/span aggregates when the engine's in-memory observability exporter is available. Usage metrics remain available when it is not.
any of (2)Variant 1- by_sessionobject[]required
Show 7 nestedHide nested
- depthinteger· uint32requiredmin 0
- duration_msinteger· uint64requiredmin 0
Elapsed window from the session's first observed span to its last.
- error_span_countinteger· uint64requiredmin 0
- parent_session_idstring
- session_idstringrequired
- span_countinteger· uint64requiredmin 0
- trace_countinteger· uint64requiredmin 0
- duration_msinteger· uint64requiredmin 0
Elapsed window from the first observed span to the last observed span.
- error_span_countinteger· uint64requiredmin 0
- span_countinteger· uint64requiredmin 0
- trace_countinteger· uint64requiredmin 0
Distinct traces across the root session and all descendants.
Variant 2valuenull
harness::
askharnessv1.9.14Schema Ask the user for a decision between discrete options: 1-4 questions, 2-4 options each; the UI adds a free-text "Other" choice, so do not include one. The questions are shown as a clickable card in the chat, your turn ends, and the answer arrives as the user's next message (one `Header: answer` line per question; a skipped question reads `(skipped)`, and a dismissed card sends a notice instead of answers), so do not repeat the questions in text. Not available to sub-agents or structured-output turns.
request - questionsobject[]required1…4 items
1-4 questions shown together on one card; the answer arrives as the user's next message, one line per question.
- headerstringrequiredmin 1 chars
Short chip label such as `Approach`; prefixes the answer line (`Approach: <label>`). No length limit: the card shows a long one with an ellipsis and the whole text on hover.
- multi_selectboolean
Let the user pick several options (checkboxes) instead of one.
- optionsobject[]required2…4 items
2-4 discrete choices; do not add an "Other" option, the UI adds a free-text one.
- descriptionstring
Optional one-line explanation shown under the label.
- labelstringrequired1…80 chars
The choice as the user sees and sends it, 1-80 characters, unique within its question.
- questionstringrequiredmin 1 chars
The full question text shown above the options.
response - question_idstringrequired
The function-call id of this ask.
- questionsobject[]required
The questions as shown, in request order.
- headerstringrequiredmin 1 chars
Short chip label such as `Approach`; prefixes the answer line (`Approach: <label>`). No length limit: the card shows a long one with an ellipsis and the whole text on hover.
- multi_selectboolean
Let the user pick several options (checkboxes) instead of one.
- optionsobject[]required2…4 items
2-4 discrete choices; do not add an "Other" option, the UI adds a free-text one.
- descriptionstring
Optional one-line explanation shown under the label.
- labelstringrequired1…80 chars
The choice as the user sees and sends it, 1-80 characters, unique within its question.
- questionstringrequiredmin 1 chars
The full question text shown above the options.
- session_idstringrequired
- statusone ofrequiredone of (1)Variant 1valuestringenum awaiting_answer
- turn_idstringrequired
The turn that asked; once the session's current turn differs, the question has been answered.
state::
setstatev0.23.3Schema Store or write a value at a key in a state scope; it persists across sessions
request - keystringrequired
Identifier for the value within the scope.
- scopestringrequired
Namespace that groups related keys (e.g. `users`, `orders`).
- valueunknownrequired
Arbitrary JSON value to store. Replaces any existing value at `scope`/`key`.
response - new_valueunknownrequired
The value after the update
- old_valueunknown
Previous value (if it existed).
state::
getstatev0.23.3Schema Read the value stored at a key in a state scope
request - keystringrequired
Identifier for the value within the scope.
- scopestringrequired
Namespace that groups related keys.
response valuestringkanban::
config:: infokanbanv0.2.4Schema Resolved kanban settings: the folder the board file lives in, the columns, and the numbering prefix.
request Empty objectresponse - agents_pathstringrequired
- agents_path_resolvedstringrequired
- board_filestringrequired
Absolute path of board.json.
- canceled_statusstring
The column that counts as canceled (out of progress and release totals); null when the board has none.
- columnsobject[]required
Board columns left to right.
- idstringrequired
Stable column id stored on tickets.
- labelstringrequired
Name shown on the board.
- configuration_idstringrequired
- data_pathstringrequired
Configured path, as written.
- data_path_resolvedstringrequired
Absolute folder the board file is read from.
- default_statusstringrequired
- done_statusstringrequired
The column that counts as done for progress, releases and subtasks.
- id_prefixstringrequired
- observersall ofrequired
How many observers `kanban::on-change` and `kanban::on-comment` have.
all of (1)Variant 1- changeinteger· uintrequiredmin 0
- commentinteger· uintrequiredmin 0
- prioritiesstring[]required
- project_rootstringrequired
- workerstringrequired
The worker name, `kanban`: every function id and page id starts with it.
kanban::
project:: createkanbanv0.2.4Schema Create a project: a named group of tickets with an optional lead and color. Names are unique (ASCII case ignored).
request - colorstring
blue | purple | teal | green | amber | rose.
- descriptionstring
- leadstring
Agent profile id, or `user`.
- namestringrequired
Required; unique among projects (ASCII case ignored).
response - archived_atstring
Set when archived; an archived project refuses new tickets.
- colorstring
blue | purple | teal | green | amber | rose.
- countsobjectrequired
- created_atstringrequired
- descriptionstring
- doneinteger· uint64requiredmin 0
Of those, the ones in the done column.
- idstringrequired
- leadstring
Agent profile id, or `user`.
- namestringrequired
Unique among projects (trimmed, ASCII case ignored).
- source_labelstring
The label this project was converted from, if any.
- statusstringrequiredenum active, archived
- totalinteger· uint64requiredmin 0
Live tickets in the project.
- updated_atstringrequired
kanban::
ticket:: createkanbanv0.2.4Schema Create a ticket on the board and return it; pass compact to get back only its compact row (id, key, title, status, priority, assignee, comment_count). Optionally make it a subtask (parent), or file it under a project or release (id or name).
request - actorstring
Who is making the change. Defaults to `user`.
- assigneestring
Agent profile id.
- compactboolean
Return the compact row (id, key, title, status, priority, assignee, comment_count) instead of the full ticket.
- descriptionstring
- labelsstring[]
- parentstring
Make the new ticket a subtask of this ticket (uuid or key). The parent must be live and not a subtask itself.
- pillsobject[]
Badges to show on the card: `[{ "icon": "calendar", "text": "Fri 17:00" }]`; `icon` is a lucide icon name.
- iconstringrequired
- textstringrequired
- prioritystring
- projectstring
Project id or name. An archived project refuses new tickets.
- releasestring
Release id or name.
- statusstring
Column id; defaults to the configured default_status.
- titlestringrequired
Required.
response any of (2)Variant 1- activityobject[]
- actorstringrequired
- atstringrequired
- changesobject[]
Show 3 nestedHide nested
- fieldstringrequired
- fromunknownrequired
- tounknownrequired
- comment_idstring
- idstringrequired
- seqinteger· uint64requiredmin 0
- ticket_idstringrequired
- typestringrequired
ticket.created | ticket.updated | ticket.moved | ticket.deleted | ticket.restored | comment.created
- assigneestring
Agent profile id.
- childrenobject[]required
Live subtasks by ticket number.
- assigneestring
- deleted_atstring
- idstringrequired
- keystringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
- commentsobject[]
- authorstringrequired
Agent profile id, or `user`.
- bodystringrequired
- created_atstringrequired
- idstringrequired
- parent_idstring
Set for a reply; replies stay one level deep.
- ticket_idstringrequired
- created_atstringrequired
- created_bystring
- deleted_atstring
Set when soft-deleted; the row stays on disk.
- descriptionstring
- idstringrequired
Internal uuid.
- keystringrequired
Human-readable id, e.g. KAN-1.
- labelsstring[]
- orderinteger· uint64min 0
Position inside its column.
- parentany of
The parent, deleted or not; `null` for a ticket that is not a subtask.
any of (2)Variant 1- assigneestring
- deleted_atstring
- idstringrequired
- keystringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
Variant 2valuenull - parent_idstring
Uuid of the parent ticket. One level deep: a parent has no parent.
- pillsobject[]
Small icon-and-text badges another worker pins on the ticket (a due date, a priority, an alarm). Shown on the card and the ticket page.
- iconstringrequired
- textstringrequired
- prioritystringrequired
- progressobjectrequired
Live children in the done column over live children that are not canceled.
- doneinteger· uint64requiredmin 0
- totalinteger· uint64requiredmin 0
- project_idstring
Uuid of the project (several tickets, independent of the release).
- release_idstring
Uuid of the release.
- statusstringrequired
Column id.
- titlestringrequired
- updated_atstringrequired
Variant 2- assigneestring
- comment_countinteger· uint64requiredmin 0
- idstringrequired
- keystringrequired
- prioritystringrequired
- statusstringrequired
- titlestringrequired
kanban::
ticket:: getkanbanv0.2.4Schema Read one ticket with its comments and activity, its parent, its live subtasks and their progress. The activity is bounded to keep the result small: every comment.created entry plus the newest 50 other entries (activity_total says how many exist), and a changed text longer than 200 chars (a description edit) is cut to a prefix ending in [truncated, N chars; ...]. kanban::activity::list returns the full history and the full text. The id accepts the internal uuid or the human-readable key.
request - idstringrequired
Ticket uuid or human-readable key (KAN-1, case-insensitive).
response - activityobject[]
- actorstringrequired
- atstringrequired
- changesobject[]
- fieldstringrequired
- fromunknownrequired
- tounknownrequired
- comment_idstring
- idstringrequired
- seqinteger· uint64requiredmin 0
- ticket_idstringrequired
- typestringrequired
ticket.created | ticket.updated | ticket.moved | ticket.deleted | ticket.restored | comment.created
- activity_totalinteger· uint64requiredmin 0
Activity entries the ticket has in total; `activity` holds fewer when older non-comment entries were left out (`kanban::activity::list` pages them all).
- assigneestring
Agent profile id.
- childrenobject[]required
Live subtasks by ticket number.
- assigneestring
- deleted_atstring
- idstringrequired
- keystringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
- commentsobject[]
- authorstringrequired
Agent profile id, or `user`.
- bodystringrequired
- created_atstringrequired
- idstringrequired
- parent_idstring
Set for a reply; replies stay one level deep.
- ticket_idstringrequired
- created_atstringrequired
- created_bystring
- deleted_atstring
Set when soft-deleted; the row stays on disk.
- descriptionstring
- idstringrequired
Internal uuid.
- keystringrequired
Human-readable id, e.g. KAN-1.
- labelsstring[]
- orderinteger· uint64min 0
Position inside its column.
- parentany of
The parent, deleted or not; `null` for a ticket that is not a subtask.
any of (2)Variant 1- assigneestring
- deleted_atstring
- idstringrequired
- keystringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
Variant 2valuenull - parent_idstring
Uuid of the parent ticket. One level deep: a parent has no parent.
- pillsobject[]
Small icon-and-text badges another worker pins on the ticket (a due date, a priority, an alarm). Shown on the card and the ticket page.
- iconstringrequired
- textstringrequired
- prioritystringrequired
- progressobjectrequired
Live children in the done column over live children that are not canceled.
- doneinteger· uint64requiredmin 0
- totalinteger· uint64requiredmin 0
- project_idstring
Uuid of the project (several tickets, independent of the release).
- release_idstring
Uuid of the release.
- statusstringrequired
Column id.
- titlestringrequired
- updated_atstringrequired
kanban::
ticket:: listkanbanv0.2.4Schema List tickets in board order, optionally narrowed to a column, an assignee, an updated_since timestamp, a parent (its subtasks), a project or a release (empty string = none); offset and limit page the result and total counts every match; compact rows carry only id, key, title, status, priority, assignee and comment_count.
request - assigneestring
Agent profile id; empty string matches unassigned.
- compactboolean
Return the compact row (id, key, title, status, priority, assignee, comment_count) instead of the full summary.
- include_deletedboolean
- limitinteger· uint64min 0
At most this many tickets (after `offset`), in board order.
- offsetinteger· uint64min 0
Skip this many tickets before `limit`: the next page starts at the rows you have. `total` says how many there are.
- parent_idstring
Only the subtasks of this ticket (uuid or key); empty string = tickets that are not subtasks.
- project_idstring
Only tickets in this project (id or name); empty string = tickets in no project.
- release_idstring
Only tickets in this release (id or name); empty string = tickets in no release.
- statusstring
Column id.
- updated_sincestring
Only tickets updated after this ISO timestamp.
response - countinteger· uint64requiredmin 0
Rows returned.
- ticketsany of[]requiredany of (2)Variant 1
- assigneestring
- comment_countinteger· uint64requiredmin 0
- created_atstringrequired
- deleted_atstring
- idstringrequired
- keystringrequired
- labelsstring[]required
- orderinteger· uint64requiredmin 0
- parent_idstring
- pillsobject[]required
Show 2 nestedHide nested
- iconstringrequired
- textstringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
- updated_atstringrequired
Variant 2- assigneestring
- comment_countinteger· uint64requiredmin 0
- idstringrequired
- keystringrequired
- prioritystringrequired
- statusstringrequired
- titlestringrequired
- totalinteger· uint64requiredmin 0
Tickets that pass the filters, before `offset` and `limit`.
kanban::
ticket:: updatekanbanv0.2.4Schema Update a ticket field (title, description, status, priority, assignee, labels, parent, project, release) and return the ticket (compact returns only its compact row). To change labels pass add_labels / remove_labels (they edit the current labels, so concurrent edits do not overwrite each other); labels replaces the whole set. parent makes the ticket a subtask (one level: the parent must be live and not a subtask, a ticket with subtasks cannot become one) and null detaches it; the activity is recorded on both tickets. project and release take an id or a name; null clears. A patch that changes nothing records and fires nothing.
request - actorstring
- add_labelsstring[]
Labels to add to the current ones; one already present (ASCII case ignored) is skipped. Applied after `labels` and `remove_labels`.
- assigneestring
Agent profile id, or null to unassign.
- compactboolean
Return the compact row (id, key, title, status, priority, assignee, comment_count) instead of the full ticket.
- descriptionstring
- idstringrequired
Ticket uuid or human-readable key (KAN-1, case-insensitive).
- labelsstring[]
Replaces the whole label set. Prefer add_labels / remove_labels: they edit the labels the ticket has when the write runs, so concurrent label edits do not overwrite each other.
- parentstring
Ticket uuid or key to make this ticket a subtask of, or null to detach it. One level only: the parent must be live and not a subtask, and a ticket with subtasks cannot become one.
- pillsobject[]
Replaces every badge on the card: `[{ "icon": "alarm-clock", "text": "09:00" }]`; `icon` is a lucide icon name. `[]` clears them.
- iconstringrequired
- textstringrequired
- prioritystring
- projectstring
Project id or name, or null to clear. An archived project refuses new tickets.
- releasestring
Release id or name, or null to clear.
- remove_labelsstring[]
Labels to drop from the current ones (ASCII case ignored). Applied after `labels`, before `add_labels`.
- statusstring
- titlestring
response any of (2)Variant 1- activityobject[]
- actorstringrequired
- atstringrequired
- changesobject[]
Show 3 nestedHide nested
- fieldstringrequired
- fromunknownrequired
- tounknownrequired
- comment_idstring
- idstringrequired
- seqinteger· uint64requiredmin 0
- ticket_idstringrequired
- typestringrequired
ticket.created | ticket.updated | ticket.moved | ticket.deleted | ticket.restored | comment.created
- assigneestring
Agent profile id.
- childrenobject[]required
Live subtasks by ticket number.
- assigneestring
- deleted_atstring
- idstringrequired
- keystringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
- commentsobject[]
- authorstringrequired
Agent profile id, or `user`.
- bodystringrequired
- created_atstringrequired
- idstringrequired
- parent_idstring
Set for a reply; replies stay one level deep.
- ticket_idstringrequired
- created_atstringrequired
- created_bystring
- deleted_atstring
Set when soft-deleted; the row stays on disk.
- descriptionstring
- idstringrequired
Internal uuid.
- keystringrequired
Human-readable id, e.g. KAN-1.
- labelsstring[]
- orderinteger· uint64min 0
Position inside its column.
- parentany of
The parent, deleted or not; `null` for a ticket that is not a subtask.
any of (2)Variant 1- assigneestring
- deleted_atstring
- idstringrequired
- keystringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
Variant 2valuenull - parent_idstring
Uuid of the parent ticket. One level deep: a parent has no parent.
- pillsobject[]
Small icon-and-text badges another worker pins on the ticket (a due date, a priority, an alarm). Shown on the card and the ticket page.
- iconstringrequired
- textstringrequired
- prioritystringrequired
- progressobjectrequired
Live children in the done column over live children that are not canceled.
- doneinteger· uint64requiredmin 0
- totalinteger· uint64requiredmin 0
- project_idstring
Uuid of the project (several tickets, independent of the release).
- release_idstring
Uuid of the release.
- statusstringrequired
Column id.
- titlestringrequired
- updated_atstringrequired
Variant 2- assigneestring
- comment_countinteger· uint64requiredmin 0
- idstringrequired
- keystringrequired
- prioritystringrequired
- statusstringrequired
- titlestringrequired
kanban::
comment:: createkanbanv0.2.4Schema Comment on a ticket, or reply to a comment by passing parent_id. Returns the new comment and the ticket (only its compact row with compact).
request - authorstring
Agent profile id, or `user`. Defaults to `user`.
- bodystringrequired
Comment body. Markdown is rendered in the console.
- compactboolean
Return the ticket as its compact row (id, key, title, status, priority, assignee, comment_count) instead of the full ticket.
- parent_idstring
Comment id to reply to; replies stay one level deep.
- ticket_idstringrequired
Ticket uuid or human-readable key (KAN-1, case-insensitive).
response - commentobjectrequired
- authorstringrequired
Agent profile id, or `user`.
- bodystringrequired
- created_atstringrequired
- idstringrequired
- parent_idstring
Set for a reply; replies stay one level deep.
- ticket_idstringrequired
- ticketany ofrequired
What a ticket write returns: the full ticket, or its compact row when the request asked for `compact`.
any of (2)Variant 1- activityobject[]
Show 8 nestedHide nested
- actorstringrequired
- atstringrequired
- changesobject[]
Show 3 nestedHide nested
- fieldstringrequired
- fromunknownrequired
- tounknownrequired
- comment_idstring
- idstringrequired
- seqinteger· uint64requiredmin 0
- ticket_idstringrequired
- typestringrequired
ticket.created | ticket.updated | ticket.moved | ticket.deleted | ticket.restored | comment.created
- assigneestring
Agent profile id.
- childrenobject[]required
Live subtasks by ticket number.
Show 9 nestedHide nested
- assigneestring
- deleted_atstring
- idstringrequired
- keystringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
- commentsobject[]
Show 6 nestedHide nested
- authorstringrequired
Agent profile id, or `user`.
- bodystringrequired
- created_atstringrequired
- idstringrequired
- parent_idstring
Set for a reply; replies stay one level deep.
- ticket_idstringrequired
- created_atstringrequired
- created_bystring
- deleted_atstring
Set when soft-deleted; the row stays on disk.
- descriptionstring
- idstringrequired
Internal uuid.
- keystringrequired
Human-readable id, e.g. KAN-1.
- labelsstring[]
- orderinteger· uint64min 0
Position inside its column.
- parentany of
The parent, deleted or not; `null` for a ticket that is not a subtask.
Show 2 nestedHide nested
any of (2)Variant 1- assigneestring
- deleted_atstring
- idstringrequired
- keystringrequired
- prioritystringrequired
- project_idstring
- release_idstring
- statusstringrequired
- titlestringrequired
Variant 2valuenull - parent_idstring
Uuid of the parent ticket. One level deep: a parent has no parent.
- pillsobject[]
Small icon-and-text badges another worker pins on the ticket (a due date, a priority, an alarm). Shown on the card and the ticket page.
Show 2 nestedHide nested
- iconstringrequired
- textstringrequired
- prioritystringrequired
- progressobjectrequired
Live children in the done column over live children that are not canceled.
Show 2 nestedHide nested
- doneinteger· uint64requiredmin 0
- totalinteger· uint64requiredmin 0
- project_idstring
Uuid of the project (several tickets, independent of the release).
- release_idstring
Uuid of the release.
- statusstringrequired
Column id.
- titlestringrequired
- updated_atstringrequired
Variant 2- assigneestring
- comment_countinteger· uint64requiredmin 0
- idstringrequired
- keystringrequired
- prioritystringrequired
- statusstringrequired
- titlestringrequired
- router::
models:: listUnknown directory::
agents:: getiii-directoryv1.3.8Schema Fetch one agent profile by id: the system prompt resolved through its `extends` chain, display fields, preloaded `skills` (skill ids whose bodies the harness pre-loads into the session prompt) plus `unknown_skills`, preloaded `functions` (engine function ids the harness pre-loads into the session prompt) plus `unknown_functions`, model, reasoning_effort, `skills_index` (false = sessions start without the skills index), and `inheritance_error` when the chain does not resolve. Pass raw: true for the exact on-disk file to edit with directory::agents::update.
request - idstringrequired
- rawboolean
When true, also return the exact on-disk file (frontmatter included) as `raw`, ready for directory::agents::update.
response - builtinbooleanrequired
Bundled with the worker, no file behind it (see `list`).
- colorstring
Harness subagent color token (closed set, validated at write time); `null` = neutral.
- composer_placeholderstring
Example request for the chat's empty composer (see `list`): this profile's own value, never inherited; omitted when absent or blank.
- descriptionstringrequired
- extendsstring
Parent profile id (`extends:`), as declared; `null` = none.
- functionsstring[]required
Preloaded functions, resolved through `extends` (the nearest profile with a non-empty list): engine function ids whose contracts the harness pre-loads into the system prompt of every session running as this profile, so the model calls them without discovery or a contract lookup. Empty = none.
- hiddenbooleanrequired
Hidden from the chat's new-session gallery (still selectable by id).
- iconstring
Harness subagent icon token (closed set, validated at write time); `null` = caller picks.
- idstringrequired
- inheritance_errorstring
Set when the `extends` chain does not resolve (unknown parent, loop, deeper than 8): `system_prompt` and the inherited fields then come from this file alone, `raw` still round-trips so the chain can be fixed, and the harness refuses to run the profile meanwhile.
- logostring
- modelstring
Model id for sessions using this profile, resolved through `extends`; `null` = the send decides. Served verbatim — resolution against the live model catalog happens where it is used.
- modified_atstringrequired
File mtime as RFC 3339; empty for a bundled profile.
- namestringrequired
- rawstring
FULL on-disk file content (this profile's own file, ancestors excluded). Present only when the request set `raw: true`.
- reasoning_effortstring
Provider-native reasoning effort paired with `model`, resolved through `extends`; `null` = the model/provider default. Served verbatim and validated at use time.
- skillsstring[]required
Preloaded skills, resolved through `extends` (the union of the chain's lists, root first): skill ids whose bodies the harness pre-loads into the system prompt of every session running as this profile. Empty = none. Never a filter on the skills index.
- skills_indexboolean
`false` = sessions running as this profile start without the names-only skills index (`<available_skills>`), resolved through `extends`; omitted when no profile in the chain sets it (on).
- sourceall ofrequired
Where the file came from (see `list`).
all of (1)Variant 1- kindstringrequiredenum kit, worker, local, global, builtin
- kitstring
Owning kit (`<handle>/<name>`) when `kind` is `kit`.
- modifiedboolean
The file differs from what its kit or worker wrote.
- versionstring
Version of the kit or worker that wrote the file.
- workerstring
Owning worker when `kind` is `worker`.
- system_promptstringrequired
The RESOLVED identity: every ancestor's body root-first, then this file's body, frontmatter stripped, joined by a blank line; blank bodies are skipped, so a profile with no prompt of its own serves its parent chain unchanged and a prompt-less profile without `extends` serves `""`. A profile that has a body and no `extends` serves that body verbatim.
- unknown_functionsstring[]required
`functions` entries the engine does not currently know (not registered right now, or a typo). Warnings — the profile still loads and the harness skips them; an empty list also results when the engine could not be asked.
- unknown_skillsstring[]required
`skills` entries that resolve to no currently visible skill. Warnings — the agent profile still loads and the harness renders them as unavailable.
fp::
pipefpv0.3.2Schema Run a worker-side pipeline: each step calls a function and its result lands in the next step's payload at `into` (default "/value"); fp::* steps thread the bare value and a failing fp::when stops the pipe. The FIRST step gets no threaded value. Returns per-step sizes and a preview, not the value. A pipe is a chain, not a batch: fp::batch and fp::pipe cannot be steps (no nesting), and neither can engine::observers::dispose, configuration::, oauth::, router::, provider::, harness::, run::, workflow::start, workflow-result::submit, session writes or approval::. For independent calls use fp::batch. A refusal lists every problem in the request.
request - preview_charsinteger· uint32min 0
Preview length of the final threaded value in the receipt (capped at 8000).
- throughobject[]required
Steps run in order; step N+1 receives step N's threaded value.
- functionstringrequired
Function id to call.
- intostring
JSON pointer in this step's payload where the previous value lands (default `/value`); object keys only, no array indexing.
- payloadunknown
Base payload for the call.
response - short_circuitedbooleanrequired
True when a `fp::when` guard failed and stopped the pipe: the receipts end at the guard and NO later step ran. Absent (false) on a full run.
- stepsobject[]required
- charsinteger· uintrequiredmin 0
Size of the value threaded OUT of this step (chars of its string or serialized form).
- functionstringrequired
- notestring
Set when the threaded value REPLACED a non-null literal already in this step's payload at the `into` pointer — almost always an omitted `into` on a write step clobbering the value it meant to write.
- value_previewstring
fp::
getfpv0.3.2Schema Extract the single value at a JSON pointer (lodash _.get). A miss names the keys that were available.
request - pathstringrequired
JSON pointer selecting the value to return (e.g. `/content`).
- valueunknownrequired
Input value (a pipe lands the previous step's value here).
response - valueunknownrequired
shell::
execidev0.13.7Schema Run a command in the foreground and return its full output. Put the program in `command` (string) and arguments in `args` (string[]), never argv in `command`. Host-only cwd/env/stdin reject S210 on a sandbox target. Errors return { code, message }; common: S216 host exec error, S300 VM boot failed, S200 in-VM failure.
request - argsstring[]
Arguments, in order (all strings). Omit/null to tokenize `command` shell-words style; pass an array (even empty) to use it verbatim.
- commandstringrequired
Program name (PATH-resolved) or path to an executable, as a string; put arguments in `args`.
- cwdstring
Working directory (host only, S210 on sandbox); jail-confined like shell::fs::* paths (S215 on escape), must be an existing directory.
- envobject
Per-call env values (host only, S210 on sandbox); exec-hijacking keys (PATH, IFS, HOME, LD_*/DYLD_*, …) reject the whole call S210.
- stdinstring
Bytes written to the program's stdin, then EOF (host only, S210 on sandbox); omit to leave stdin at /dev/null.
- targetall of
Where to run the command. Defaults to the host worker; pass `{ kind: "sandbox", sandbox_id }` to forward the call to a microVM.
all of (1)Variant 1one of (2)Variant 1- kindstringrequiredenum host
Variant 2- kindstringrequiredenum sandbox
- sandbox_idstring· uuidrequired
- timeout_msinteger· uint64min 0
Per-call timeout in milliseconds, capped at the configured max; negative or fractional values fall back to the default.
response - duration_msinteger· uint64requiredmin 0
- exit_codeinteger· int32
- stderrstringrequired
- stderr_truncatedbooleanrequired
- stdoutstringrequired
- stdout_truncatedbooleanrequired
- timed_outbooleanrequired
coder::
treeidev0.13.7Schema Show a directory tree, bounded by max_depth, per_folder_limit and a node budget. Nodes carry only name (child path = parent path + '/' + name); over-limit folders are truncated stubs to paginate with coder::list-folder. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
request - include_hiddenboolean
List dot-prefixed entries; false omits them at every level (they then don't count toward per_folder_limit). The requested root is exempt.
- max_depthinteger· uint32min 0
Maximum depth to descend; the root node is depth 0.
- pathstring
Base folder for the snapshot (default `.`).
- per_folder_limitinteger· uint32min 0
Maximum children listed per folder. When more exist, the folder is flagged `truncated` and callers should switch to `coder::list-folder`.
- use_default_excludesboolean
Prune directories matching default_exclude_globs (see coder::info) into childless `truncated` stubs; false lists everything.
response - pathstringrequired
Canonical absolute path of the requested folder (resolved through the jail). Nodes carry only `name`, and the root node's path IS this `path` — do not join the root's `name` onto it; derive children by joining from here: child path = parent path + "/" + name. Operations on derived paths re-validate through the jail.
- rootall ofrequired
Root node of the snapshot; its `name` is the folder's basename.
all of (1)Variant 1- childrenunknown[]
- kindstringrequiredenum file, dir, symlink, other
- mtimeinteger· int64required
- namestringrequired
Entry basename. The ROOT node's path is the response's top-level `path` itself; every other node's path derives by joining from there: child path = parent path + "/" + name.
- non_accessiblebooleanrequired
- sizeinteger· uint64requiredmin 0
- truncatedany of
Set on directories whose `children` was capped at `per_folder_limit`, whose subtree was cut off by `max_depth`, which matched `default_exclude_globs` or omitted matching non-directory children (reason "default_exclude"), or where the snapshot's node budget ran out (reason "max_nodes").
Show 2 nestedHide nested
any of (2)Variant 1- hintstringrequired
- reasonstringrequired
Reason this folder was truncated: hit `per_folder_limit`, cut off by `max_depth`, matched `default_exclude_globs` (`default_exclude`), omitted matching non-directory children, or the snapshot's total node budget ran out (`max_nodes`).
- showninteger· uint32requiredmin 0
Number of children actually returned.
- totalinteger· uint32min 0
Total number of children eligible for listing in the folder, counted after hidden and default-exclude filtering (only populated when `reason == "per_folder_limit"`; for depth truncation we don't peek into the folder).
Variant 2valuenull
coder::
read-fileidev0.13.7Schema Read a file. stat: true probes size/mtime/total_lines without content; line_from/line_to (1-based, inclusive) read a window of a file of any size; numbered: true prefixes absolute line numbers; paths[] (XOR path) batch-reads. Paths: relative to the primary root or absolute inside an allowed root (see coder::info).
request - encodingall of
Content encoding for full reads; `base64` returns the exact file bytes (encoded length is budgeted). C210 with stat/window/numbered.
all of (1)Variant 1one of (2)Variant 1valuestringenum textVariant 2valuestringenum base64 - line_frominteger· uint64min 1
First line (1-based, >= 1) of a windowed read; windows keep files over max_read_bytes readable slice by slice. `path` mode only.
- line_tointeger· uint64min 1
Last line of the window, 1-based inclusive, >= `line_from`; omit to read from `line_from` to EOF. `path` mode only.
- max_output_bytesinteger· uint64min 0
Full-read byte budget (returned bytes, clamped to max_read_bytes); over budget fails C218 naming size/total_lines. C210 with a window.
- numberedboolean
Prefix each line with its absolute 1-based file line number (`N→`), matching coder::update-file line ops; C210 with `stat`. `path` mode only.
- pathstring
Single file to read; XOR with `paths` (C210 if both or neither is set).
- pathsany of[]
Batch of files to read in one call (bare path strings or window objects), processed in order against batch_read_budget_bytes; XOR with `path`.
any of (2)Variant 1valuestringVariant 2- line_frominteger· uint64min 1
First line of the window, 1-based inclusive (>= 1); defaults to 1 when only `line_to` is set.
- line_tointeger· uint64min 1
Last line of the window, 1-based inclusive, >= `line_from`; omit to read to EOF.
- numberedboolean
Prefix this entry's lines with their absolute 1-based line numbers (`N→`); prefix bytes count toward the batch budget.
- pathstringrequired
File to read.
- statboolean
Metadata probe for this entry: size/mode/mtime plus total_lines, content null, no budget consumed; C210 with a window or `numbered`.
- statboolean
Metadata probe: size/mode/mtime plus total_lines/is_utf8, no content; C210 with line_from/line_to/numbered/max_output_bytes.
response - contentstring
File content as a UTF-8 string — the whole file, or just the requested window when `line_from`/`line_to` was given (window lines keep their newline terminators). Binary content is returned with invalid bytes replaced by U+FFFD; request `encoding: "base64"` when exact bytes matter (content is then the file's bytes base64-encoded). **Single-path mode only; null when the request used `paths[]`.**
- is_utf8boolean
Whether `content` survived UTF-8 conversion without losing bytes. Reflects the RETURNED content only: a clean window inside an otherwise-binary file is still `true`. **Single-path mode only; null when the request used `paths[]`.**
- lines_returnedinteger· uint64min 0
Number of lines in `content`. For full reads this equals the file's total line count. **Single-path mode only; null when the request used `paths[]`.**
- modeinteger· uint32min 0
Unix permission bits (lower 9 bits of `st_mode`), e.g. 0o644. **Single-path mode only; null when the request used `paths[]`.**
- more_linesboolean
True when the file has content beyond what `content` includes: the window ended before EOF, or the byte budget cut the window short. Always false for full reads. **Single-path mode only; null when the request used `paths[]`.**
- mtimeinteger· int64
Last-modified time as a Unix epoch in seconds. **Single-path mode only; null when the request used `paths[]`.**
- pathstring
Canonical absolute path of the file read (resolved through the jail). **Single-path mode only; null when the request used `paths[]`.**
- resultsobject[]
Per-entry results for a batch `paths[]` request. **Present only when the request used `paths[]`; null in single-path mode.**
- contentstring
File content as a UTF-8 string — the whole file or the requested window. Binary bytes are replaced by U+FFFD (`is_utf8: false`). `null` on failure.
- errorany of
Structured error — present only when `success: false`.
any of (2)Variant 1- codestringrequired
Stable error code, e.g. "C211". See the README error table.
- messagestringrequired
Human/LLM-readable message: problem + actual values + corrective next call.
Variant 2valuenull - is_utf8boolean
Whether `content` survived UTF-8 conversion without losing bytes. `null` on failure.
- lines_returnedinteger· uint64min 0
Number of lines returned in `content`. `null` on failure.
- modeinteger· uint32min 0
Unix permission bits (lower 9 bits of `st_mode`), e.g. 0o644. `null` on failure.
- more_linesboolean
`true` when the file has content beyond what `content` includes (window ended before EOF, or byte budget cut the window short). `null` on failure.
- mtimeinteger· int64
Last-modified time as a Unix epoch in seconds. `null` on failure.
- pathstringrequired
Canonical absolute path of the file (resolved through the jail). If resolution failed, this echoes the caller's input verbatim.
- sizeinteger· uint64min 0
Size of the FILE in bytes (from metadata). `null` on failure or when the entry budget was exhausted before the file was opened.
- successbooleanrequired
`true` when the read succeeded (content/metadata fields are populated); `false` when an error occurred (only `error` is set).
- total_linesinteger· uint64min 0
Total lines in the file; present when the stream reached EOF during this entry's read. `null` when not traversed or on failure.
- revisionstring
Opaque identity of the file's exact bytes. Present for complete single-path reads only; pass it as `expected_revision` to `coder::create-file` for a conflict-safe whole-file overwrite.
- sizeinteger· uint64min 0
Size of the FILE in bytes (from metadata) — not the size of `content`; in windowed mode the two differ. **Single-path mode only; null when the request used `paths[]`.**
- total_linesinteger· uint64min 0
Total number of lines in the file. Present only when the read traversed the whole file: always for full reads; for windowed reads only when the stream naturally reached EOF within the byte cap. Never computed by forcing an extra full scan — absent means the file was not fully traversed. **Single-path mode only; null when the request used `paths[]`.**