@sema-agent/core 5.19.0 → 5.21.0

package/dist/brain/stream-shared.d.ts

@@ -1,8 +1,42 @@
 import { type RepetitionEvent } from "./repetition.js";
+/**
+ * design/157 A10 — stream-parser pieces that the anthropic and openai SSE lanes carried BYTE-IDENTICALLY
+ * (verified by diff at 1469481: a 16-line repetition-telemetry closure). Provider-agnostic policy, so it
+ * lives here once and each lane keeps a pointer comment.
+ *
+ * REF-B1 extends that: the fail-closed ARGUMENT PARSE inside each lane's `closeToolCall*` (identical down to
+ * its comment) is hoisted here as {@link parseStreamedToolArgs}. Only the parse — each lane keeps its own
+ * accumulator fields, its `closedTc` cache and its own id prefix, which are real wire-format differences.
+ *
+ * Deliberately NOT hoisted: each lane's own degenerate-cut bookkeeping (`degenTextBlock` / `degenFace` are
+ * lane-specific content shapes).
+ *
+ * Internal module: not re-exported from `src/index.ts`.
+ */
+/**
+ * REF-B1 — turn a streamed tool call's accumulated argument bytes into its arguments object, FAIL-CLOSED.
+ *
+ * - no bytes (`""`) → `{}`: genuinely a no-argument call (the provider's frame carried no arguments);
+ * - valid JSON **object** → that object;
+ * - anything else (truncated/invalid JSON, or a top-level string/array/number/null) → `undefined`.
+ *
+ * bug-hunt #6 (kept from finalize): a non-object must never reach `tool.execute` / the MCP wire. `undefined`
+ * means "do not emit a `toolcall_end` for this call"; callers must NOT cache that outcome — finalize retries
+ * the parse against the complete accumulation.
+ */
 export declare function parseStreamedToolArgs(json: string): Record<string, unknown> | undefined;
+/** Repetition telemetry for ONE stream — the cut event plus the allowance-spared hits. */
 export interface RepetitionPoll {
+    /** Inspect the accumulated text; returns whether it is degenerate (the caller trips its own cut). */
     poll(text: string): boolean;
+    /** The cut event, once a poll tripped. */
     readonly cut: RepetitionEvent | undefined;
+    /** Allowance-spared hits, deduped by rule+segment with the loop's PEAK depth kept. */
     readonly spared: RepetitionEvent[];
 }
+/**
+ * Repetition telemetry (clay 2026-07-10): the cut event + allowance-spared hits for THIS stream.
+ * Polls re-inspect the same growing text every ~64 chars — dedupe spared by rule+segment so one
+ * boot block doesn't log once per poll. Attached to the final message as `repetition`.
+ */
 export declare function createRepetitionPoll(): RepetitionPoll;

package/dist/brain/terminal-cause.d.ts

@@ -1,3 +1,34 @@
 import type { AssistantMessage } from "../internal/llm.js";
+/**
+ * RB-464 — the DELIBERATE brain-side cut, read as a TYPED cause instead of by comparing the
+ * turn's human-readable `errorMessage` against an exported sentinel string.
+ *
+ * Why this file exists at all. The cut is a cross-LAYER signal: a brain stamps it, the loop's
+ * recovery lane reacts, and the assembler maps it to a terminal code. Before
+ * RB-464 the only carrier was the sentinel prose, compared by identity at six sites in two files.
+ * Identity-comparing an exported constant is much safer than matching a prose fragment — the value
+ * can be reworded freely and every site follows — but it still makes the CAUSE a string: a brain
+ * that stamps the same sentence without importing the constant (a custom `Brain`, a message rebuilt
+ * from a field whitelist, a re-encode through a host that normalizes whitespace) is invisible to all
+ * six sites at once, silently, with every test still green because the tests import the constant too.
+ * `errorKind` carries the cause as data instead; these predicates are the single place that knows how
+ * to read it.
+ *
+ * RB-482 #12 (ruled 2026-08-03, the RB-464 retirement condition met at this window): the transitional
+ * `errorMessage`-sentinel fallback is DELETED — `errorKind` is the ONE read. The two shapes the
+ * fallback served are closed the documented way: pre-RB-464 stored turns are the sacrificed-replay
+ * class (RB-476-A precedent), and stamping `errorKind` on every cut turn is now a documented Brain
+ * obligation (see the field's contract note on AssistantMessage). A custom brain that stamps only the
+ * sentinel prose is no longer recognized — declared in the 5.1.0 CHANGELOG.
+ */
+/** The subset of an assistant turn that carries a terminal cause. Accepts a full {@link AssistantMessage}. */
 export type TerminalCauseCarrier = Pick<AssistantMessage, "errorKind">;
+/**
+ * True when this turn is the brain's DEGENERATE-REPETITION cutoff (design/39): the model looped on the
+ * same text and the brain cancelled the stream, keeping the salvageable prefix.
+ *
+ * Deliberately does NOT also require `stopReason === "error"`. Callers that need the terminal shape
+ * check it themselves (the assembler does); the recovery lanes are handed an already-errored turn.
+ * Folding the check in here would silently change those call sites' meaning.
+ */
 export declare function isDegenerateCutMessage(message: TerminalCauseCarrier): boolean;

package/dist/brain/timeout.d.ts

@@ -1,30 +1,138 @@
 import type { StreamFn } from "../internal/llm.js";
+/**
+ * Tiered timeouts (1.38.1, design/17 §5B). The task-level `timeoutSec` only bounds the *whole* run;
+ * it can't tell apart a gateway that never accepts the connection from one that accepts it, opens the
+ * SSE stream, then hangs forever without emitting a token (the most common gateway-stall symptom).
+ * Two finer levels close that gap, each retryable as a transient `network` failure:
+ *
+ * - **connect**: `fetch` hasn't returned response headers in time.
+ * - **first-token**: the SSE stream is open but no content delta has arrived (see brain read loops).
+ *
+ * Both default to `undefined` (disabled) so existing behavior is unchanged.
+ */
+/**
+ * The largest delay a host timer can actually wait for. Past this `setTimeout` does not schedule far in
+ * the future — it truncates the delay to 1ms and fires at once, which for a watchdog means the OPPOSITE
+ * of what a deployment widening the bound asked for: every call aborted immediately, while the failure
+ * text quotes the number that was requested. Any ms knob that reaches a timer is refused above it
+ * (knob-hygiene #98); a watchdog that is meant to be off has its own `0` / `false` spelling.
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/**
+ * Resolve one stall-timeout knob to its effective value, refusing invalid numbers loudly. `x && x > 0`
+ * downstream reads NaN as "unset" — a deployment that SET a tighter watchdog and fumbled the units
+ * ("120s" → Number → NaN) used to get every watchdog silently OFF, the dangerous direction (ruled
+ * 2026-08-03, cross-repo robustness batch; same posture as the guardrail knob). `0` stays legal —
+ * an explicit off. Absent stays absent. Above {@link MAX_TIMER_DELAY_MS} is refused for the mirror-image
+ * reason: the host timer would turn "watch for 34 days" into "abort on arrival".
+ */
 export declare function resolveStallTimeoutMs(value: number | undefined, knob: string): number | undefined;
+/**
+ * The engine's ADVISORY per-call stall watchdog values (`StreamOptions.stallTimeouts`), supplied on
+ * every provider call. They are a GUARDRAIL, not part of any budget lane: TB2.0 run89's production
+ * frame had an in-flight model call sit 680s with ZERO deltas, and `BrainTimeoutConfig` defaults
+ * every watchdog to OFF, so nothing finer than the hour-scale {@link BRAIN_CALL_GUARDRAIL_DEFAULT_MS}
+ * bounded it. A silent stream is never worth more than these bounds, whether or not the task declared
+ * a time limit. All three surface as the brain's existing retryable `network` stall class (design/124
+ * tier C retries a zero-content cut, so a transient gateway hang still recovers). 量纲:
+ *   - connect 30s: bounds the fetch→response-HEADERS wait — the one segment every post-headers
+ *     watchdog is blind to. On a streaming API the model's time is spent AFTER headers, so 30s with
+ *     none at all is a hung gateway, not a slow model.
+ *   - first-token 120s: bounds the headers→first-delta wait, NOT the model's thought (the first
+ *     THINKING delta already counts as the first token, design/17 O5 — see
+ *     {@link BrainTimeoutConfig.firstTokenTimeoutMs}), so a slow reasoner is safe; 2 minutes with
+ *     literally NOTHING is a hung gateway.
+ *   - idle 90s: mid-stream silence after output started — a healthy stream emits steadily
+ *     (comfortably above any provider keep-alive cadence).
+ * ADVISORY: a brain whose construction-time {@link BrainTimeoutConfig} sets the corresponding field
+ * keeps it (deployment sovereignty; see the `StreamOptions.stallTimeouts` priority chain).
+ */
 export declare const STALL_CONNECT_MS = 30000;
 export declare const STALL_FIRST_TOKEN_MS = 120000;
 export declare const STALL_IDLE_MS = 90000;
 export interface BrainTimeoutConfig {
+    /** Abort the request if `fetch` doesn't return response headers within this many ms. Retryable. */
     connectTimeoutMs?: number;
+    /**
+     * After the stream opens, cancel it if no content delta (text / thinking / tool input) arrives
+     * within this many ms → `BrainError("network", "first-token timeout")`. For reasoning models the
+     * **first thinking delta also counts** as the first token, so a long-thinking model isn't killed
+     * for being slow to its first *visible* word (design/17 O5).
+     */
     firstTokenTimeoutMs?: number;
+    /**
+     * **Idle / mid-stream stall watchdog** (1.40.1, design/24 — gap found in the Claude Code source study).
+     * After the first delta, re-armed on every delta; if the stream then goes silent for this many ms
+     * (a gateway that hung mid-output) → `reader.cancel()` + `BrainError("network", "stream idle timeout")`.
+     * Complements `firstTokenTimeoutMs`: that one tolerates a long *first* token (reasoning), this one
+     * catches a stall *after* output has started, where a healthy stream emits steadily. Default off.
+     */
     idleTimeoutMs?: number;
 }
+/**
+ * A per-fetch-attempt abort controller that fires on a connect timeout while still forwarding an
+ * outer (task) abort. The returned `signal` governs the **whole** request including the streamed body
+ * — so once headers arrive, call `clearTimer()` (NOT `dispose()`) to stop the connect timer while
+ * keeping the outer-abort link alive for the body read; call `dispose()` only when the request is
+ * fully done or being discarded.
+ */
 export declare function createConnectController(connectTimeoutMs: number | undefined, outerSignal: AbortSignal | undefined): {
     signal: AbortSignal;
     timedOut: () => boolean;
     clearTimer: () => void;
+    /** Abort this attempt's signal. The signal handed to `doFetch` is how an injected fetch wrapper
+     *  learns it may release its transport, so an attempt being ABANDONED (its error body cut short by
+     *  a bound, its response discarded before a retry) must say so rather than just dropping the
+     *  reference. Idempotent; a no-op once the response is fully consumed. */
     abort: () => void;
     dispose: () => void;
 };
+/**
+ * Default ceiling on how long the ENGINE waits for a single brain call (ruled 2026-08-03: one hour).
+ * Deliberately far above any legitimate call: this is a wedged-run backstop, not a latency policy —
+ * a deployment that wants a tight per-call bound sets the fine tier above ({@link BrainTimeoutConfig},
+ * or the advisory {@link STALL_CONNECT_MS} family the engine supplies by default). All of these clocks
+ * run in parallel with the task's own `limits.timeoutSec`; whichever expires first owns the run.
+ */
 export declare const BRAIN_CALL_GUARDRAIL_DEFAULT_MS = 3600000;
+/** Terminal `TaskResult.errorCode` for a run the guardrail stopped waiting on. */
 export declare const BRAIN_CALL_GUARDRAIL_ERROR_CODE = "brain.call_guardrail_timeout";
+/** Thrown at every await point of a brain call the guardrail has given up on. */
 export declare class BrainCallGuardrailTimeoutError extends Error {
+    /** Read by the runner's terminal-code chain (`errorCodeOf`) — never matched on the message text. */
     readonly code = "brain.call_guardrail_timeout";
     readonly limitMs: number;
     constructor(limitMs: number);
 }
+/**
+ * The guardrail knob's value space: a positive number of milliseconds, or `false`/`0` to switch the
+ * guardrail OFF entirely (a deployment that owns its own outer bound). Absent ⇒
+ * {@link BRAIN_CALL_GUARDRAIL_DEFAULT_MS}.
+ */
 export type BrainCallGuardrailKnob = number | false;
+/**
+ * Resolve the knob to the effective limit, or `undefined` when the guardrail is off.
+ *
+ * FAIL-LOUD on a value that is neither: a negative / NaN / Infinity setting is a configuration bug,
+ * and silently folding it to a default (or to "off") is how an operator ends up believing a wedged
+ * run is bounded when nothing bounds it.
+ */
 export declare function resolveBrainCallGuardrailMs(knob: BrainCallGuardrailKnob | undefined): number | undefined;
+/** Records the FIRST guardrail expiry of a run, so the runner can give the task a typed terminal. */
 export interface BrainCallGuardrailRef {
+    /** Set once, by the first call the guardrail gave up on. Absent ⇒ the guardrail never fired. */
     timedOut?: BrainCallGuardrailTimeoutError;
 }
+/**
+ * Wrap a {@link StreamFn} so the ENGINE never waits longer than `limitMs` for one brain call.
+ *
+ * Every await point of the call is bounded: the `stream()` promise itself (a brain that never
+ * returns a stream), each iterator step (a brain that trickles events forever), and `result()` (a
+ * brain that opens a stream and never terminates it). The guardrail's clock starts when the call is
+ * issued and stops when the call ends — it bounds ONE call, not the turn and not the task.
+ *
+ * `return()` on the wrapped iterator forwards the inner cleanup WITHOUT awaiting it: the whole point
+ * is that the engine stops waiting on a brain, so releasing the iterator must not re-introduce a wait
+ * on the same hung code.
+ */
 export declare function withBrainCallGuardrail(streamFn: StreamFn, limitMs: number, ref: BrainCallGuardrailRef): StreamFn;

package/dist/brain/timeout.js

@@ -1,3 +1,4 @@
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export function resolveStallTimeoutMs(value, knob) {
     if (value === undefined)
         return undefined;
@@ -6,6 +7,11 @@ export function resolveStallTimeoutMs(value, knob) {
         e.code = "config.stall_timeout_invalid";
         throw e;
     }
+    if (value > MAX_TIMER_DELAY_MS) {
+        const e = new Error(`${knob} must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so this watchdog would abort every call instead of tolerating a long one (got ${String(value)}). Pass 0 to disable it.`);
+        e.code = "config.stall_timeout_invalid";
+        throw e;
+    }
     return value;
 }
 export const STALL_CONNECT_MS = 30_000;
@@ -66,6 +72,11 @@ export function resolveBrainCallGuardrailMs(knob) {
         e.code = "config.brain_call_guardrail_invalid";
         throw e;
     }
+    if (knob > MAX_TIMER_DELAY_MS) {
+        const e = new Error(`brainCallGuardrailMs must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so the backstop would abort every model call (got ${String(knob)}). Pass false or 0 to turn the backstop off.`);
+        e.code = "config.brain_call_guardrail_invalid";
+        throw e;
+    }
     return knob;
 }
 function armCallGuardrail(limitMs, outerSignal, ref) {

package/dist/brain/tool-call-id.d.ts

@@ -1 +1,21 @@
+/**
+ * REF-C5 — the ONE place a **fallback tool-call id** is minted.
+ *
+ * When a provider's wire frame carries no `id` for a tool call, the adapter must still hand downstream a
+ * non-`undefined`, process-unique handle: the whole execution/pairing chain keys on it (a tool_use must pair
+ * with its tool_result, and an in-stream executor's result must pair with the final content). Three adapters
+ * used to hand-roll the same `Math.random().toString(36)` short id with only their protocol prefix differing.
+ *
+ * The prefix is the caller's protocol identity (`toolu_` / `call_` / `repair_<name>_`) and is the ONLY
+ * parameter — the id BODY is deliberately opaque and uniform: no length/charset options, so there is exactly
+ * one collision profile to reason about for every lane.
+ *
+ * Zero-dependency leaf on purpose: `tool-call-repair.ts` is a pure parser with no runtime imports, so this
+ * must not drag a stream/telemetry dependency in. Internal module: not re-exported from `src/index.ts`.
+ */
+/**
+ * Mint a placeholder tool-call id under `prefix`. Uniqueness is per-process and probabilistic
+ * (`Math.random`), which is what every call site already relied on — the id never crosses a trust boundary
+ * and is never a capability; it only has to not collide inside one response.
+ */
 export declare function mintFallbackToolCallId(prefix: string): string;

package/dist/brain/tool-call-repair.d.ts

@@ -1,4 +1,17 @@
 import type { ToolCall } from "../internal/llm.js";
+/**
+ * Best-effort recovery of tool calls that a weaker (non-native-function-calling) model emitted as
+ * TEXT instead of structured tool calls. Recognizes `<tool_call>{...}</tool_call>` /
+ * `<function_call>...` tags and fenced ```json blocks containing `{name|tool, arguments|parameters|input}`
+ * (or an array of them). Only names present in `toolNames` are promoted.
+ *
+ * Returns the promoted tool calls and the text with those blocks removed. Off by default — enable via
+ * `createOpenAIBrain({ repairTextToolCalls: true })` only for models that need it.
+ *
+ * A fenced block must carry an arguments face to be promoted at all (HRD-BRN-3) and a block is only removed
+ * from the text when everything in it was promoted (HRD-BRN-3) — so this never fabricates a call out of a
+ * JSON object that merely names a tool, and never deletes text it did not turn into a call.
+ */
 export declare function repairTextToolCalls(text: string, toolNames: Set<string>): {
     toolCalls: ToolCall[];
     cleanedText: string;

package/dist/config/catalog.d.ts

@@ -1,29 +1,75 @@
+/**
+ * Config catalog (clay ruling 2026-07-19) — the SINGLE machine-readable source for the engineering
+ * configuration scale across every client (server / cli / TB harness / future shells).
+ *
+ * Why this exists: the same knob was found carrying FIVE different values across layers (maxTurns:
+ * core default 1000, TB cloud harness 80, a box-side adapter 500, cloud_companion 200, a server env
+ * cap) with no layer aware of the others. The catalog is the anti-chaos contract:
+ *
+ *   1. **Recommended values are imported from the live constants** — never hand-copied. A drift
+ *      between catalog and engine is a compile/test failure, not a doc bug.
+ *   2. **Clients don't hand-write numbers.** A client either inherits the recommendation (writes
+ *      nothing) or overrides it and DECLARES the override (`TaskSpec.configOverrides`, with a
+ *      reason). Declared overrides ride the `config.assembled` trace, so every run self-reports its
+ *      true knobs and their provenance — "who set 80" becomes a trace read, not archaeology.
+ *   3. **Announced change discipline** (clay): the recommendations are a living baseline — any repo
+ *      changing one (or overriding persistently) posts the change to the shared blackboard so the
+ *      scale evolves deliberately, together.
+ *
+ * v1 scope: the cross-client TASK-LAUNCH knobs (the chaos surface). Internal engine tuning
+ * (compaction thresholds, retry ladders…) stays out until a real cross-repo consumer appears.
+ */
 import type { TaskLimits } from "../core/types.js";
 export declare const CONFIG_CATALOG_VERSION = "sema-config@1";
 export interface ConfigKnob {
+    /** Dotted catalog key, e.g. `limits.maxTurns`. Stable — clients key parity probes off it. */
     key: string;
+    /** The recommended value. `null` = deliberately UNSET (the summary says what unset means). */
     recommended: number | boolean | string | null;
     unit?: "turns" | "seconds" | "ms" | "days" | "usd" | "tokens" | "count";
+    /** What kind of knob this is: a runaway safety net, a spend bound, a behavior switch, retention. */
     kind: "safety-net" | "budget" | "behavior" | "retention";
+    /** One-line semantics, including the meaning of unset and any derived-default coupling. */
     summary: string;
+    /** Who may set it and who wins (highest first). */
     precedence: string;
 }
+/** The v1 catalog. Recommended values reference the LIVE constants — the totality pin in
+ *  `test/config-catalog.test.ts` fails if an entry and its engine source diverge. */
 export declare function describeConfigCatalog(): {
     version: string;
     knobs: ConfigKnob[];
 };
+/**
+ * A host-layer override DECLARATION (`TaskSpec.configOverrides`) — the "changes must be announced"
+ * mechanical hook. A host that overrides a catalog knob at its own layer (env cap, adapter flag,
+ * harness default) attaches the declaration so the override rides the `config.assembled` trace with
+ * provenance `host-declared` instead of being invisible. Advisory: declarations are observability
+ * metadata — they do not themselves change any effective value.
+ */
 export interface ConfigOverrideDeclaration {
+    /** Catalog key (`limits.maxTurns`) — or a host-namespaced key (`tb.harness.maxTurns`) for knobs
+     *  that live entirely outside core. */
     key: string;
     value: number | boolean | string | null;
+    /** Why this deployment deviates from the recommendation — required; this is the announcement. */
     reason: string;
 }
 export type ConfigProvenance = "default" | "spec" | "derived" | "host-declared";
+/** One field of the effective-config manifest (`config.assembled`). */
 export interface EffectiveConfigField {
     key: string;
     value: number | boolean | string | null;
     provenance: ConfigProvenance;
 }
+/** Declaration bounds (codex): host strings ride the trace stream — bounded and sanitized, never
+ *  free-form. Beyond `MAX_OVERRIDE_DECLARATIONS` entries are dropped (count-capped, first-N kept). */
 export declare const MAX_OVERRIDE_DECLARATIONS = 32;
+/**
+ * Build the effective task-launch config + provenance from a spec's launch fields. Pure. The
+ * manifest must mirror ENGINE truth, not the spec's surface (codex): `maxOutputTokens` falls back
+ * to the model's own cap (provenance `derived`) before "provider default".
+ */
 export declare function resolveEffectiveConfig(spec: {
     limits?: Pick<TaskLimits, "maxTurns" | "maxWalltimeMs" | "maxOutputTokens" | "maxCostUsd" | "maxTokens">;
     resourceSuspend?: {
@@ -34,4 +80,5 @@ export declare function resolveEffectiveConfig(spec: {
 }, ctx?: {
     modelMaxTokens?: number;
 }): EffectiveConfigField[];
+/** Bounded, sanitized reasons map for the manifest's announcement face. */
 export declare function declarationReasons(declarations: readonly ConfigOverrideDeclaration[] | undefined): Record<string, string>;

package/dist/config/defaults.d.ts

@@ -1,4 +1,37 @@
+/**
+ * Dependency-free leaf module for engine default constants that `config/catalog.ts` needs as
+ * plain values. Extracted (design/157 S2) so the catalog no longer value-imports the modules that
+ * OWN these defaults (`core/runner/runtask.ts`, `agents/subagent.ts`, `core/session-store.ts`) —
+ * that import used to drag catalog.ts's runtime closure to 155 modules / 86119 lines (and formed
+ * the only size≥2 runtime SCC in the whole repo: catalog.ts ↔ runtask.ts). Each owning module now
+ * re-exports its constant(s) from here, so the original import surface (`import { X } from
+ * ".../runtask.js"`, etc.) stays byte-identical for every existing consumer.
+ */
+/**
+ * design/164 (ruled 2026-08-04): the engine no longer carries a per-task turn / wall-clock default at all.
+ * `DEFAULT_MAX_TURNS` (1000), `FORK_DEFAULT_MAX_TURNS` (200) and `SESSION_BG_DEFAULT_TIMEOUT_SEC` (30 min)
+ * are RETIRED — every task-level ceiling is now stated by the caller or absent.
+ *
+ * What replaced each obligation, so nothing is silently dropped:
+ *  - the runaway backstop is the ENGINEERING GUARDRAIL family (brain-call guardrail, stall watchdogs),
+ *    which answers "is the system hung" rather than "how much may this task spend";
+ *  - the design/129 anti-zombie duty for a session-scoped background child moved to the stale-running
+ *    reaper, which collects by STALL instead of by age (see TaskRegistry.reapStaleSessionBackgroundAgents):
+ *    a background task legitimately busy for two hours should not be killed at thirty minutes.
+ */
 export declare const RETAIN_DEFAULT_TTL_MS: number;
 export declare const RETAIN_DEFAULT_MAX = 16;
+/** Default idle TTL (days) before a cached session is evicted (config-catalog `session.idleTtlDays`). */
 export declare const SESSION_DEFAULT_TTL_DAYS = 7;
+/**
+ * RB-369 / RB-427-c — the shared cadence for RUNNING-state observability driven by a child's tool
+ * activity. A beat is one tool-lifecycle event (start or end); the FIRST beat always fires immediately
+ * (a short-lived agent must be observable at all), then at most one emission per this many beats.
+ *
+ * One constant, two consumers, deliberately: the workflow lane's running-record persist (RB-369) and the
+ * background-agent lane's intra-turn fleet beat (RB-427-c) are the same trade — a row that only moves at
+ * turn boundaries is frozen for as long as a turn lasts, and a row that moves per tool call is write /
+ * frame amplification on a tool-heavy child. A second, independently-tuned number for the same trade is
+ * how two surfaces describing one agent start disagreeing about how fast it is going.
+ */
 export declare const RUNNING_AGENT_OBSERVE_EVERY_BEATS = 4;

package/dist/core/a2a-task-state.d.ts

@@ -1,15 +1,68 @@
 import type { BackgroundAgentRecord } from "./background-agent-store.js";
+/**
+ * The protocol's task states, as ONE list — the type is derived from it, so a value and its type can
+ * never drift apart, and a consumer validating wire input iterates the same source the mapping does.
+ */
 export declare const A2A_TASK_STATES: readonly ["submitted", "working", "input-required", "completed", "canceled", "failed", "rejected", "auth-required", "unknown"];
+/** One A2A task state (see {@link A2A_TASK_STATES}). */
 export type A2ATaskState = (typeof A2A_TASK_STATES)[number];
+/**
+ * Durable row → protocol state. TOTAL and pure: every (status, stoppedBy) pair has an answer, and the
+ * answer depends on nothing else.
+ *
+ * The four direct arms:
+ * - `running` → `working`;
+ * - `completed` → `completed`;
+ * - `failed` → `failed`;
+ * - `parked` → `input-required`. This engine's `parked` is durably suspended ON AN APPROVAL CHECKPOINT
+ *   — a NARROWING of the protocol's "waiting for the caller to supply something": the something is an
+ *   approval decision, and it is redeemed through the durable approval inbox, not by a message reply.
+ *
+ * `killed` splits on the attribution, because the protocol distinguishes what this engine records in a
+ * second field: a stop by `user` or `parent` is a deliberate cancellation (`canceled`), while a
+ * `system` stop, an unrecognized source, or NO attribution at all is not — those are terminations the
+ * requester never asked for, and `canceled` would assert an intent nobody expressed. `failed` is the
+ * honest terminal for them.
+ *
+ * FOUR PROTOCOL STATES HAVE NO ARM HERE, as a fact of the type rather than an omission:
+ * - `submitted`, `rejected`, `auth-required` describe moments BEFORE a durable row exists (registration
+ *   and start are one step in this engine; rejection and an authorization demand are admission-time
+ *   outcomes of the serving layer, which has no row to project yet);
+ * - `unknown` belongs to the READ-PROJECTION layer one level up — the poll face's `not_local` arm,
+ *   where a `running` row was written by ANOTHER engine instance and this instance genuinely cannot
+ *   speak to its outcome. That arm has no record-level answer to give and never calls this function; a
+ *   caller holding a record, by contrast, always has the state. Keeping the two apart is the boundary
+ *   this function is drawn on.
+ * The switch is exhaustive over `status` with NO default arm, so tsc — not this comment — is what fails
+ * when a sixth durable status is added.
+ */
 export declare function toA2ATaskState(record: Pick<BackgroundAgentRecord, "status" | "stoppedBy">): A2ATaskState;
+/** A reversal that keeps everything the protocol state carried. */
 export interface A2ATaskStateReversalFaithful {
     lossy: false;
     status: BackgroundAgentRecord["status"];
 }
+/**
+ * A reversal that DROPPED something. `note` is required on this arm by construction: the whole purpose
+ * of the discriminant is that a consumer which branches on `lossy` cannot reach the lossy case without
+ * text describing what it lost.
+ */
 export interface A2ATaskStateReversalLossy {
     lossy: true;
     status: BackgroundAgentRecord["status"];
     note: string;
 }
+/** The result of {@link fromA2ATaskState}: discriminated on `lossy`. */
 export type A2ATaskStateReversal = A2ATaskStateReversalFaithful | A2ATaskStateReversalLossy;
+/**
+ * Protocol state → durable row status. Nine onto five, so five arms lose information; each of those
+ * says so (`lossy: true`) and names what it dropped, rather than returning a bare status that reads as
+ * an exact translation.
+ *
+ * `lossy: false` holds EXACTLY for the states that survive `toA2ATaskState(fromA2ATaskState(s))`
+ * unchanged — that biconditional is pinned as a property test (`test/a2a-task-state.test.ts`), so the
+ * flag is tied to an observable fact and not to an author's intent.
+ *
+ * The exhaustive switch (no default arm) makes a newly-declared protocol state a compile error here.
+ */
 export declare function fromA2ATaskState(state: A2ATaskState): A2ATaskStateReversal;

package/dist/core/a2a.d.ts

@@ -1,23 +1,46 @@
 import type { AgentTool } from "../internal/harness-types.js";
 import type { A2aServerSpec, ToolEffect } from "./types.js";
+/** The hard per-skill description bound (ruled 2026-08-03: ~2KiB). */
 export declare const A2A_SKILL_DESCRIPTION_MAX_CHARS = 2048;
+/**
+ * The safety axes carried alongside one materialized A2A tool, for `prepare-task` to fold into the SAME
+ * irreversible/egress collections first-party and MCP tools feed.
+ *
+ * Unlike MCP there is no server-hint leg to merge: the protocol has no per-skill annotation vocabulary,
+ * and a remote agent's self-declaration would not be trustworthy if it had one. Every A2A tool therefore
+ * starts at the ruled default (`egress:true`, `effect:"write"`) and the CALLER's
+ * {@link A2aServerSpec.toolAxes} is the only thing that can lower it (design F: caller = trust root).
+ */
 export interface A2aToolAxis {
+    /** Namespaced tool name (`a2a__<peer>__<skill>`). */
     name: string;
+    /** `"never"` appears ONLY via an explicit caller override — enforcement ignores it (tighten-only),
+     *  the ask's risk-axes report face consumes it. */
     irreversibility?: "always" | "never";
+    /** `false` appears ONLY via an explicit caller override — same posture: enforcement ignores it,
+     *  the report face consumes it (an explicit negative is a judgment, not silence). */
     egress?: boolean;
     effect?: ToolEffect;
 }
+/** design/99 §E9 equivalent for A2A — a per-peer projection of THIS materialization. A2A holds no
+ *  connection (every call is its own HTTPS request), so `ready` means "the card was fetched and its
+ *  skills were mounted at prepare time", never "the peer is alive right now". */
 export interface A2aPeerStatus {
     name: string;
     status: "ready" | "failed";
+    /** The card's self-declared name, neutralized + bounded (it rides consumer-rendered lines). */
     agentName?: string;
     agentDescription?: string;
+    /** The negotiated JSON-RPC endpoint this task will call. */
     endpoint?: string;
     toolNames?: string[];
     error?: string;
 }
+/** One per-peer entry of {@link MaterializedA2a.refresh}. */
 export interface A2aRefreshResult {
     peer: string;
+    /** The peer's namespaced-name prefix — the consumer's SPLICE DOMAIN for a wholesale swap (the same
+     *  self-healing prefix domain the MCP refresh receipt hands out). Present on every entry. */
     prefix: string;
     status: "refreshed" | "failed" | "disposed";
     toolCount: number;
@@ -27,16 +50,44 @@ export interface A2aRefreshResult {
     axes?: A2aToolAxis[];
     error?: string;
 }
+/**
+ * Tools materialized from one or more A2A peers.
+ *
+ * Deliberately NARROWER than {@link import("./mcp.js").MaterializedMcp}: A2A has no server-instructions
+ * channel and no intake schema gate, so there is no `serverInstructions`, no `instructionsDelta` and no
+ * `droppedTools` face — an absent face is honest, an empty one that can never fill is a face a consumer
+ * writes code against for nothing.
+ */
 export interface MaterializedA2a {
     tools: AgentTool[];
     toolAxes: A2aToolAxis[];
+    /** One entry per peer that could not be materialized and was SKIPPED (fail-open, design/29): the task
+     *  runs with the healthy peers' tools. The Runner forwards these to `onError(phase:"a2a")`. */
     warnings: Error[];
     statuses: A2aPeerStatus[];
+    /** Re-read one peer's card (or every declared peer) and re-derive its tools. Unlike the MCP refresh
+     *  this dials nothing new — every A2A call is a fresh request anyway — so a peer that failed at
+     *  prepare time can genuinely recover here. */
     refresh: (peer?: string) => Promise<A2aRefreshResult[]>;
+    /**
+     * Task teardown. There is no socket to close (every call is its own request), so what this owns is the
+     * LIFETIME statement: after it resolves, a tool that somehow still holds a reference fails loudly
+     * instead of talking to a remote agent on behalf of a task that has ended.
+     */
     dispose: () => Promise<void>;
 }
+/** A JSON-RPC error answered BY the peer (the exchange happened; the peer refused or failed). Carries the
+ *  numeric code for `instanceof`-plus-code discrimination — never message-text matching. */
 export declare class A2aRpcError extends Error {
     readonly code: number;
     constructor(peer: string, method: string, code: number, message: string);
 }
+/**
+ * Materialize every declared A2A peer into tools for one task.
+ *
+ * Peers are set up IN PARALLEL and merged in SPEC ORDER, so the tool roster (and therefore the system
+ * prompt's tool list and the prefix cache) is byte-identical regardless of which card answered first.
+ * `allSettled` keeps it fail-open: one unreachable peer is a skipped peer with a warning, never a task
+ * that cannot start.
+ */
 export declare function materializeA2aTools(specs: readonly A2aServerSpec[], principal?: string, signal?: AbortSignal): Promise<MaterializedA2a>;