no skills preloaded.

• harness::spawnharness1.8.55schema

  Spawn a sub-agent in a child session (never a trigger target) and return { child_session_id, child_turn_id } immediately; the child's outcome reaches you only through whatever destination its task names. Check `harness::status` for child health; children are leaves unless options.orchestrator is true.

  request

  • agentstring

    Directory agent profile id (`directory::agents::*`) supplying the child's prompt, skills, model, and display; refused with `options.system_prompt`. Omitted, an in-turn spawn continues the parent turn's profile (name `options.system_prompt` for a child that needs a different identity).

  • displayany of

    Display-only name/icon/color for the child session; never affects ids, policy, or routing.

    any of (2)

    variant 1

    • colorany of

      … expand 2 nestedcollapse

      any of (2)

      variant 1

      valuestringenum: neutral, blue, purple, teal, green, amber, …

      variant 2

      valuenull
    • iconany of

      … expand 2 nestedcollapse

      any of (2)

      variant 1

      valuestringenum: agent, code, search, terminal, database, test, …

      variant 2

      valuenull
    • namestring*required1…48 chars

      Short functional name such as `Frontend`, 1-48 characters after trimming.

    variant 2

    valuenull
  • modelstring
  • optionsany of

    any of (2)

    variant 1

    • filesystem_rootstring

      Absolute filesystem root for the child turn; omit to inherit the parent's.

    • functionsany of

      Dispatch policy for the child, intersected with the parent's (narrow, never escalate).

      … expand 2 nestedcollapse

      any of (2)

      variant 1

      • allowstring[]
      • denystring[]
      • exposeall of

        … expand 1 nestedcollapse

        all of (1)

        variant 1

        valuestringenum: agent_trigger, native

      variant 2

      valuenull
    • max_childreninteger· uint32min 0

      Fan-out guard for the child's own spawns.

    • max_output_tokensinteger· uint64min 0

      Inherits the parent's ceiling unless explicitly narrowed/overridden.

    • max_turnsinteger· uint32min 0

      Turn cap for the child, capped at the parent's remaining budget; omit unless required (small values strand the child).

    • max_validation_retriesinteger· uint32min 0

      Override of the child's validation-retry budget.

    • orchestratorboolean

      Let the child spawn, send, and register triggers (still capped by the parent's policy); default false makes it a leaf.

    • outputany of

      The child's deliverable: text / json / json+schema.

      … expand 2 nestedcollapse

      any of (2)

      variant 1

      one of (2)

      variant 1

      • typestring*requiredenum: text

      variant 2

      • schemaunknown
      • typestring*requiredenum: json

      variant 2

      valuenull
    • skillsstring[]

      Exact skill ids advertised to the child; omitted or empty means all (a reused child inherits when omitted).

    • system_promptstring
    • system_prompt_strategyall of

      How `system_prompt` combines with the built-in prompt.

      … expand 1 nestedcollapse

      all of (1)

      variant 1

      one of (3)

      variant 1

      valuestringenum: override

      variant 2

      valuestringenum: enrich

      variant 3

      valuestringenum: disabled
    • thinking_levelany of

      … expand 2 nestedcollapse

      any of (2)

      variant 1

      one of (2)

      variant 1

      valuestringenum: minimal, low, medium, high, xhigh

      variant 2

      valuestringenum: off

      variant 2

      valuenull

    variant 2

    valuenull
  • parent_session_idstring

    Display-only parent for the console tree when there is no live parent turn; grants no policy inheritance.

  • providerstring
  • session_idstring

    Session id to spawn into, created if absent; an existing id may be reused only inside the caller's own tree.

  • taskstring*required

    The child's self-contained goal, its opening user message; name every required resource selector literally (the child cannot infer them).

  response

  • child_session_idstring*required
  • child_turn_idstring*required
  • reusedboolean

    The named session already existed and was reused — its prior transcript and parent linkage were retained (only possible with an explicit `session_id`).

• harness::statusharness1.8.55schema

  Read a session's current turn. Returns a lean summary by default; pass verbose: true for the full runtime report and untruncated result.

  request

  • session_idstring*required
  • verboseboolean

    Include the full runtime report and unmodified result.

  response

  any of (2)

  variant 1

  • armed_wakesobject[]

    WHAT the session is parked on, when `expects_wake`: each armed wake's watch and deadline, so "parked 12m on state operation_meta/status — never written" is readable from the outside instead of the session just looking quietly done.

    • configunknown
    • created_atinteger· int64*required
    • expires_atinteger· int64
    • subscription_idstring*required
    • trigger_typestring

      The registered trigger's type/config, read from the canonicalised registration request. Absent on records that predate it.

  • childrenobject[]*required

    • function_call_idstring*required
    • session_idstring*required
    • turn_idstring*required
  • contextany of

    The last generate step's context accounting (budget, categories, provider-exact usage once it lands) — what a UI meter should show instead of re-estimating the transcript. Verbose only; absent before the first generate.

    any of (2)

    variant 1

    • categoriesobject*required

      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.

      … expand 6 nestedcollapse

      • hook_guidanceinteger· uint64min 0
      • messagesobject*required

        Estimated tokens of the assembled window's messages, by role.

        … expand 4 nestedcollapse

        • assistantinteger· uint64*requiredmin 0
        • custominteger· uint64*requiredmin 0
        • function_resultinteger· uint64*requiredmin 0
        • userinteger· uint64*requiredmin 0
      • overheadinteger· uint64*requiredmin 0

        Provider framing plus response_format / provider_options fields.

      • skillsinteger· uint64min 0

        Selected skill bodies contained in the system prompt.

      • system_promptinteger· uint64*requiredmin 0

        Final assembled system prompt excluding tokens attributed to `skills`: identity, per-step aids, and any compaction summary section.

      • toolsinteger· uint64*requiredmin 0

        Function schemas exposed to the model.

    • compactedboolean*required

      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· uint64*requiredmin 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· uint64*requiredmin 0
    • modelstring*required
    • prefix_divergencesobject[]

      Already-sent rows this session's requests rewrote, newest last (at most [`MAX_PREFIX_DIVERGENCES`]), carried from step to step.

      … expand 9 nestedcollapse

      • 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· uint64*requiredmin 0
      • turn_idstring*required
    • 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_idstring*required
    • stepinteger· uint64*requiredmin 0
    • summarized_head_tokensinteger· uint64min 0

      Size of the history that summary replaced.

    • timestampinteger· int64*required
    • totalinteger· uint64*requiredmin 0

      Final request estimate: categories plus post-assembly growth.

    • turn_idstring*required
    • usableinteger· uint64*requiredmin 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).

      … 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

    variant 2

    valuenull
  • depthinteger· uint32min 0
  • expects_wakeboolean

    The session owns an armed wake (a one-shot notify subscription): a completed turn here is NOT the run's outcome — a later turn in this session carries it. Mirrors the `terminal` flag on `harness::turn-completed` (`expects_wake == !terminal`). Pollers (e.g. workflow reconcile) must treat `completed && expects_wake` as still running.

  • max_transient_resumesinteger· uint32min 0
  • max_turnsinteger· uint32min 0
  • max_validation_retriesinteger· uint32min 0
  • partial_result_availableboolean
  • pending_function_callsstring[]
  • queuedobject[]

    Messages queued while a step streams, in arrival order; they land in the transcript when the stream ends.

    • entry_idstring*required

      Deterministic transcript entry id the drain appends under, so a redelivered drain is a no-op.

    • idstring*required
    • messageany of*required

      The canonical transcript message union. Untagged: the single-variant role tags disambiguate deserialization (assistant/function_result/custom are tried before user so their required fields gate the match).

      … expand 4 nestedcollapse

      any of (4)

      variant 1

      • contentone of[]*required

        … expand 7 nestedcollapse

        one of (7)

        variant 1

        • textstring*required
        • typestring*requiredenum: text

        variant 2

        • attachment_idstring

          Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.

        • datastring*required
        • mimestring*required
        • typestring*requiredenum: image

        variant 3

        • attachment_idstring*required
        • mimestring*required
        • namestring*required
        • sizeinteger· uint64*requiredmin 0
        • typestring*requiredenum: file

        variant 4

        • signaturestring
        • textstring*required
        • typestring*requiredenum: thinking

        variant 5

        • datastring*required
        • typestring*requiredenum: redacted_thinking

        variant 6

        • argumentsunknown*required
        • function_idstring*required
        • idstring*required
        • typestring*requiredenum: function_call

        variant 7

        • contentunknown[]*required
        • function_call_idstring*required
        • is_errorboolean
        • typestring*requiredenum: 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
      • modelstring*required
      • native_stop_reasonstring
      • providerstring*required
      • rolestring*requiredenum: assistant
      • stop_reasonstring*requiredenum: end, length, function_call, aborted, error
      • timestampinteger· int64*required
      • 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[]

      variant 2

      • contentone of[]*required

        … expand 7 nestedcollapse

        one of (7)

        variant 1

        • textstring*required
        • typestring*requiredenum: text

        variant 2

        • attachment_idstring

          Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.

        • datastring*required
        • mimestring*required
        • typestring*requiredenum: image

        variant 3

        • attachment_idstring*required
        • mimestring*required
        • namestring*required
        • sizeinteger· uint64*requiredmin 0
        • typestring*requiredenum: file

        variant 4

        • signaturestring
        • textstring*required
        • typestring*requiredenum: thinking

        variant 5

        • datastring*required
        • typestring*requiredenum: redacted_thinking

        variant 6

        • argumentsunknown*required
        • function_idstring*required
        • idstring*required
        • typestring*requiredenum: function_call

        variant 7

        • contentunknown[]*required
        • function_call_idstring*required
        • is_errorboolean
        • typestring*requiredenum: function_result
      • detailsunknown*required
      • function_call_idstring*required
      • function_idstring*required
      • is_errorboolean*required
      • rolestring*requiredenum: function_result
      • timestampinteger· int64*required

      variant 3

      • contentone of[]*required

        … expand 7 nestedcollapse

        one of (7)

        variant 1

        • textstring*required
        • typestring*requiredenum: text

        variant 2

        • attachment_idstring

          Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.

        • datastring*required
        • mimestring*required
        • typestring*requiredenum: image

        variant 3

        • attachment_idstring*required
        • mimestring*required
        • namestring*required
        • sizeinteger· uint64*requiredmin 0
        • typestring*requiredenum: file

        variant 4

        • signaturestring
        • textstring*required
        • typestring*requiredenum: thinking

        variant 5

        • datastring*required
        • typestring*requiredenum: redacted_thinking

        variant 6

        • argumentsunknown*required
        • function_idstring*required
        • idstring*required
        • typestring*requiredenum: function_call

        variant 7

        • contentunknown[]*required
        • function_call_idstring*required
        • is_errorboolean
        • typestring*requiredenum: function_result
      • custom_typestring*required
      • detailsunknown
      • displaystring
      • rolestring*requiredenum: custom
      • timestampinteger· int64*required

      variant 4

      • contentone of[]*required

        … expand 7 nestedcollapse

        one of (7)

        variant 1

        • textstring*required
        • typestring*requiredenum: text

        variant 2

        • attachment_idstring

          Optional link to the stored original of this inline image (`session::put-attachment`, resolvable with `session::get-attachment`). Lets readers ask `session::messages { include_image_data: false }` and fetch the bytes lazily instead of receiving them inline. Persisted verbatim on the transcript; model-bound consumers never see it (see [`ContentBlock::strip_files`]). Omitted on the wire when absent so legacy transcripts stay byte-identical.

        • datastring*required
        • mimestring*required
        • typestring*requiredenum: image

        variant 3

        • attachment_idstring*required
        • mimestring*required
        • namestring*required
        • sizeinteger· uint64*requiredmin 0
        • typestring*requiredenum: file

        variant 4

        • signaturestring
        • textstring*required
        • typestring*requiredenum: thinking

        variant 5

        • datastring*required
        • typestring*requiredenum: redacted_thinking

        variant 6

        • argumentsunknown*required
        • function_idstring*required
        • idstring*required
        • typestring*requiredenum: function_call

        variant 7

        • contentunknown[]*required
        • function_call_idstring*required
        • is_errorboolean
        • typestring*requiredenum: function_result
      • rolestring*requiredenum: user
      • timestampinteger· int64*required
    • originunknown
    • queued_atinteger· int64*required
    • session_idstring*required
  • resultunknown
  • result_errorstring
  • session_idstring*required
  • statusstring*requiredenum: running, awaiting_functions, completed, cancelled, failed

    The coarse, harness-internal turn lifecycle (harness.md § API Reference). Finer-grained than the session's `status`, which the loop derives from it.

  • stepinteger· uint64*requiredmin 0
  • stop_reasonstring

    Why a `completed` turn stopped when the model did not end it itself (`max_turns`). Present in the lean report too: a poller that reads `completed` with no error must still be able to tell an exhausted budget from a finished task.

  • transient_resumesinteger· uint32min 0
  • turn_countinteger· uint32*requiredmin 0
  • turn_idstring
  • validation_retriesinteger· uint32min 0

  variant 2

  valuenull
• harness::stopharness1.8.55schema

  Request cancellation of an in-flight turn (cascades to spawned children).

  request

  • session_idstring*required
  • turn_idstring

    Omit to stop the current turn.

  response

  • stoppingboolean*required
• harness::metricsharness1.8.55schema

  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 1

  empty object

  variant 2

  empty object

  response

  • by_sessionobject[]*required

    • cache_read_tokensinteger· uint64*requiredmin 0

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • cache_write_tokensinteger· uint64*requiredmin 0

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • 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

      • categoriesobject*required

        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.

        … expand 6 nestedcollapse

        • hook_guidanceinteger· uint64min 0
        • messagesobject*required

          Estimated tokens of the assembled window's messages, by role.

          … expand 4 nestedcollapse

          • assistantinteger· uint64*requiredmin 0
          • custominteger· uint64*requiredmin 0
          • function_resultinteger· uint64*requiredmin 0
          • userinteger· uint64*requiredmin 0
        • overheadinteger· uint64*requiredmin 0

          Provider framing plus response_format / provider_options fields.

        • skillsinteger· uint64min 0

          Selected skill bodies contained in the system prompt.

        • system_promptinteger· uint64*requiredmin 0

          Final assembled system prompt excluding tokens attributed to `skills`: identity, per-step aids, and any compaction summary section.

        • toolsinteger· uint64*requiredmin 0

          Function schemas exposed to the model.

      • compactedboolean*required

        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· uint64*requiredmin 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· uint64*requiredmin 0
      • modelstring*required
      • prefix_divergencesobject[]

        Already-sent rows this session's requests rewrote, newest last (at most [`MAX_PREFIX_DIVERGENCES`]), carried from step to step.

        … expand 9 nestedcollapse

        • 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· uint64*requiredmin 0
        • turn_idstring*required
      • 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_idstring*required
      • stepinteger· uint64*requiredmin 0
      • summarized_head_tokensinteger· uint64min 0

        Size of the history that summary replaced.

      • timestampinteger· int64*required
      • totalinteger· uint64*requiredmin 0

        Final request estimate: categories plus post-assembly growth.

      • turn_idstring*required
      • usableinteger· uint64*requiredmin 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).

        … 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

      variant 2

      valuenull
    • cost_usdnumber· double*required

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • depthinteger· uint32*requiredmin 0
    • function_call_errorsinteger· uint64*requiredmin 0
    • function_callsinteger· uint64*requiredmin 0
    • input_tokensinteger· uint64*requiredmin 0

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • output_tokensinteger· uint64*requiredmin 0

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • parent_session_idstring
    • reasoning_tokensinteger· uint64*requiredmin 0

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • session_idstring*required
    • turnsinteger· uint64*requiredmin 0
  • completeboolean*required
  • root_session_idstring*required
  • totalsobject*required

    • cache_read_tokensinteger· uint64*requiredmin 0

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • cache_write_tokensinteger· uint64*requiredmin 0

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • cost_usdnumber· double*required

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • function_call_errorsinteger· uint64*requiredmin 0
    • function_callsinteger· uint64*requiredmin 0
    • input_tokensinteger· uint64*requiredmin 0

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • output_tokensinteger· uint64*requiredmin 0

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • reasoning_tokensinteger· uint64*requiredmin 0

      Summed over every generation that reported it. A single generation without the counter (a stream the provider cut before usage came back) is left out of the sum. `null` means no generation reported it or more than one did not — never a measured zero, so the key is always present and a reader can tell the two apart.

    • sessionsinteger· uint64*requiredmin 0
    • turnsinteger· uint64*requiredmin 0
  • 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

      … expand 7 nestedcollapse

      • depthinteger· uint32*requiredmin 0
      • duration_msinteger· uint64*requiredmin 0

        Elapsed window from the session's first observed span to its last.

      • error_span_countinteger· uint64*requiredmin 0
      • parent_session_idstring
      • session_idstring*required
      • span_countinteger· uint64*requiredmin 0
      • trace_countinteger· uint64*requiredmin 0
    • duration_msinteger· uint64*requiredmin 0

      Elapsed window from the first observed span to the last observed span.

    • error_span_countinteger· uint64*requiredmin 0
    • span_countinteger· uint64*requiredmin 0
    • trace_countinteger· uint64*requiredmin 0

      Distinct traces across the root session and all descendants.

    variant 2

    valuenull
• harness::askharness1.8.55schema

  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, 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.

    • headerstring*required1…16 chars

      Short chip label such as `Approach`, 1-16 characters; prefixes the answer line (`Approach: <label>`).

    • 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.

      • labelstring*required1…80 chars

        The choice as the user sees and sends it, 1-80 characters, unique within its question.

    • questionstring*requiredmin 1 chars

      The full question text shown above the options.

  response

  • question_idstring*required

    The function-call id of this ask.

  • questionsobject[]*required

    The questions as shown, in request order.

    • headerstring*required1…16 chars

      Short chip label such as `Approach`, 1-16 characters; prefixes the answer line (`Approach: <label>`).

    • 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.

      • labelstring*required1…80 chars

        The choice as the user sees and sends it, 1-80 characters, unique within its question.

    • questionstring*requiredmin 1 chars

      The full question text shown above the options.

  • session_idstring*required
  • statusone of*required

    one of (1)

    variant 1

    valuestringenum: awaiting_answer
  • turn_idstring*required

    The turn that asked; once the session's current turn differs, the question has been answered.

• engine::register_triggerunknown
• state::compare-and-setstate0.22.19schema

  Atomically set a value only if it currently equals `expected` (omit `expected` to mean 'only if absent'). Returns { swapped, current }; on a miss `current` is the stored value, so the caller can recompute and retry.

  request

  • expectedunknown

    The value the caller believes is there. Omit to mean "expect absent" — the set-if-absent form.

  • keystring*required
  • scopestring*required
  • valueunknown*required

  response

  • currentunknown

    What is actually stored, when the swap did not happen.

  • swappedboolean*required
• state::liststate0.22.19schema

  List every value stored in a state scope

  request

  • scopestring*required

    Namespace whose keys should be listed as a group.

  response

  valuestring
• kanban::config::infokanban0.1.22schema

  Resolved kanban settings: the folder the board file lives in, the columns, and the numbering prefix.

  request

  empty object

  response

  • agents_pathstring*required
  • agents_path_resolvedstring*required
  • board_filestring*required

    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.

    • idstring*required

      Stable column id stored on tickets.

    • labelstring*required

      Name shown on the board.

  • configuration_idstring*required
  • data_pathstring*required

    Configured path, as written.

  • data_path_resolvedstring*required

    Absolute folder the board file is read from.

  • default_statusstring*required
  • done_statusstring*required

    The column that counts as done for progress, releases and subtasks.

  • id_prefixstring*required
  • prioritiesstring[]*required
  • project_rootstring*required
  • subscribersobject*required

    • changeinteger· uint*requiredmin 0
    • commentinteger· uint*requiredmin 0
• kanban::project::createkanban0.1.22schema

  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`.

  • namestring*required

    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.

  • countsobject*required
  • created_atstring*required
  • descriptionstring
  • doneinteger· uint64*requiredmin 0

    Of those, the ones in the done column.

  • idstring*required
  • leadstring

    Agent profile id, or `user`.

  • namestring*required

    Unique among projects (trimmed, ASCII case ignored).

  • source_labelstring

    The label this project was converted from, if any.

  • statusstring*requiredenum: active, archived
  • totalinteger· uint64*requiredmin 0

    Live tickets in the project.

  • updated_atstring*required
• kanban::ticket::createkanban0.1.22schema

  Create a ticket on the board and return it; pass compact to get back only its compact row (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 (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.

  • 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.

  • titlestring*required

    Required.

  response

  any of (2)

  variant 1

  • activityobject[]

    • actorstring*required
    • atstring*required
    • changesobject[]

      … expand 3 nestedcollapse

      • fieldstring*required
      • fromunknown*required
      • tounknown*required
    • comment_idstring
    • idstring*required
    • seqinteger· uint64*requiredmin 0
    • ticket_idstring*required
    • typestring*required

      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
    • idstring*required
    • keystring*required
    • prioritystring*required
    • project_idstring
    • release_idstring
    • statusstring*required
    • titlestring*required
  • commentsobject[]

    • authorstring*required

      Agent profile id, or `user`.

    • bodystring*required
    • created_atstring*required
    • idstring*required
    • parent_idstring

      Set for a reply; replies stay one level deep.

    • ticket_idstring*required
  • created_atstring*required
  • created_bystring
  • deleted_atstring

    Set when soft-deleted; the row stays on disk.

  • descriptionstring
  • idstring*required

    Internal uuid.

  • keystring*required

    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
    • idstring*required
    • keystring*required
    • prioritystring*required
    • project_idstring
    • release_idstring
    • statusstring*required
    • titlestring*required

    variant 2

    valuenull
  • parent_idstring

    Uuid of the parent ticket. One level deep: a parent has no parent.

  • prioritystring*required
  • progressobject*required

    Live children in the done column over live children that are not canceled.

    • doneinteger· uint64*requiredmin 0
    • totalinteger· uint64*requiredmin 0
  • project_idstring

    Uuid of the project (several tickets, independent of the release).

  • release_idstring

    Uuid of the release.

  • statusstring*required

    Column id.

  • titlestring*required
  • updated_atstring*required

  variant 2

  • assigneestring
  • comment_countinteger· uint64*requiredmin 0
  • keystring*required
  • prioritystring*required
  • statusstring*required
  • titlestring*required
• kanban::ticket::getkanban0.1.22schema

  Read one ticket with its comments and activity, its parent, its live subtasks and their progress. The id accepts the internal uuid or the human-readable key.

  request

  • idstring*required

    Ticket uuid or human-readable key (KAN-1, case-insensitive).

  response

  • activityobject[]

    • actorstring*required
    • atstring*required
    • changesobject[]

      • fieldstring*required
      • fromunknown*required
      • tounknown*required
    • comment_idstring
    • idstring*required
    • seqinteger· uint64*requiredmin 0
    • ticket_idstring*required
    • typestring*required

      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
    • idstring*required
    • keystring*required
    • prioritystring*required
    • project_idstring
    • release_idstring
    • statusstring*required
    • titlestring*required
  • commentsobject[]

    • authorstring*required

      Agent profile id, or `user`.

    • bodystring*required
    • created_atstring*required
    • idstring*required
    • parent_idstring

      Set for a reply; replies stay one level deep.

    • ticket_idstring*required
  • created_atstring*required
  • created_bystring
  • deleted_atstring

    Set when soft-deleted; the row stays on disk.

  • descriptionstring
  • idstring*required

    Internal uuid.

  • keystring*required

    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
    • idstring*required
    • keystring*required
    • prioritystring*required
    • project_idstring
    • release_idstring
    • statusstring*required
    • titlestring*required

    variant 2

    valuenull
  • parent_idstring

    Uuid of the parent ticket. One level deep: a parent has no parent.

  • prioritystring*required
  • progressobject*required

    Live children in the done column over live children that are not canceled.

    • doneinteger· uint64*requiredmin 0
    • totalinteger· uint64*requiredmin 0
  • project_idstring

    Uuid of the project (several tickets, independent of the release).

  • release_idstring

    Uuid of the release.

  • statusstring*required

    Column id.

  • titlestring*required
  • updated_atstring*required
• kanban::ticket::listkanban0.1.22schema

  List tickets, optionally narrowed to a column, an assignee, an updated_since timestamp, a parent (its subtasks), a project or a release (empty string = none); compact rows carry only key, title, status, priority, assignee and comment_count.

  request

  • assigneestring

    Agent profile id; empty string matches unassigned.

  • compactboolean

    Return the compact row (key, title, status, priority, assignee, comment_count) instead of the full summary.

  • include_deletedboolean
  • limitinteger· uint64min 0
  • 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· uint64*requiredmin 0
  • ticketsany of[]*required

    any of (2)

    variant 1

    • assigneestring
    • comment_countinteger· uint64*requiredmin 0
    • created_atstring*required
    • deleted_atstring
    • idstring*required
    • keystring*required
    • labelsstring[]*required
    • orderinteger· uint64*requiredmin 0
    • parent_idstring
    • prioritystring*required
    • project_idstring
    • release_idstring
    • statusstring*required
    • titlestring*required
    • updated_atstring*required

    variant 2

    • assigneestring
    • comment_countinteger· uint64*requiredmin 0
    • keystring*required
    • prioritystring*required
    • statusstring*required
    • titlestring*required
• kanban::ticket::movekanban0.1.22schema

  Move a ticket to a column (and position inside it); used by the board drag and drop. Moving a ticket to where it already is changes nothing; a deleted ticket cannot be moved. Returns the ticket, or only its compact row with compact.

  request

  • actorstring
  • compactboolean

    Return the compact row (key, title, status, priority, assignee, comment_count) instead of the full ticket.

  • idstring*required

    Ticket uuid or human-readable key (KAN-1, case-insensitive).

  • indexinteger· uint64min 0

    Zero-based position in the target column.

  • statusstring*required

    Target column id.

  response

  any of (2)

  variant 1

  • activityobject[]

    • actorstring*required
    • atstring*required
    • changesobject[]

      … expand 3 nestedcollapse

      • fieldstring*required
      • fromunknown*required
      • tounknown*required
    • comment_idstring
    • idstring*required
    • seqinteger· uint64*requiredmin 0
    • ticket_idstring*required
    • typestring*required

      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
    • idstring*required
    • keystring*required
    • prioritystring*required
    • project_idstring
    • release_idstring
    • statusstring*required
    • titlestring*required
  • commentsobject[]

    • authorstring*required

      Agent profile id, or `user`.

    • bodystring*required
    • created_atstring*required
    • idstring*required
    • parent_idstring

      Set for a reply; replies stay one level deep.

    • ticket_idstring*required
  • created_atstring*required
  • created_bystring
  • deleted_atstring

    Set when soft-deleted; the row stays on disk.

  • descriptionstring
  • idstring*required

    Internal uuid.

  • keystring*required

    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
    • idstring*required
    • keystring*required
    • prioritystring*required
    • project_idstring
    • release_idstring
    • statusstring*required
    • titlestring*required

    variant 2

    valuenull
  • parent_idstring

    Uuid of the parent ticket. One level deep: a parent has no parent.

  • prioritystring*required
  • progressobject*required

    Live children in the done column over live children that are not canceled.

    • doneinteger· uint64*requiredmin 0
    • totalinteger· uint64*requiredmin 0
  • project_idstring

    Uuid of the project (several tickets, independent of the release).

  • release_idstring

    Uuid of the release.

  • statusstring*required

    Column id.

  • titlestring*required
  • updated_atstring*required

  variant 2

  • assigneestring
  • comment_countinteger· uint64*requiredmin 0
  • keystring*required
  • prioritystring*required
  • statusstring*required
  • titlestring*required
• kanban::ticket::updatekanban0.1.22schema

  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 (key, title, status, priority, assignee, comment_count) instead of the full ticket.

  • descriptionstring
  • idstring*required

    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.

  • 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[]

    • actorstring*required
    • atstring*required
    • changesobject[]

      … expand 3 nestedcollapse

      • fieldstring*required
      • fromunknown*required
      • tounknown*required
    • comment_idstring
    • idstring*required
    • seqinteger· uint64*requiredmin 0
    • ticket_idstring*required
    • typestring*required

      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
    • idstring*required
    • keystring*required
    • prioritystring*required
    • project_idstring
    • release_idstring
    • statusstring*required
    • titlestring*required
  • commentsobject[]

    • authorstring*required

      Agent profile id, or `user`.

    • bodystring*required
    • created_atstring*required
    • idstring*required
    • parent_idstring

      Set for a reply; replies stay one level deep.

    • ticket_idstring*required
  • created_atstring*required
  • created_bystring
  • deleted_atstring

    Set when soft-deleted; the row stays on disk.

  • descriptionstring
  • idstring*required

    Internal uuid.

  • keystring*required

    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
    • idstring*required
    • keystring*required
    • prioritystring*required
    • project_idstring
    • release_idstring
    • statusstring*required
    • titlestring*required

    variant 2

    valuenull
  • parent_idstring

    Uuid of the parent ticket. One level deep: a parent has no parent.

  • prioritystring*required
  • progressobject*required

    Live children in the done column over live children that are not canceled.

    • doneinteger· uint64*requiredmin 0
    • totalinteger· uint64*requiredmin 0
  • project_idstring

    Uuid of the project (several tickets, independent of the release).

  • release_idstring

    Uuid of the release.

  • statusstring*required

    Column id.

  • titlestring*required
  • updated_atstring*required

  variant 2

  • assigneestring
  • comment_countinteger· uint64*requiredmin 0
  • keystring*required
  • prioritystring*required
  • statusstring*required
  • titlestring*required
• kanban::comment::createkanban0.1.22schema

  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`.

  • bodystring*required

    Comment body. Markdown is rendered in the console.

  • compactboolean

    Return the ticket as its compact row (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_idstring*required

    Ticket uuid or human-readable key (KAN-1, case-insensitive).

  response

  • commentobject*required

    • authorstring*required

      Agent profile id, or `user`.

    • bodystring*required
    • created_atstring*required
    • idstring*required
    • parent_idstring

      Set for a reply; replies stay one level deep.

    • ticket_idstring*required
  • ticketany of*required

    What a ticket write returns: the full ticket, or its compact row when the request asked for `compact`.

    any of (2)

    variant 1

    • activityobject[]

      … expand 8 nestedcollapse

      • actorstring*required
      • atstring*required
      • changesobject[]

        … expand 3 nestedcollapse

        • fieldstring*required
        • fromunknown*required
        • tounknown*required
      • comment_idstring
      • idstring*required
      • seqinteger· uint64*requiredmin 0
      • ticket_idstring*required
      • typestring*required

        ticket.created | ticket.updated | ticket.moved | ticket.deleted | ticket.restored | comment.created

    • assigneestring

      Agent profile id.

    • childrenobject[]*required

      Live subtasks by ticket number.

      … expand 9 nestedcollapse

      • assigneestring
      • deleted_atstring
      • idstring*required
      • keystring*required
      • prioritystring*required
      • project_idstring
      • release_idstring
      • statusstring*required
      • titlestring*required
    • commentsobject[]

      … expand 6 nestedcollapse

      • authorstring*required

        Agent profile id, or `user`.

      • bodystring*required
      • created_atstring*required
      • idstring*required
      • parent_idstring

        Set for a reply; replies stay one level deep.

      • ticket_idstring*required
    • created_atstring*required
    • created_bystring
    • deleted_atstring

      Set when soft-deleted; the row stays on disk.

    • descriptionstring
    • idstring*required

      Internal uuid.

    • keystring*required

      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.

      … expand 2 nestedcollapse

      any of (2)

      variant 1

      • assigneestring
      • deleted_atstring
      • idstring*required
      • keystring*required
      • prioritystring*required
      • project_idstring
      • release_idstring
      • statusstring*required
      • titlestring*required

      variant 2

      valuenull
    • parent_idstring

      Uuid of the parent ticket. One level deep: a parent has no parent.

    • prioritystring*required
    • progressobject*required

      Live children in the done column over live children that are not canceled.

      … expand 2 nestedcollapse

      • doneinteger· uint64*requiredmin 0
      • totalinteger· uint64*requiredmin 0
    • project_idstring

      Uuid of the project (several tickets, independent of the release).

    • release_idstring

      Uuid of the release.

    • statusstring*required

      Column id.

    • titlestring*required
    • updated_atstring*required

    variant 2

    • assigneestring
    • comment_countinteger· uint64*requiredmin 0
    • keystring*required
    • prioritystring*required
    • statusstring*required
    • titlestring*required
• shell::execide0.12.32schema

  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.

  • commandstring*required

    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 1

    one of (2)

    variant 1

    • kindstring*requiredenum: host

    variant 2

    • kindstring*requiredenum: sandbox
    • sandbox_idstring· uuid*required
  • 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· uint64*requiredmin 0
  • exit_codeinteger· int32
  • stderrstring*required
  • stderr_truncatedboolean*required
  • stdoutstring*required
  • stdout_truncatedboolean*required
  • timed_outboolean*required
• coder::treeide0.12.32schema

  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

  • pathstring*required

    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 of*required

    Root node of the snapshot; its `name` is the folder's basename.

    all of (1)

    variant 1

    • childrenunknown[]
    • kindstring*requiredenum: file, dir, symlink, other
    • mtimeinteger· int64*required
    • namestring*required

      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_accessibleboolean*required
    • sizeinteger· uint64*requiredmin 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").

      … expand 2 nestedcollapse

      any of (2)

      variant 1

      • hintstring*required
      • reasonstring*required

        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· uint32*requiredmin 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 2

      valuenull
• directory::agents::getiii-directory1.2.40schema

  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

  • idstring*required
  • rawboolean

    When true, also return the exact on-disk file (frontmatter included) as `raw`, ready for directory::agents::update.

  response

  • builtinboolean*required

    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.

  • descriptionstring*required
  • 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.

  • hiddenboolean*required

    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.

  • idstring*required
  • 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_atstring*required

    File mtime as RFC 3339; empty for a bundled profile.

  • namestring*required
  • 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 of*required

    Where the file came from (see `list`).

    all of (1)

    variant 1

    • kindstring*requiredenum: 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_promptstring*required

    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.

• engine::unregister_triggerunknown
• harness::triggers::listharness1.8.55schema

  List the trigger bindings a session owns: subscription id, trigger type/config, target (absent = notifies the owner), label, conditions, lifecycle, and fire count. In-turn calls may omit `session_id`.

  request

  • session_idstring

    Owner session whose bindings to list; in-turn calls may omit it (the calling session is injected).

  response

  • subscriptionsobject[]*required

    • actionstring

      Human-readable event text declared as `metadata.action`.

    • conditionsobject[]

      • configunknown
      • function_idstring*required
    • configunknown
    • created_atinteger· int64*required
    • expires_atinteger· int64
    • firesinteger· uint64*requiredmin 0
    • labelstring
    • max_firesinteger· uint64min 0
    • onceboolean*required
    • subscription_idstring*required
    • targetstring

      The function a fire calls. Absent for a wake — the fire notifies the owner session.

    • trigger_idstring

      The engine's own trigger id (absent only in the brief window before the engine acknowledged the registration).

    • trigger_typestring