No skills preloaded.

• harness::spawnharnessv1.8.58Schema

  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

      Show 2 nestedHide nested

      any of (2)

      Variant 1

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

      Variant 2

      valuenull
    • iconany of

      Show 2 nestedHide nested

      any of (2)

      Variant 1

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

      Variant 2

      valuenull
    • namestringrequiredmin 1 chars

      Short functional name such as `Frontend`; trimmed, and cut to its first 48 characters when longer.

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

      Show 2 nestedHide nested

      any of (2)

      Variant 1

      • allowstring[]
      • denystring[]
      • exposeall of

        Show 1 nestedHide nested

        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.

      Show 2 nestedHide nested

      any of (2)

      Variant 1

      one of (2)

      Variant 1

      • typestringrequiredenum text

      Variant 2

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

      Show 1 nestedHide nested

      all of (1)

      Variant 1

      one of (3)

      Variant 1

      valuestringenum override

      Variant 2

      valuestringenum enrich

      Variant 3

      valuestringenum disabled
    • thinking_levelany of

      Show 2 nestedHide nested

      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.

  • taskstringrequired

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

  response

  • child_session_idstringrequired
  • child_turn_idstringrequired
  • 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::statusharnessv1.8.58Schema

  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_idstringrequired
  • 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· int64required
    • expires_atinteger· int64
    • subscription_idstringrequired
    • trigger_typestring

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

  • childrenobject[]required

    • function_call_idstringrequired
    • session_idstringrequired
    • turn_idstringrequired
  • 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

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

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

    • idstringrequired
    • messageany ofrequired

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

      Show 4 nestedHide nested

      any of (4)

      Variant 1

      • contentone of[]required

        Show 7 nestedHide nested

        one of (7)

        Variant 1

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

        • datastringrequired
        • mimestringrequired
        • typestringrequiredenum image

        Variant 3

        • attachment_idstringrequired
        • mimestringrequired
        • namestringrequired
        • sizeinteger· uint64requiredmin 0
        • typestringrequiredenum file

        Variant 4

        • signaturestring
        • textstringrequired
        • typestringrequiredenum thinking

        Variant 5

        • datastringrequired
        • typestringrequiredenum redacted_thinking

        Variant 6

        • argumentsunknownrequired
        • function_idstringrequired
        • idstringrequired
        • typestringrequiredenum function_call

        Variant 7

        • contentunknown[]required
        • function_call_idstringrequired
        • is_errorboolean
        • typestringrequiredenum function_result
      • error_kindany of

        Show 2 nestedHide nested

        any of (2)

        Variant 1

        valuestringenum auth_expired, rate_limited, context_overflow, transient, permanent

        Variant 2

        valuenull
      • error_messagestring
      • modelstringrequired
      • native_stop_reasonstring
      • providerstringrequired
      • rolestringrequiredenum assistant
      • stop_reasonstringrequiredenum end, length, function_call, aborted, error
      • timestampinteger· int64required
      • usageany of

        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 2

        valuenull
      • warningsstring[]

      Variant 2

      • contentone of[]required

        Show 7 nestedHide nested

        one of (7)

        Variant 1

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

        • datastringrequired
        • mimestringrequired
        • typestringrequiredenum image

        Variant 3

        • attachment_idstringrequired
        • mimestringrequired
        • namestringrequired
        • sizeinteger· uint64requiredmin 0
        • typestringrequiredenum file

        Variant 4

        • signaturestring
        • textstringrequired
        • typestringrequiredenum thinking

        Variant 5

        • datastringrequired
        • typestringrequiredenum redacted_thinking

        Variant 6

        • argumentsunknownrequired
        • function_idstringrequired
        • idstringrequired
        • typestringrequiredenum function_call

        Variant 7

        • contentunknown[]required
        • function_call_idstringrequired
        • is_errorboolean
        • typestringrequiredenum function_result
      • detailsunknownrequired
      • function_call_idstringrequired
      • function_idstringrequired
      • is_errorbooleanrequired
      • rolestringrequiredenum function_result
      • timestampinteger· int64required

      Variant 3

      • contentone of[]required

        Show 7 nestedHide nested

        one of (7)

        Variant 1

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

        • datastringrequired
        • mimestringrequired
        • typestringrequiredenum image

        Variant 3

        • attachment_idstringrequired
        • mimestringrequired
        • namestringrequired
        • sizeinteger· uint64requiredmin 0
        • typestringrequiredenum file

        Variant 4

        • signaturestring
        • textstringrequired
        • typestringrequiredenum thinking

        Variant 5

        • datastringrequired
        • typestringrequiredenum redacted_thinking

        Variant 6

        • argumentsunknownrequired
        • function_idstringrequired
        • idstringrequired
        • typestringrequiredenum function_call

        Variant 7

        • contentunknown[]required
        • function_call_idstringrequired
        • is_errorboolean
        • typestringrequiredenum function_result
      • custom_typestringrequired
      • detailsunknown
      • displaystring
      • rolestringrequiredenum custom
      • timestampinteger· int64required

      Variant 4

      • contentone of[]required

        Show 7 nestedHide nested

        one of (7)

        Variant 1

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

        • datastringrequired
        • mimestringrequired
        • typestringrequiredenum image

        Variant 3

        • attachment_idstringrequired
        • mimestringrequired
        • namestringrequired
        • sizeinteger· uint64requiredmin 0
        • typestringrequiredenum file

        Variant 4

        • signaturestring
        • textstringrequired
        • typestringrequiredenum thinking

        Variant 5

        • datastringrequired
        • typestringrequiredenum redacted_thinking

        Variant 6

        • argumentsunknownrequired
        • function_idstringrequired
        • idstringrequired
        • typestringrequiredenum function_call

        Variant 7

        • contentunknown[]required
        • function_call_idstringrequired
        • is_errorboolean
        • typestringrequiredenum function_result
      • rolestringrequiredenum user
      • timestampinteger· int64required
    • originunknown
    • queued_atinteger· int64required
    • session_idstringrequired
  • resultunknown
  • result_errorstring
  • session_idstringrequired
  • statusstringrequiredenum 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· uint64requiredmin 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· uint32requiredmin 0
  • turn_idstring
  • validation_retriesinteger· uint32min 0

  Variant 2

  valuenull
• harness::stopharnessv1.8.58Schema

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

  request

  • session_idstringrequired
  • turn_idstring

    Omit to stop the current turn.

  response

  • stoppingbooleanrequired
• harness::metricsharnessv1.8.58Schema

  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

    • 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 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· uint64requiredmin 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· doublerequired

        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_callsinteger· uint64requiredmin 0
      • input_tokensinteger· uint64requiredmin 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.

      • modelstringrequired
      • output_tokensinteger· uint64requiredmin 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.

      • providerstringrequired
      • reasoning_tokensinteger· uint64requiredmin 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.

      • turnsinteger· uint64requiredmin 0

        Model steps (assistant messages) this model generated.

    • cache_read_tokensinteger· uint64requiredmin 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· uint64requiredmin 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

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

        valuenull

      Variant 2

      valuenull
    • cost_usdnumber· doublerequired

      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· uint32requiredmin 0
    • function_call_errorsinteger· uint64requiredmin 0
    • function_callsinteger· uint64requiredmin 0
    • input_tokensinteger· uint64requiredmin 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· uint64requiredmin 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· uint64requiredmin 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_idstringrequired
    • turnsinteger· uint64requiredmin 0
  • 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 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· uint64requiredmin 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· doublerequired

        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_callsinteger· uint64requiredmin 0
      • input_tokensinteger· uint64requiredmin 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.

      • modelstringrequired
      • output_tokensinteger· uint64requiredmin 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.

      • providerstringrequired
      • reasoning_tokensinteger· uint64requiredmin 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.

      • turnsinteger· uint64requiredmin 0

        Model steps (assistant messages) this model generated.

    • cache_read_tokensinteger· uint64requiredmin 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· uint64requiredmin 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· doublerequired

      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· uint64requiredmin 0
    • function_callsinteger· uint64requiredmin 0
    • input_tokensinteger· uint64requiredmin 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· uint64requiredmin 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· uint64requiredmin 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· uint64requiredmin 0
    • turnsinteger· uint64requiredmin 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

      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 2

    valuenull
• harness::askharnessv1.8.58Schema

  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.

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

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

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

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

    one of (1)

    Variant 1

    valuestringenum awaiting_answer
  • turn_idstringrequired

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

• engine::register_triggerUnknown
• state::compare-and-setstatev0.22.20Schema

  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.

  • keystringrequired
  • scopestringrequired
  • valueunknownrequired

  response

  • currentunknown

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

  • swappedbooleanrequired
• state::liststatev0.22.20Schema

  List every value stored in a state scope

  request

  • scopestringrequired

    Namespace whose keys should be listed as a group.

  response

  valuestring
• kanban::config::infokanbanv0.1.24Schema

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

  request

  Empty object

  response

  • 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
  • prioritiesstring[]required
  • project_rootstringrequired
  • subscribersobjectrequired

    • changeinteger· uintrequiredmin 0
    • commentinteger· uintrequiredmin 0
• kanban::project::createkanbanv0.1.24Schema

  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.1.24Schema

  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.

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

    valuenull
  • parent_idstring

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

  • 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
  • keystringrequired
  • prioritystringrequired
  • statusstringrequired
  • titlestringrequired
• kanban::ticket::getkanbanv0.1.24Schema

  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

  • 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

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

    valuenull
  • parent_idstring

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

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

  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· uint64requiredmin 0
  • ticketsany of[]required

    any of (2)

    Variant 1

    • assigneestring
    • comment_countinteger· uint64requiredmin 0
    • created_atstringrequired
    • deleted_atstring
    • idstringrequired
    • keystringrequired
    • labelsstring[]required
    • orderinteger· uint64requiredmin 0
    • parent_idstring
    • prioritystringrequired
    • project_idstring
    • release_idstring
    • statusstringrequired
    • titlestringrequired
    • updated_atstringrequired

    Variant 2

    • assigneestring
    • comment_countinteger· uint64requiredmin 0
    • keystringrequired
    • prioritystringrequired
    • statusstringrequired
    • titlestringrequired
• kanban::ticket::movekanbanv0.1.24Schema

  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.

  • idstringrequired

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

  • indexinteger· uint64min 0

    Zero-based position in the target column.

  • statusstringrequired

    Target column id.

  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 2

    valuenull
  • parent_idstring

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

  • 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
  • keystringrequired
  • prioritystringrequired
  • statusstringrequired
  • titlestringrequired
• kanban::ticket::updatekanbanv0.1.24Schema

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

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

    valuenull
  • parent_idstring

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

  • 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
  • keystringrequired
  • prioritystringrequired
  • statusstringrequired
  • titlestringrequired
• kanban::comment::createkanbanv0.1.24Schema

  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 (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 2

      valuenull
    • parent_idstring

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

    • 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
    • keystringrequired
    • prioritystringrequired
    • statusstringrequired
    • titlestringrequired
• shell::execidev0.12.34Schema

  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 1

    one 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.12.34Schema

  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 2

      valuenull
• directory::agents::getiii-directoryv1.2.41Schema

  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.

• engine::unregister_triggerUnknown
• harness::triggers::listharnessv1.8.58Schema

  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_idstringrequired
    • configunknown
    • created_atinteger· int64required
    • expires_atinteger· int64
    • firesinteger· uint64requiredmin 0
    • labelstring
    • max_firesinteger· uint64min 0
    • oncebooleanrequired
    • subscription_idstringrequired
    • 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