@sema-agent/core 5.19.0 → 5.21.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## 5.21.0 — 2026-08-09
+
+### BREAKING
+
+- **`createGiteaIssueTool` / `GiteaIssueToolOptions` removed** (historical deletion). A single-vendor
+  HTTP integration from this repo's own early self-hosted era — the engine is the wrong layer for it.
+  A deployment that wants issue-filing mounts its own ToolSpec (~30 lines against its forge's API) or
+  an MCP server; nothing else in the engine referenced it.
+
+## 5.20.0 — 2026-08-08
+
+### BREAKING
+
+Configuration hygiene sweep. A malformed numeric knob used to be accepted and then quietly do
+something — usually the OPPOSITE of what it was set to. Every seam below now either refuses the
+value at its resolution point or clamps it and says so. Well-formed values in the documented range
+are untouched everywhere; the break is that values which used to be accepted-then-misbehave are
+now rejected, so a deployment carrying one gets a loud failure at wiring time instead of a
+mysterious runtime.
+
+- **MCP millisecond env knobs** (`MCP_TOOL_TIMEOUT`, `MCP_TOOL_TIMEOUT_TOTAL`,
+  `MCP_IDLE_TIMEOUT_STDIO`, `MCP_IDLE_TIMEOUT_HTTP`, `MCP_TIMEOUT`) share one parser, which was
+  `parseInt`-based: `1e9` meant 1ms, `30s` meant 30ms, and `100_000_000` — the way this repo writes
+  the default constant it invites you to copy — meant 100ms. Past 2^31-1 the host timer truncated
+  the delay and fired at once, so widening a watchdog to "basically off" made it abort every call,
+  while the failure text quoted the requested number back. The parser now reads plain digits,
+  scientific notation and digit grouping, refuses anything else, and clamps into
+  **[1000, 2147483647] ms**, warning once on stderr with the knob name, the raw text and the value
+  actually in force. Timeout frames quote the resolved value. `MAX_MCP_OUTPUT_TOKENS` moves onto the
+  same grammar (its `1e5` used to mean a 4-char budget), keeping upstream's unbounded range.
+  Upgrade note (the widening side of this fix): on 5.19.0 and earlier, `1e9` / `1_800_000` — both
+  legal upstream spellings — silently took effect as **1ms**. After upgrading they take effect at
+  face value, so a deployment that wrote one of these will see the knob jump from 1ms to the
+  number it always said.
+- **Millisecond knobs that arm a host timer** are refused above 2147483647ms (~24.8 days), where
+  the timer truncates and fires immediately: the stall watchdogs (`connectTimeoutMs`,
+  `firstTokenTimeoutMs`, `idleTimeoutMs`), `brainCallGuardrailMs`, `runWorkflow`'s `totalTimeoutMs`
+  / `stallMs` / `throttleBackoffMs`, and `createApprovalPolicy`'s `approvalTimeoutMs` — the last of
+  which would otherwise have denied every request instantly, fail-closed and silent. Each already
+  documents `0` / `false` / omission as "off". `limits.maxWalltimeMs` is the exception and keeps
+  its promise of no ceiling: the hard-abort timer now waits in representable chunks.
+- **Retention policies** (`BackgroundAgentStore.reap`, `MailboxStore.reap`, `WorkflowRunStore.reap`,
+  `reapDurableAgents`, both roster stores' constructors) refuse a non-finite or negative bound with
+  `config.retention_policy_invalid`. `keep` is consumed as `slice(Math.max(0, keep))`, where NaN
+  collapses to `slice(0)` and deleted EVERY terminal row in the scope; the roster's `maxAgeMs` made
+  every durable address read as expired. Absent fields keep their "this arm is not applied" meaning.
+  Operational note: this is a refusal, not a sanitize — a deployment with a malformed retention knob
+  will see every reap throw (rows accumulate) until the knob is corrected. Fix the knob before
+  upgrading; nothing is auto-repaired on your behalf.
+- **Web and circuit-breaker knobs**: `timeoutMs` on WebFetch / WebSearch / the Searxng backend fed a
+  bare `setTimeout`, where NaN and Infinity both become 1ms — a budget written as "no limit" aborted
+  every request on arrival and reported "timed out after NaNms". `maxResults` fed `slice(0, max)`,
+  so a NaN or 0 cap emptied every search from a backend that answered. The circuit breaker's
+  `failureThreshold` / `cooldownMs` / `halfOpenProbes` had no validation at all, and `failures >= NaN`
+  is false forever — an unevaluable threshold left the breaker permanently open-loop. All are now
+  resolved at assembly time (`config.web_timeout_invalid`,
+  `config.web_search_max_results_invalid`, `config.circuit_breaker_invalid`). `probeSearchBackend`
+  keeps its documented never-throws contract: a malformed budget comes back as `{ ok: false, error }`.
+
+### Added
+
+- **`Hooks.preToolUseObservational`** — a deployment declares that its PreToolUse face is a pure
+  OBSERVER (a tracer, an audit sink) and never judges. 5.19.0's delegation fold keys on PRESENCE,
+  which cannot tell a tracer from a screener: a deployment that flipped on a default-OFF diagnostic
+  hook thereby added an opaque constraint to every delegated child, and a child that durably parked
+  recorded that count on its row — where an approval redeemed by a leg that cannot re-supply the
+  live screening closure has no recovery path. With the declaration the face contributes **no
+  chain entry**, so `parentConstraintCount` counts only constraints that actually judge; without it,
+  5.19.0 behavior is unchanged. The callback still runs in the installing task's own gate, on every
+  call, with the same crash posture (a throw is still the fail-closed deny) — only the inherited
+  constraint goes away. A declared-observational face that returns something anyway has that return
+  **refused, not obeyed**: the call proceeds as if the face had no opinion (this covers
+  `additionalContext` too) and `onError` is told (`phase:"hook"`, classification
+  `observational-hook-verdict-ignored`), so the declaration cannot become a quiet way to keep a
+  screening face's verdicts while shedding the delegation constraint they belong to. A declared face
+  is also handed a **detached copy of the arguments** (best-effort, same helper and same limits as the
+  other observe-only payloads): the gate reads a rewrite off reference identity, so an in-place edit
+  would be a second channel outliving the dropped return. Two further consequences of "it does not
+  judge": a declared face no longer collapses an ancestor's screening entry that names the same
+  callback (the descendant no longer honors it, so the ancestor's constraint is folded instead), and it
+  no longer counts as an effect-aware gate for the loud ungated-write-surface warning.
+- **`createPreToolUseConstraintPolicy` is now a public export**, and a durable park under an inherited
+  screening constraint says so at PARK time. A checkpoint records only how many opaque constraints its
+  leg ran under; the resume must hand the same chain back. Every entry kind except one is a policy the
+  deployment authored — the screening entry 5.19.0 added is engine-minted, so a hook-wired tree's
+  parked children were redeemable only in the process that spawned them (same-Runner resumes are
+  auto-re-supplied from the in-memory registry and were never affected). The mint is now exported, so a
+  fresh Runner can rebuild the entry — same callback, same installed env — and hand the full chain to
+  `resumeStream(..., internals)`; the recorded-count check is unchanged, so a short or mismatched chain
+  is still refused pre-CAS. And the park itself now announces the requirement once per task on
+  `onError` (`phase:"degraded"`, classification `screening-constraint-in-durable-chain`), naming the
+  recorded count and the ways out, instead of leaving it to be discovered at a redemption that fails.
+
 ## 5.19.0 — 2026-08-10
 
 > Three bundles, each pre-verified two-way by the evaluation line against the 5.18.1 artifact
@@ -14,10 +107,15 @@
   four-axis dedup so a deps-level hook is consulted once per call at any depth). A screening
   `ask` resolves at the installing task's frozen approver; a hook-wired parent with no approver
   denies its children's screened calls fail-closed.
-  **Operational**: `parentConstraintCount` gains a screening entry for hook-wired trees — a
-  pending approval checkpoint minted before this change and resumed after (or the reverse)
-  fails pre-CAS with `resume.parent_constraint_mismatch`. **Drain pending checkpoints across
-  the upgrade.** A delegated child of a hook-wired parent also sets
+  **Operational (corrected per downstream measurement)**: `parentConstraintCount` gains a
+  screening entry for hook-wired trees. Pre-5.19.0 rows (including hook-wired parents) recorded
+  the old count and rebuild legs that supply it keep matching — upgrade and rollback are clean
+  for EXISTING pending checkpoints. The unrecoverable case is a checkpoint **minted on 5.19.0**
+  by a hook-wired parent and redeemed by a rebuild leg that cannot re-supply the live screening
+  entry (cross-replica redemption): it fails pre-CAS with `resume.parent_constraint_mismatch`
+  and stays pending, with no recovery path (the count is written at park time; disabling the
+  hook afterwards does not change it). Same-replica resumes via `resumeStream(..., internals)`
+  are unaffected. A delegated child of a hook-wired parent also sets
   `requiresParentConstraint`, so its durable resume must re-supply the chain via
   `resumeStream(..., internals)`.
 - **Write guards judge the call's live cwd** (P1, host-lane proven bypass). A resident shell's

package/dist/agents/agent-definition.d.ts

@@ -1,2 +1,9 @@
 import type { AgentDefinition } from "../core/types.js";
+/**
+ * Validate + freeze a declarative sub-agent definition (design/38 1B). A thin, fail-fast factory: it
+ * checks the only hard requirement (a non-empty `name`) and returns a shallow-frozen copy so a stored
+ * definition can't be mutated out from under the registry. Registry-level checks (name uniqueness,
+ * collision with reserved/tool names, model-ref resolution) happen when the set is handed to
+ * {@link createSubagentTool}, where the tool name + model catalog are available.
+ */
 export declare function defineAgent(def: AgentDefinition): AgentDefinition;

package/dist/agents/agent-transcript-tool.d.ts

@@ -1,15 +1,45 @@
 import { Type } from "typebox";
 import type { Runner } from "../core/runner/runtask.js";
+/** Model-facing name of the child-transcript read tool (residual lane C). */
 export declare const AGENT_TRANSCRIPT_TOOL_NAME = "AgentTranscript";
 export interface AgentTranscriptToolOptions {
+    /** Runner whose `sessions` store holds the child's persisted history. */
     runner: Runner;
+    /** The unified registry the background Agent lane registered its a* handles in (scopes reads to lineage). */
     registry: import("../core/task-registry.js").TaskRegistry;
+    /** design/151 S1b: the durable ledger — when the live row/retain entry is gone (restart, terminal GC,
+     *  retain off), the row's `sessionId` still anchors the PRESERVED transcript session (the S1b
+     *  lifecycle flip skipped its release). Reads go through `runner.sessions` — a split-store child
+     *  (caller-mounted Agent tool with its own runner) is honestly unreadable here after a restart. */
     agentStore?: import("../core/background-agent-store.js").BackgroundAgentStore;
+    /** Access identity (mirrors SendMessage/TaskOutput — the mount fills these). */
     owner?: string;
     scope?: string;
     sessionId?: string;
+    /**
+     * RB-409 seat, wired by RB-448 — the mount's per-call ctx builder, forwarded to {@link defineTool}
+     * (see {@link import("../core/tools.js").ToolCtxEnricher}). This tool is a `defineTool` PRODUCT, so
+     * without it the body sees exactly `{toolCallId, signal}` and `ctx.subagentRetain` below is always
+     * undefined — the run-scoped retain ledger has NO other channel (its own doc calls itself "threaded
+     * to delegation tools as the TRUSTED ctx.subagentRetain"), so the ordinary retained child this tool
+     * advertises reading was structurally unreachable and every such call fell through to the durable
+     * lane and then to "not retained". Same seat, same builder and same rationale as the SendMessage
+     * twin (RB-409 fixed it there and left this sibling — extracted from the same source file in
+     * design/157 A7 — behind). Absent ⇒ unchanged behavior: the `opts` axes alone supply the identity.
+     */
     enrichCtx?: import("../core/tools.js").ToolCtxEnricher;
 }
+/**
+ * Residual observability (lane C) — build the MODEL-VISIBLE **AgentTranscript** tool: read the last N tool steps of a
+ * previously spawned background agent ON DEMAND (a PULL face — it does NOT inflate the parent's context
+ * the way an injected residual would). `id` is the a* task_id the Agent tool returned. This is the
+ * complement to the stop-time residual (which the notification already carries): use it to look deeper
+ * into a child's tail when the residual isn't enough.
+ *
+ * Safety: reads are bounded to the parent's OWN lineage — the same non-leaking registry access scope as
+ * SendMessage/TaskOutput (an unknown or out-of-scope id reads identically to "not found"). Only a
+ * RETAINED child's session survives to be read; a throwaway child returns an honest "not retained".
+ */
 export declare function createAgentTranscriptTool(opts: AgentTranscriptToolOptions): import("../internal/harness-types.js").AgentTool<Type.TObject<{
     id: Type.TString;
     lastN: Type.TOptional<Type.TInteger>;

package/dist/agents/builtin-agents.d.ts

@@ -1,8 +1,68 @@
 import type { AgentDefinition } from "../core/types.js";
+/**
+ * F1 (design/135 批次3 / PARITY-SPOT-AGENT-TYPES-2026-07-10) — the CC 2.1.198 BUILT-IN `Explore` and
+ * `Plan` agent types, ported to sema's AgentDefinition roster shape.
+ *
+ * 198 锚 (亲核 2026-07-10, drift 调研: 198→204→206 逐字零漂移):
+ *  - Explore definition `qme` — pretty.js:409186-409198 (`agentType:"Explore"`, whenToUse=nbm,
+ *    whenToUseLean=rbm, `disallowedTools:[is,NR,s0,xa,Ic,FR]` = Agent/Artifact/ExitPlanMode/Edit/Write/
+ *    NotebookEdit, `model:"inherit"`, `omitClaudeMd:!0`, getSystemPrompt=tbm).
+ *  - Explore whenToUse `nbm` / whenToUseLean `rbm` — pretty.js:409173-409174 (verbatim below).
+ *  - Explore system prompt `tbm()` — pretty.js:409122-409160 (verbatim below, unix+Glob/Grep arm).
+ *  - Plan definition `Xor` — pretty.js:486943-486953 (`agentType:"Plan"`, single whenToUse, same six
+ *    disallowedTools, `tools: qme.tools` = undefined, `model:"inherit"`, `omitClaudeMd:!0`).
+ *  - Plan system prompt `kBm()` — pretty.js:486874-486930 (verbatim below, unix arm).
+ *  - Registry `HCe` — pretty.js:487221-487240: Explore+Plan ship behind `iAt()` (487127-487131:
+ *    env kill-switch `CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS` + `tengu_slate_ibis` gate DEFAULT ON)
+ *    ⇒ GA default-on in 198 (and byte-stable through 204/206 — CC-DRIFT-198-206-AGENT-TYPES 锚 1-7).
+ *    SDK entrypoints ship them too (only `claude-code-guide` is non-SDK); the SDK-form opt-out is
+ *    `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` (487221) → sema's deployment-config analog is
+ *    `SubagentToolOptions.builtinAgents: false` (config-driven, not env-driven).
+ *
+ * sema adaptations (deliberate, each recorded):
+ *  - De-branding (prompt-sovereignty / SUBAGENT_PROMPT precedent): CC's persona first sentences name the
+ *    product ("… for Claude Code, Anthropic's official CLI for Claude." / "… for Claude Code.") — sema
+ *    stays provider-neutral, the brand clause is dropped; every other byte is CC-verbatim.
+ *  - Platform arm: CC's `tbm`/`kBm` interpolate per-platform tool guidance (unix Bash vs PowerShell) and
+ *    a bash-only search mode (`ww()`). sema children run in a POSIX ExecutionEnv with first-party
+ *    Glob/Grep/Read/Bash under CC-identical names — the unix + Glob/Grep arm is baked verbatim
+ *    (Mu="Glob" :149761, Jc="Grep" :224202, Ls="Read", Lo="Bash").
+ *  - `model:"inherit"` — sema shape: `model` omitted on an AgentDefinition = inherit the caller's current
+ *    model (identical semantics). CC's Explore firstParty opus UPGRADE (`GAe`, 409162-409171: built-in
+ *    Explore may upshift to opus on first-party subscriptions) is a CC-subscription ladder concern —
+ *    NOT ported (sema is provider-neutral; inherit is the base arm both sides share).
+ *  - `omitClaudeMd:!0` (422063: drops the CLAUDE.md user-context layer for these types) — NOT ported this
+ *    round: sema's project-context layer is assembled in prepare-task (design/113 C4), a concurrent-batch
+ *    conflict domain at port time. Recorded as the F7 residual; the deployment `loadProjectMemory` seam
+ *    already receives `isSubagent`/`agentName` and can trim today.
+ *  - `disallowedTools` → `denyTools` (sema name), with the DELEGATION-tool entry tracking the deployment's
+ *    actual tool name (default "Agent" = CC-verbatim). "Artifact"/"ExitPlanMode" have first-party sema
+ *    referents only partially (present_plan canonicalizes to ExitPlanMode; Artifact has none) — a deny of
+ *    an unmounted name is a documented no-op (tool-filter), kept for CC listing-tail byte parity.
+ */
+/** CC 198 `nbm` (pretty.js:409173) — Explore `whenToUse`, verbatim. */
 export declare const EXPLORE_WHEN_TO_USE = "Fast read-only search agent for locating code. Use it to find files by pattern (eg. \"src/components/**/*.tsx\"), grep for symbols or keywords (eg. \"API endpoints\"), or answer \"where is X defined / which files reference Y.\" Do NOT use it for code review, design-doc auditing, cross-file consistency checks, or open-ended analysis \u2014 it reads excerpts rather than whole files and will miss content past its read window. When calling, specify search breadth: \"quick\" for a single targeted lookup, \"medium\" for moderate exploration, or \"very thorough\" to search across multiple locations and naming conventions.";
+/** CC 198 `rbm` (pretty.js:409174) — Explore `whenToUseLean`, verbatim. */
 export declare const EXPLORE_WHEN_TO_USE_LEAN = "Read-only search agent for broad fan-out searches \u2014 when answering means sweeping many files, directories, or naming conventions and you only need the conclusion, not the file dumps. It reads excerpts rather than whole files, so it locates code; it doesn't review or audit it. Specify search breadth: \"medium\" for moderate exploration, \"very thorough\" for multiple locations and naming conventions.";
+/** CC 198 Plan `whenToUse` (pretty.js:486945), verbatim (Plan has no lean variant in 198). */
 export declare const PLAN_WHEN_TO_USE = "Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs.";
+/** CC 198 `tbm()` (pretty.js:409122-409160) — Explore persona, unix+Glob/Grep arm, first sentence de-branded. */
 export declare const EXPLORE_SYSTEM_PROMPT = "You are a file search specialist. You excel at thoroughly navigating and exploring codebases.\n\n=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\nThis is a READ-ONLY exploration task. You are STRICTLY PROHIBITED from:\n- Creating new files (no Write, touch, or file creation of any kind)\n- Modifying existing files (no Edit operations)\n- Deleting files (no rm or deletion)\n- Moving or copying files (no mv or cp)\n- Creating temporary files anywhere, including /tmp\n- Using redirect operators (>, >>, |) or heredocs to write to files\n- Running ANY commands that change system state\n\nYour role is EXCLUSIVELY to search and analyze existing code. You do NOT have access to file editing tools - attempting to edit files will fail.\n\nYour strengths:\n- Rapidly finding files using glob patterns\n- Searching code and text with powerful regex patterns\n- Reading and analyzing file contents\n\nGuidelines:\n- Use Glob for broad file pattern matching\n- Use Grep for searching file contents with regex\n- Use Read when you know the specific file path you need to read\n- Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)\n- NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification\n- Adapt your search approach based on the thoroughness level specified by the caller\n- Communicate your final report directly as a regular message - do NOT attempt to create files\n\nNOTE: You are meant to be a fast agent that returns output as quickly as possible. In order to achieve this you must:\n- Make efficient use of the tools that you have at your disposal: be smart about how you search for files and implementations\n- Wherever possible you should try to spawn multiple parallel tool calls for grepping and reading files\n\nComplete the user's search request efficiently and report your findings clearly.";
+/** CC 198 `kBm()` (pretty.js:486874-486930) — Plan persona, unix arm, first sentence de-branded. */
 export declare const PLAN_SYSTEM_PROMPT = "You are a software architect and planning specialist. Your role is to explore the codebase and design implementation plans.\n\n=== CRITICAL: READ-ONLY MODE - NO FILE MODIFICATIONS ===\nThis is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:\n- Creating new files (no Write, touch, or file creation of any kind)\n- Modifying existing files (no Edit operations)\n- Deleting files (no rm or deletion)\n- Moving or copying files (no mv or cp)\n- Creating temporary files anywhere, including /tmp\n- Using redirect operators (>, >>, |) or heredocs to write to files\n- Running ANY commands that change system state\n\nYour role is EXCLUSIVELY to explore the codebase and design implementation plans. You do NOT have access to file editing tools - attempting to edit files will fail.\n\nYou will be provided with a set of requirements and optionally a perspective on how to approach the design process.\n\n## Your Process\n\n1. **Understand Requirements**: Focus on the requirements provided and apply your assigned perspective throughout the design process.\n\n2. **Explore Thoroughly**:\n   - Read any files provided to you in the initial prompt\n   - Find existing patterns and conventions using Glob, Grep, and Read\n   - Understand the current architecture\n   - Identify similar features as reference\n   - Trace through relevant code paths\n   - Use Bash ONLY for read-only operations (ls, git status, git log, git diff, find, cat, head, tail)\n   - NEVER use Bash for: mkdir, touch, rm, cp, mv, git add, git commit, npm install, pip install, or any file creation/modification\n\n3. **Design Solution**:\n   - Create implementation approach based on your assigned perspective\n   - Consider trade-offs and architectural decisions\n   - Follow existing patterns where appropriate\n\n4. **Detail the Plan**:\n   - Provide step-by-step implementation strategy\n   - Identify dependencies and sequencing\n   - Anticipate potential challenges\n\n## Required Output\n\nEnd your response with:\n\n### Critical Files for Implementation\nList 3-5 files most critical for implementing this plan:\n- path/to/file1.ts\n- path/to/file2.ts\n- path/to/file3.ts\n\nREMEMBER: You can ONLY explore and plan. You CANNOT and MUST NOT write, edit, or modify any files. You do NOT have access to file editing tools.";
+/**
+ * CC 198 `disallowedTools:[is,NR,s0,xa,Ic,FR]` (pretty.js:409189 Explore / :486948 Plan) — the six-tool
+ * deny set shared by both read-only built-ins, constants resolved 亲核: is="Agent"(147382),
+ * NR="Artifact"(143265), s0="ExitPlanMode"(149770), xa="Edit"(143358), Ic="Write"(143375),
+ * NotebookEdit FR(143373). The delegation-tool entry is parameterized on the deployment's actual tool
+ * name (default = "Agent", CC-verbatim).
+ */
 export declare const BUILTIN_READONLY_DENY_TOOLS: (delegationToolName?: string) => string[];
+/**
+ * Build the built-in agent definitions offered by {@link import("./subagent.js").createSubagentTool}
+ * (CC `HCe` registry analog, SDK arm: Explore + Plan; general-purpose is sema's OMITTED-`subagent_type`
+ * fallback and fork lives in the `subagent_type` value domain — neither needs a definition here).
+ * A deployment definition of the same name SHADOWS a built-in (fork-shadowing precedent), and
+ * `builtinAgents: false` removes them wholesale (CC `CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS` form).
+ */
 export declare function builtinAgentDefinitions(delegationToolName?: string): AgentDefinition[];

package/dist/agents/cascade.d.ts

@@ -1,24 +1,98 @@
 import type { Runner } from "../core/runner/runtask.js";
 import type { ModelRef, TaskResult, TaskSpec } from "../core/types.js";
+/**
+ * Quality-gate cascade (design/27). Run the SAME task across a ladder of models (cheapest → strongest);
+ * after each rung a caller-supplied **decidable gate** judges "good enough" — pass = keep it, fail =
+ * escalate to the next rung. Classic FrugalGPT cascade, as a thin function over `runner.runTask`
+ * (no Runner-core changes).
+ *
+ * APPLICABILITY: cascade only helps when the gate is **decidable** (a schema check, a verifier model, a
+ * concrete assertion). Open-ended "completeness" tasks (find every bug, writing quality) have no oracle —
+ * the gate keeps passing the first plausible cheap answer and escalation idles. Those want breadth /
+ * adversarial debate (a `team`), not a depth ladder.
+ *
+ * Cost note (design/27 §2): each rung is an independent COLD `runTask` — every escalation repays the
+ * full input cost. Cascade wins when (a) the cheap rung usually passes and (b) the prompt isn't so large
+ * that the restart tax dominates. It is NOT always cheaper than running the strongest model directly.
+ *
+ * Boundary vs teacher mode: teacher injects advice and continues the SAME session (recovery); cascade
+ * does independent re-runs on a model ladder (breadth). Orthogonal, not merged.
+ */
+/** A gate's verdict: a bare boolean, or `{ pass, diagnostics }` to attach reasoning to `attempts[]`. */
 export type GateVerdict = boolean | {
     pass: boolean;
     diagnostics?: string;
 };
 export interface CascadeRung {
+    /** The model this rung runs on. */
     model: ModelRef;
+    /** Optional per-rung overrides (default: inherit the task's). */
     overrides?: Partial<Pick<TaskSpec, "limits" | "systemPrompt">>;
 }
 export interface CascadeConfig {
+    /** RB-473 — disclosure channel for CONTAINED host-callback failures in this scope (the RB-463
+     *  isolation primitive's bounded first-failure per site). Absent ⇒ failures are counted only. */
     onNotifyError?: (failure: import("../core/safe-notify.js").SafeNotifyFailure) => void;
+    /** Model ladder, cheapest → strongest. ≥1 rung; the last rung is the fallback (returned even if it doesn't pass). */
     ladder: CascadeRung[];
+    /**
+     * Quality gate: given a rung's result, return whether it is good enough (true/`{pass:true}` = keep,
+     * false = escalate). Default: `status === "completed"` — and, if `spec.outputSchema` is set, also
+     * requires a valid `structuredOutput` (so a schema auto-gives "only keep a rung that actually produced
+     * valid structured output"; a prose-only completion escalates). The gate can be a pure check (structured
+     * output / fields), a verifier model, semantic agreement, etc. **A throw is treated as "did not pass"**
+     * (fail-open to escalate) and recorded as `attempts[].gateError` — so a broken gate can't strand the run,
+     * but a verifier-gate's own failure is still visible. The gate must be decidable (see APPLICABILITY).
+     *
+     * HRD-AGO-10 — a positive verdict is CONJOINED with the rung's status: it counts as a pass only when
+     * `result.status === "completed"`, unless {@link CascadeConfig.acceptPartial} is set. A status-blind gate
+     * ("the text is non-empty", "the JSON parses") could otherwise keep a blocked/failed/timeout rung, which made
+     * `cascadeOutcome: "passed"` disagree with the `status` the same object carries. A verdict rejected on those
+     * grounds is recorded as `passed: false` + {@link CascadeAttempt.statusRejected}, and the cascade escalates.
+     *
+     * @warning unredacted — the gate receives the UNREDACTED `TaskResult` (model output, structured output,
+     * stats); this is prose advisory, not an enforced boundary (design/54 §3.5, [46] DESIGN1). If your gate
+     * forwards output to an external service, ensure it has no sensitive data or sanitize first.
+     */
     gate?: (result: TaskResult, rung: {
         index: number;
         model: ModelRef;
     }) => GateVerdict | Promise<GateVerdict>;
+    /**
+     * HRD-AGO-10 — the explicit opt-out from the require-completed conjunction above. Two states, no middle:
+     * - **omitted / `false` (default)** — a {@link gate} pass counts only on a `completed` rung. Unfinished work
+     *   is escalated, so `cascadeOutcome: "passed"` always implies the returned rung actually finished.
+     * - **`true`** — the gate's verdict alone decides, so a deliberately partial answer can be kept (a blocked
+     *   rung whose partial output IS the deliverable, a timeout whose streamed prefix is good enough). The
+     *   returned `status` still reports the truth — this only says the gate is allowed to accept it.
+     *
+     * Ignored by the default gate, which requires `completed` in either case.
+     */
     acceptPartial?: boolean;
+    /** Max escalations (rungs run ≤ maxEscalations + 1). Default = `ladder.length - 1` (the whole ladder). */
     maxEscalations?: number;
+    /** Stop escalating once cumulative cost reaches this; return the current best. Optional. */
     costCeilingMicroUsd?: number;
+    /**
+     * Overall wall-clock ceiling for the whole cascade (per-rung time is `spec.limits.timeout`). Optional.
+     *
+     * HRD-AGO-7 — this is a REAL deadline over the run, not just a gate on starting the next rung: each rung is
+     * dispatched with an `AbortSignal` that fires at `start + totalTimeoutMs` (combined with the caller's own
+     * `spec.signal` when there is one), so a rung already in flight when the budget runs out is ABORTED. What
+     * "aborted" buys is bounded by the workload's cooperation with cancellation — the brain request is cancelled
+     * and a tool that honors its `ToolExecuteContext.signal` stops at once, but a tool that ignores its signal
+     * still runs to its own completion (the run then assembles as failed the moment it returns). Cleanup on a
+     * cut: the rung's result is NOT gated (truncated work must never pass), its session IS released (nothing
+     * pins it — a durable pause is handled earlier and returns instead), the attempt is recorded with
+     * `timedOut: true`, and the ladder stops (`cascadeOutcome: "exhausted"`) rather than escalating past a
+     * deadline that has already passed.
+     *
+     * A budget already spent AT ENTRY (`0`, negative, or a caller that measured elapsed time itself) dispatches
+     * NOTHING and returns the cascade's own terminal: `status: "failed"`, `errorCode:
+     * "cascade.budget_exhausted"`, empty `attempts`, `finalRung: -1`.
+     */
     totalTimeoutMs?: number;
+    /** Per-rung callback (observability). */
     onRung?: (info: {
         index: number;
         model: ModelRef;
@@ -30,20 +104,53 @@ export interface CascadeAttempt {
     index: number;
     model: ModelRef;
     passed: boolean;
+    /** This rung's OWN+nested spend. ABSENT when the rung ran unpriced (RB-368 knownness, codex batch-4
+     *  F4) — a fabricated 0 here both misreported the attempt and let escalation ride under a finite
+     *  ceiling the engine could not actually enforce. */
     costMicroUsd?: number;
     status: TaskResult["status"];
+    /** The rung's own failure code (e.g. "auth") if its `runTask` failed — distinct from "gate rejected it". */
     errorCode?: string;
+    /** Set when the gate THREW (vs returned false) — surfaces a broken verifier-gate (expired key, etc.). */
     gateError?: string;
+    /** HRD-AGO-7: this rung was CUT IN FLIGHT by {@link CascadeConfig.totalTimeoutMs}. Its result is truncated
+     *  work, so it was never handed to the gate (`passed` is always false) and the ladder stopped here. */
     timedOut?: true;
+    /** HRD-AGO-7: the CALLER's own `spec.signal` aborted during this rung (distinct from the cascade deadline).
+     *  Same handling — no gate, no escalation onto an already-aborted signal. */
     cancelled?: true;
+    /** HRD-AGO-10: the gate returned a PASS but the rung had not `completed`, so the verdict did not count
+     *  (`passed: false`, escalate). Set only in the default require-completed mode — never with
+     *  {@link CascadeConfig.acceptPartial}. */
     statusRejected?: true;
+    /** Optional reasoning the gate attached to its verdict. */
     diagnostics?: string;
 }
 export interface CascadeRunResult extends TaskResult {
+    /**
+     * The cascade's conclusion, **distinct from the inherited `status`**: `"passed"` = some rung passed the
+     * gate; `"exhausted"` = ladder/guards ran out with no rung passing (the last rung's result is returned,
+     * and its `status` may still be "completed" — judge the cascade by `cascadeOutcome`, not `status`).
+     */
     cascadeOutcome: "passed" | "exhausted";
+    /** F4: present when a finite `costCeilingMicroUsd` was configured but some rung's spend was unpriced —
+     *  the ceiling could not be enforced over unknown cost, so the ladder STOPPED escalating (fail-closed)
+     *  instead of riding an unbindable budget. Judge spend by the absent cost fields, not by 0. */
     costCeilingUnenforceable?: true;
+    /** True if the returned result came from a rung after the first (i.e. an escalation happened). */
     escalated: boolean;
+    /** Which rung (0-based) produced the returned result — or `-1` when NO rung was dispatched (an already
+     *  spent {@link CascadeConfig.totalTimeoutMs}); `attempts` is then empty and the result is the cascade's
+     *  own synthetic `cascade.budget_exhausted` terminal, not a rung's. */
     finalRung: number;
+    /** Per-rung audit detail (cost, pass/fail, why). Each attempt's `costMicroUsd` includes that rung's nested
+     *  (delegated) cost; the top-level `stats.costMicroUsd` is the sum of the rungs' OWN cost (nested totals live
+     *  in `stats.nested.costMicroUsd`), so it is NOT the plain sum of `attempts[].costMicroUsd`. */
     attempts: CascadeAttempt[];
 }
+/**
+ * Side-effect note: `runCascade` runs the task up to N times. If your tools have non-idempotent effects
+ * (`effect: "write"`), those execute once PER rung — ensure idempotency, or gate before the side effect
+ * (e.g. a structured-output gate). `TaskSpec` never guaranteed idempotency; cascade makes it explicit.
+ */
 export declare function runCascade(runner: Runner, spec: TaskSpec, config: CascadeConfig): Promise<CascadeRunResult>;

package/dist/agents/cumulative-stats.d.ts

@@ -1,29 +1,85 @@
 import type { TaskResult } from "../core/types.js";
+/**
+ * Shared CUMULATIVE-STATS constructor for the multi-leg agent compositions (cascade rungs, repair-loop
+ * attempts, teacher student attempts). All three run `runner.runTask` MORE THAN ONCE and must report the
+ * OPERATION's totals, not the last leg's.
+ *
+ * The invariant this exists to hold in ONE place: **every field the accumulator tracks is OVERRIDDEN over
+ * the base stats**. A field left un-overridden silently leaks the LAST leg's value dressed up as a
+ * cumulative total (the cascade R1-m5 / R3 trap; repair-loop shipped exactly that hole on `humanReview`).
+ * Three independent copies of this literal is how that hole survived in one copy while the other two were
+ * fixed — hence one constructor, three call sites.
+ *
+ * OWN and NESTED stay DISJOINT (the cascade R-5 / teacher A-7 convention): a consumer adds
+ * `stats.X + stats.nested.X` for the true total; nested cost is never folded into `costMicroUsd`.
+ */
+/** Cumulative delegated-subagent (nested) totals, summed across every leg. */
 export interface CumulativeNestedTotals {
     tokens: number;
     turns: number;
     tasks: number;
     costMicroUsd: number;
 }
+/**
+ * Cumulative human-review (design/91 C2 axis) burden, summed across every leg. `gates` is the ordered
+ * concatenation of each leg's gate entries — the element shape is the canonical one published on
+ * {@link TaskResult}, so a leg's entry passes through with `toolName`/`toolArg` intact.
+ */
 export interface CumulativeHumanReviewTotals {
     count: number;
     totalWaitMs: number;
     gates: NonNullable<TaskResult["stats"]["humanReview"]>["gates"];
 }
+/**
+ * The running totals a multi-leg composition accumulates. Every field is REQUIRED: an optional field here
+ * would re-open the exact "forgot to override one" hole this module exists to close — a caller that has
+ * nothing to report passes zeros.
+ */
 export interface CumulativeStatsAccumulator {
     tokens: number;
     turns: number;
     promptTokens: number;
+    /** RB-457-a: the cache-INCLUSIVE input total — its own leg, no longer derivable from `promptTokens` (the
+     *  cache-MISS sum). Also the cache-hit-rate denominator. */
     totalInputTokens: number;
     cachedTokens: number;
     outputTokens: number;
     cacheWriteTokens: number;
     cacheWriteTokensLong: number;
+    /**
+     * Cumulative own LLM cost (micro-USD) EXACTLY as the caller wants it published. Callers differ on the
+     * zero case on purpose and this constructor does not adjudicate: cascade/repair-loop publish a plain `0`
+     * (a run happened, it cost nothing measurable), teacher collapses `0` to `undefined` (the RB-368
+     * "unpriced spend is absent, not free" posture). Unifying the two is a BEHAVIOR change, not a refactor.
+     *
+     * Ignored entirely when {@link anyLegUnpriced} is set — see there.
+     */
     costMicroUsd: number | undefined;
+    /**
+     * TRUE when ANY contributing leg published no `costMicroUsd`, i.e. it ran on a model with neither a
+     * `RunnerDeps.pricing` entry nor a `Model.cost` declaration (`stats.costMicroUsd` is contractually
+     * ABSENT there — types.ts / RB-368 [2076]).
+     *
+     * Accumulating such a leg as `?? 0` publishes a total that is not one: the operation's real cost is
+     * unknown, and reporting the priced legs' partial sum makes "no price table" indistinguishable from
+     * "declared free" — the exact conflation the single-leg face refuses. So the knownness travels with the
+     * money: when this is set, `costMicroUsd` AND `costBreakdown` are both omitted from the cumulative
+     * stats, matching what a single unpriced `runTask` already reports. Token/turn totals are unaffected
+     * (they are knowable regardless of pricing).
+     */
     anyLegUnpriced: boolean;
+    /** Cumulative root-agent LLM cost for the `costBreakdown` taxonomy. */
     llmRootMicroUsd: number;
+    /** Cumulative within-task compaction LLM cost for the `costBreakdown` taxonomy. */
     compactionMicroUsd: number;
     nested: CumulativeNestedTotals;
     humanReview: CumulativeHumanReviewTotals;
 }
+/**
+ * Build the cumulative stats over a base (the FINAL leg's stats — it carries the non-accumulated fields
+ * such as `model`) with every accumulated field overridden.
+ *
+ * `cacheHitRate` is RE-DERIVED from the cumulative cached/total-input totals rather than spread from the
+ * base: a ratio is not additive, so the last leg's rate is never the operation's rate.
+ */
 export declare function buildCumulativeStats(base: TaskResult["stats"], acc: CumulativeStatsAccumulator): TaskResult["stats"];