@sema-agent/core 5.20.0 → 5.21.1

package/dist/brain/reasoning.d.ts

@@ -1,32 +1,137 @@
 import type { ThinkingLevel } from "../internal/harness-types.js";
+/**
+ * Unified reasoning-intensity abstraction (design/96 S3).
+ *
+ * The intensity a caller requests IS a {@link ThinkingLevel} — we reuse the existing 7-tier vendor scale
+ * (`off | minimal | low | medium | high | xhigh | max`) rather than forking a parallel "fast/standard/deep"
+ * enum, so there is ONE knob, not two that must be kept in sync. This module is the single place that maps a
+ * requested intensity to what a given endpoint can ACTUALLY honor, and reports the EFFECTIVE intensity — so a
+ * request that can't be honored as asked ("high" on a binary enable-only provider like qwen/zai, or
+ * "xhigh"/"max" on an endpoint whose `reasoning_effort` only accepts up to "high") is observable rather than
+ * silently swallowed or 422'd (design/96 §E honesty red-line; design/46 anti-drift).
+ *
+ * The brain (openai.ts / anthropic.ts) consumes this. Surfacing the effective intensity to a task result is a
+ * later config-domain slice (design/96 S6); here it is a pure, tested mapping.
+ */
 export type ReasoningIntensity = ThinkingLevel;
+/** Type guard: is `v` one of the 7 {@link ThinkingLevel} tiers? (A legacy/unknown reasoning string is not.) */
 export declare function isThinkingLevel(v: unknown): v is ThinkingLevel;
+/** Ordinal rank of a level (`off`=0 … `max`=6). */
 export declare function rankOf(level: ThinkingLevel): number;
+/**
+ * The `reasoning_effort` tiers an OpenAI-family endpoint accepts by DEFAULT. Conservative on purpose: a value
+ * the endpoint rejects 422s the whole request, so we ship the set stock OpenAI takes
+ * (`minimal | low | medium | high`) and clamp anything higher ("xhigh"/"max") down to "high". An endpoint that
+ * genuinely accepts a higher tier declares it via `compat.reasoningEffortLevels`.
+ */
 export declare const DEFAULT_EFFORT_LEVELS: readonly ThinkingLevel[];
-export type ReasoningFormat = "openai" | "openrouter" | "deepseek" | "together" | "zai" | "qwen" | "qwen-chat-template" | "budget" | "effort";
+/**
+ * The per-provider thinking wire format (mirrors `compat.thinkingFormat`). `"budget"` is the synthetic tag for
+ * Anthropic's extended-thinking budget path (no `thinkingFormat` — the anthropic brain doesn't read one), kept
+ * here so {@link resolveReasoning} can report ONE endpoint discriminant across both brain families.
+ */
+export type ReasoningFormat = "openai" | "openrouter" | "deepseek" | "together" | "zai" | "qwen" | "qwen-chat-template" | "budget"
+/** Anthropic `output_config.effort` (CC 2.1.198 / Fable-5 class, design/119): the tier is a named
+ *  effort string, clamped to `compat.effortLevels` — the anthropic-side twin of the OpenAI
+ *  `reasoning_effort` path (thinking FORM is `thinkingMode`; effort carries the intensity). */
+ | "effort";
+/** How a requested intensity resolved against one endpoint's real capability. */
 export interface ReasoningResolution {
+    /** The level the caller asked for. */
     requested: ThinkingLevel;
+    /** The level actually in effect after mapping to what the endpoint accepts. */
     effective: ThinkingLevel;
+    /**
+     * True when the endpoint varies behavior by intensity (effort tiers / token budget). False = binary
+     * enable-only (qwen / zai / qwen-chat-template, or an effort endpoint that declares
+     * `supportsReasoningEffort:false`): thinking is on or off and the tier is NOT honored — read this alongside
+     * {@link effective}, which then echoes the request as intent only.
+     */
     graded: boolean;
+    /** True when {@link effective} differs from {@link requested} (the request couldn't be honored exactly). */
     clamped: boolean;
 }
+/**
+ * A {@link ReasoningResolution} enriched with the endpoint discriminant, for observability (design/96 S6).
+ * The brain consumes only the {@link ReasoningResolution} fields to shape the request; `format`/`endpoint`
+ * are reported (e.g. a `reasoning.resolved` trace event) so a deployment can see WHY a tier was downgraded
+ * (binary provider) or clamped (effort-set cap) rather than the resolution being silently swallowed (§E honesty).
+ */
 export interface ResolvedReasoning extends ReasoningResolution {
+    /** The wire format the request will use (the load-bearing reason for `graded`/`clamped`). */
     format: ReasoningFormat;
+    /** A coarse endpoint label for the trace (`model.api` — e.g. `openai-completions`, `anthropic-messages`). */
     endpoint: string;
 }
+/**
+ * Resolve a requested intensity against a model END-TO-END, dispatching on its wire format the SAME way the
+ * brains do — so a trace event and the actual provider request can never drift (design/96 S6). This is the
+ * single observability-side resolver: the runner calls it at task start to emit `reasoning.resolved`; the
+ * brains keep calling {@link resolveEffort}/{@link resolveBinary}/{@link reasoningBudgetShare} on the hot path.
+ *
+ * - Anthropic (`api === "anthropic-messages"`) → budget-based: the tier sets a budget share, so it's a real
+ *   gradient (`graded:true`) and never tier-clamped (`clamped:false`); reported as `format:"budget"`.
+ * - Binary enable-only formats (qwen / zai / qwen-chat-template) → `graded:false` (tier not honored).
+ * - An effort endpoint with `supportsReasoningEffort:false` → `graded:false` (enable key only, no effort tier).
+ * - Otherwise effort-based → clamp DOWN to the endpoint's `reasoningEffortLevels` (default minimal|low|medium|high).
+ *
+ * `off`/falsy never enables thinking, so it resolves trivially (no clamp, graded:true) — the caller decides
+ * whether to emit at all.
+ */
 export declare function resolveReasoning(requested: ThinkingLevel, model: {
     api?: string;
     reasoning?: boolean;
     compat?: unknown;
 }): ResolvedReasoning;
+/**
+ * Resolve a requested intensity for an effort-based endpoint (`reasoning_effort` / `reasoning.effort`). Picks
+ * the requested tier when supported; otherwise the highest supported tier ≤ requested (clamp DOWN, never
+ * silently up); if none is ≤ requested (the endpoint's set is entirely higher — unusual), the lowest supported
+ * tier. Never returns a value outside `allowed`, so the brain can't emit a tier the endpoint would 422.
+ */
 export declare function resolveEffort(requested: ThinkingLevel, allowed?: readonly ThinkingLevel[]): ReasoningResolution;
+/**
+ * Resolve a requested intensity for a binary enable-only endpoint (qwen / zai / qwen-chat-template): the
+ * provider only takes an on/off switch, so the intensity tier is NOT honored as a gradient. `graded: false`
+ * is the load-bearing honesty signal.
+ */
 export declare function resolveBinary(requested: ThinkingLevel): ReasoningResolution;
+/**
+ * Extended-thinking budget as a FRACTION of `max_tokens` per intensity tier, for budget-based endpoints
+ * (Anthropic). Lets a higher intensity actually buy a larger thinking budget — before this, the budget was a
+ * fixed share regardless of the requested tier, so the intensity had no effect on Anthropic (design/96 §D/§E).
+ * The brain clamps the resulting budget to Anthropic's `[1024, max_tokens-1]` window; an explicit
+ * `thinkingBudgetTokens` / `thinkingBudgetShare` in config still overrides this table.
+ */
 export declare const REASONING_BUDGET_SHARE: Record<ThinkingLevel, number>;
+/** The extended-thinking budget share for a given intensity tier (see {@link REASONING_BUDGET_SHARE}). */
 export declare function reasoningBudgetShare(level: ThinkingLevel): number;
+/**
+ * design/96 §D (S4) — a user-facing NAMED reasoning tier, DISTINCT from the raw 7-tier {@link ThinkingLevel}
+ * ({@link ReasoningIntensity}). A profile maps it to engine flags via {@link resolveReasoningProfile}. This is
+ * the "ultracode" parity axis: a high tier (`ultra`) buys both a higher thinking level AND a thoroughness/
+ * self-verify prompt nudge.
+ */
 export type ReasoningTier = "off" | "fast" | "standard" | "deep" | "ultra";
+/** The engine flags a {@link ReasoningTier} resolves to (design/96 §D table). A profile may override the
+ *  default; core ships sane defaults. */
 export interface ReasoningProfileFlags {
+    /** The vendor thinking level to run at (clamped per-endpoint downstream by {@link resolveEffort}). */
     thinking: ThinkingLevel;
+    /**
+     * Compose `ORCHESTRATION_AWARENESS` — a high-tier thoroughness/self-verify nudge. 🔴 NOT the `run_workflow`
+     * tool (that is gated by a hard sandbox, S8 §6.3); this is purely about how the model reasons. Independent
+     * of self-orchestration (a task can be both).
+     */
     awarenessGuidance: boolean;
+    /** Advisory HINT that goal mode suits this tier. Core NEVER forces intensity→mode (constitution: the
+     *  mapping is profile data); a profile/caller decides whether to actually run `runGoal`. */
     goalSuggested: boolean;
 }
+/**
+ * design/96 §D (S4) — map a named {@link ReasoningTier} to its engine {@link ReasoningProfileFlags} (default
+ * mapping). G2 (clay): the intensity→capability mapping is PROFILE-layer data — core gives this primitive +
+ * a sane default; a profile/scenario layer calls it (and may override the table) to set a task's `thinking` +
+ * prompt flags. Core never forces it. Returns a fresh COPY (callers may mutate).
+ */
 export declare function resolveReasoningProfile(tier: ReasoningTier): ReasoningProfileFlags;

package/dist/brain/repetition.d.ts

@@ -1,15 +1,98 @@
+/**
+ * Detect **degenerate repetition** — the most common LLM failure mode: a model that gets stuck
+ * emitting the same character or short phrase forever (often with no punctuation), e.g. `啊啊啊啊…`
+ * or `the answer is the answer is the answer is…`. Brains poll this over the growing output and, on a
+ * hit, **cancel the stream** and mark the turn errored, so the loop doesn't keep paying for garbage and
+ * downstream (e.g. a team member) treats it as a failed turn rather than a real statement.
+ *
+ * Only an *exact* tail repetition trips it (character-for-character). The original header claimed
+ * normal code "won't false-positive" because repeated structure differs in content — **falsified in
+ * the field** (docs/DEADTARGET-WINNING-AVG-COREWARS-2026-07-10.md §〇-3): legitimate code repeats the
+ * SAME line verbatim (redcode boot blocks `mov <bootsrc, {bootdst` ×6-8, SQL fixture rows, ASCII-art
+ * banners), landed exactly in the rule-2 window, and the cut stream three-struck whole TB tasks dead.
+ * Hence two structural allowances, both bounded so true runaway loops are still caught:
+ *   - rule 1 exempts short symbol runs (ASCII dividers) — a run of a non-letter/digit char only
+ *     counts as degenerate past `CHAR_RUN_SYMBOL`;
+ *   - rule 2 exempts *code-line-shaped* units (full-line repeats carrying operand/structure chars or
+ *     indentation) unless the loop SATURATES the inspection window AND is `SATURATION_REPS` deep in the
+ *     output — no legitimate boot block is 16+ identical lines deep with nothing after it.
+ *
+ * Known residual (HRD-BRN-2): rule 2 itself never fires for a unit longer than ~66 chars, because reaching
+ * `MIN_REPS` inside the fixed 400-char window requires `p ≤ WINDOW/MIN_REPS`. That is rule 2's general
+ * geometry (it applies to prose units too), not the code-line allowance, and widening it means growing
+ * the window — deliberately left alone rather than traded for false cuts on long legitimate lines.
+ */
+/**
+ * The errorMessage a brain stamps on a turn it cut off for degenerate repetition — the human-readable
+ * DISPLAY text, and nothing more. It is a single exported constant so the brains do not each invent their
+ * own wording, but it is no longer the cross-layer signal: since RB-482 #12 the detection contract is
+ * `AssistantMessage.errorKind === "degenerate"` (read via `isDegenerateCutMessage` in
+ * ./terminal-cause.js), which `assembleResult` maps to `errorCode="output.degenerate"` + salvages the
+ * turn text (design/39). Reword this freely; do NOT match on it. Wording: the output is salvaged now,
+ * not discarded.
+ */
 export declare const DEGENERATE_MESSAGE = "degenerate repetition detected \u2014 the model looped on the same text; output cut off at the repetition";
+/**
+ * One detector hit — either the event that CUT a stream (`degenerate`) or a repetition that landed in
+ * a detection window but was SPARED by a 2e1c161 structural allowance (code-line shape / divider run).
+ * Spared events are the RSI raw material for judging whether the allowance is too wide or too narrow
+ * (clay 2026-07-10: the detector must report counts AND the detected segment, not just a boolean).
+ */
 export interface RepetitionEvent {
+    /** Which rule's window the repetition landed in: rule 1 (`char-run`) or rule 2 (`unit-loop`). */
     rule: "char-run" | "unit-loop";
+    /** Repeating-unit length in chars (1 for a char run). */
     period: number;
+    /** How many times the unit repeated (the run length for a char run). */
     reps: number;
+    /** Sample of the repeated unit/tail, truncated to ≤{@link SEGMENT_MAX} chars. */
     segment: string;
 }
+/** Structured result of one detector pass over a (growing) output tail. */
 export interface RepetitionInspection {
+    /** True ⇒ a degenerate loop tripped — the caller should cut the stream (same verdict as `looksDegenerate`). */
     degenerate: boolean;
+    /** The event that tripped; present iff `degenerate`. */
     cut?: RepetitionEvent;
+    /** Allowance-spared hits (at most one per rule per pass — the smallest period is the fundamental one). */
     spared: RepetitionEvent[];
 }
+/**
+ * Structured detector pass: same verdict as {@link looksDegenerate}, plus WHAT hit (`cut`) and what
+ * the 2e1c161 allowances spared. Spared collection is bounded: at most one `char-run` and one
+ * `unit-loop` event per pass (rule 2 keeps the smallest period — the fundamental unit — so a p and
+ * its 2p/3p multiples don't report the same loop several times).
+ */
 export declare function inspectDegenerate(text: string): RepetitionInspection;
 export declare function looksDegenerate(text: string): boolean;
+/**
+ * T1-4 (brain stream-layer truncation): drop the degenerate TAIL off the text face that tripped a
+ * cut, keeping ONE instance of the repeating unit, so the salvaged prefix lands in the final
+ * assistant content / `salvagedOutput` without hundreds of chars of loop garbage (which the loop's
+ * bounded degenerate-recovery continue would otherwise re-feed the model as context — the very text
+ * it must not repeat).
+ *
+ * Always-on by design (no opt-out flag). The honest argument (fable review tightened the original
+ * "zero information loss" claim):
+ *  - everything removed is a byte-identical duplicate of the unit that is KEPT, so no UNIQUE text is
+ *    ever swallowed (a non-repeating tail never matches and is returned unchanged). What CAN be lost
+ *    is a repetition COUNT: if the legitimate text immediately before the loop happened to end with
+ *    the same unit repeated (e.g. an intentional "very very" directly abutting a "very"-loop), those
+ *    legitimate repeats fold into the loop and collapse to the single kept instance. This only ever
+ *    happens on a stream the detector ALREADY cut as degenerate, and the alternative is worse (the
+ *    full loop tail re-fed to the model);
+ *  - most legitimate verbatim repetition (code lines, dividers) never gets here at all — the 2e1c161
+ *    allowances spare it upstream, and a spared stream is never cut;
+ *  - the loop may have grown far past the 400-char inspection window before the poll fired; the
+ *    scan below strips ALL trailing repeats (and one trailing PARTIAL unit from post-cut buffered
+ *    deltas), not just the reps the window measured.
+ *
+ * Fail-safe floor: the trim only fires when the tail ends with ≥2 exact repeats of the cut event's
+ * unit — a WRONG-face call (e.g. the cut tripped in thinking, this is the text face) is structurally
+ * a no-op unless that face coincidentally ends with ≥2 exact unit repeats (in which case those — and
+ * any partial-unit suffix stripped with them — fold like any other repeats; same bounded cost as
+ * above). Thinking/reasoning faces are deliberately never trimmed by the brains: anthropic thinking
+ * blocks are signature-sealed for replay (mutating them invalidates the signature), and neither face
+ * reaches `salvagedOutput`.
+ */
 export declare function trimDegenerateTail(text: string, cut: RepetitionEvent): string;

package/dist/brain/request-params.d.ts

@@ -1,9 +1,65 @@
+/**
+ * Request-parameter passthrough (design/40). A deployment can set official provider params it wants but
+ * core doesn't model as first-class fields (OpenAI `frequency_penalty`/`presence_penalty`/`top_p`/`seed`/
+ * `logit_bias`; Anthropic `top_k`/`top_p`/`stop_sequences`; …) via `Model.extraBody`, and core merges them
+ * into the brain's request body. Anchored at the **Model** level (not per-turn) so the serialized body
+ * stays byte-stable across turns → the prefix cache holds (design/9/31).
+ *
+ * Symmetric: each brain owns its structural + tuning keys (`reserved`) and ALWAYS wins — `extraBody` can
+ * only supply the long tail, never clobber `messages`/`tools`/`temperature`/etc. Stripping is the safety
+ * enforcement (the brains are standalone-usable); `prepareTask` separately warns on a collision (it has
+ * `onError`, the brain doesn't — council design/40).
+ */
+/** OpenAI request-body keys core owns; `extraBody` cannot override these. */
 export declare const OPENAI_RESERVED: ReadonlySet<string>;
+/** Anthropic request-body keys core owns; `extraBody` cannot override these. (Note the asymmetry vs
+ *  OpenAI — e.g. `stop`/`stop_sequences` is NOT reserved here because the Anthropic brain never sets it.) */
 export declare const ANTHROPIC_RESERVED: ReadonlySet<string>;
+/**
+ * Open Responses request-body keys core owns; `extraBody` cannot override these (design/163).
+ *
+ * The last three are NOT keys the adapter sets — they are keys it must be IMPOSSIBLE to set. The
+ * Open Responses lane is stateless by contract (this engine is the transcript authority), and
+ * `extraBody` is the only other path to the request body, so `store` / `previous_response_id` /
+ * `conversation` are reserved purely to close it. A deployment that sets one gets the design/40
+ * collision warning at load and a stripped key on the wire, never a silently server-linked turn.
+ */
 export declare const RESPONSES_RESERVED: ReadonlySet<string>;
+/** Reserved set for a model's API. */
 export declare function reservedFor(api: string): ReadonlySet<string>;
+/**
+ * Merge `extraBody` into a brain's already-built request `body`, dropping any key the brain owns so core
+ * always wins. Returns a NEW object (passthrough keys first, then core keys) when `extraBody` is set; the
+ * exact `body` reference (no allocation, byte-identical serialization) when it isn't — so an existing
+ * deployment with no `extraBody` is unaffected.
+ */
 export declare function applyExtraBody(body: Record<string, unknown>, extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): Record<string, unknown>;
+/**
+ * [1282] per-call auth REPLACES construction-time auth: drop every auth-bearing header
+ * (case-insensitive `authorization` / `x-api-key`) from an already-merged header bag. Called by a
+ * brain's buildRequest ONLY when a per-call `options.apiKey` is present — the brain then re-emits
+ * the credential in its own wire posture (anthropic `x-api-key`, openai `Bearer`), making the
+ * per-call key the request's single credential. Case-insensitivity matters twice: a
+ * construction-time `Authorization` (capital A) is what boot env tokens ship, and a case-variant
+ * duplicate would otherwise ride the wire alongside the hard-locked lowercase form (fetch Headers
+ * folds duplicates into one comma-joined value — broken auth both ways).
+ */
 export declare function stripAuthHeaders(headers: Record<string, string>): void;
+/**
+ * The output-cap key(s) each lane's wire form uses. A lane's set is exactly the keys THAT lane's
+ * endpoint reads — a stray cap key belonging to another wire form is inert there and must not be
+ * mistaken for a bound this request carries.
+ */
 export declare const OUTPUT_CAP_KEYS: Readonly<Record<"openai" | "anthropic" | "responses", readonly string[]>>;
+/**
+ * The per-request output cap a FINAL (post-`extraBody`) request body actually carries — the SMALLEST
+ * of the lane's cap keys that is present and usable, or `undefined` when none is.
+ *
+ * Read off the merged body rather than off the knob the adapter set, because those are not the same
+ * thing: `extraBody` can contribute a cap under a spelling the adapter did not choose, and a
+ * consumer that treats the adapter's own number as "the cap on the wire" would be wrong about a
+ * request that carries two. Smallest wins so a consumer reasoning about the bound stays conservative.
+ */
 export declare function effectiveOutputCap(body: Record<string, unknown>, keys: readonly string[]): number | undefined;
+/** Names in `extraBody` that collide with a reserved (core-owned) key — for a load-time warning. */
 export declare function reservedCollisions(extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): string[];

package/dist/brain/retry.d.ts

@@ -1,8 +1,54 @@
+/**
+ * Transient-failure retry backoff (RB-420-b, CC 2.1.220 parity).
+ *
+ * The shape is **increasing exponential + light additive jitter**, not full jitter:
+ * `min(base * 2^attempt, 32s)` plus up to 25% of that. Full jitter (`random(0, exp)`) made the Nth
+ * wait routinely SHORTER than the first, which destroys the one property a rate-limited provider
+ * needs from a client — that each successive attempt backs further off. The 25% additive spread is
+ * still enough de-synchronization to keep many clients from re-converging into a thundering herd.
+ *
+ * Provider wait hints ride at ONE layer above the computed value, both as a FLOOR
+ * (`max(hint, computed)`) — retrying before the server said just gets rejected again, but a hint must
+ * never SHORTEN a backoff we already escalated past it:
+ * - `Retry-After` (delta-seconds or HTTP-date), on any retryable response.
+ * - `anthropic-ratelimit-unified-reset` (an absolute epoch-seconds stamp of when the rate-limit window
+ *   reopens), read only off a 429 — it is a rate-limit signal.
+ * When both are present the larger wins. Both are clamped so a hostile/buggy value
+ * (`Retry-After: 2147483647`, a reset stamp years out) cannot pin the caller for hours.
+ */
+/** Parse a `Retry-After` header (delta-seconds or HTTP-date) to ms; undefined if absent/unparseable. */
 export declare function parseRetryAfter(res: Response | undefined): number | undefined;
+/**
+ * Parse `anthropic-ratelimit-unified-reset` — an ABSOLUTE epoch-seconds stamp of when the unified
+ * rate-limit window reopens — into ms from now. Undefined when absent, unparseable, or already past
+ * (a stale stamp carries no wait, so the caller falls back to its computed backoff).
+ */
 export declare function parseRateLimitReset(res: Response | undefined): number | undefined;
+/**
+ * A single provider wait hint after clamping, carrying enough of its own history to disclose a
+ * truncation: `rawMs` is only set when the response actually asked for more than {@link
+ * MAX_HEADER_WAIT_MS} and the hint was cut down to it.
+ */
 export interface ProviderWaitHint {
+    /** The value honored (post-clamp), ms. */
     readonly ms: number;
+    /** The value the response asked for, ms — present only when it exceeded the clamp. */
     readonly rawMs?: number;
 }
+/** The larger of the response's two wait hints, each clamped; undefined when the response carries
+ *  neither (or only stale/unparseable ones). Exported so a caller can disclose a truncation instead
+ *  of silently honoring less than the response asked for.
+ *
+ *  Ranks by the CLAMPED `ms` first (that is the value actually honored — unchanged from before this
+ *  hint carried `rawMs`), but a tie there is broken by the UNCLAMPED value: two hints can clamp to the
+ *  same 60s ceiling while asking for very different waits (`Retry-After: 60` vs a reset a day out), and
+ *  picking whichever came first would silently return the one with no `rawMs` — reporting the smaller
+ *  ask as if nothing had been truncated at all, even though the pair's honored wait is identical either
+ *  way. */
 export declare function providerWaitHint(res: Response | undefined): ProviderWaitHint | undefined;
+/**
+ * Backoff (ms) for retry `attempt` (0-based) of a transient failure: an increasing capped exponential
+ * plus ≤25% additive jitter, floored by the response's provider wait hints (see the module note).
+ * `rand` is injectable for deterministic tests.
+ */
 export declare function retryBackoffMs(baseDelayMs: number, attempt: number, res?: Response, rand?: () => number): number;

package/dist/brain/routing.d.ts

@@ -1,6 +1,18 @@
 import type { Brain } from "../core/types.js";
 export interface RoutingBrainOptions {
+    /** Which field of the Model selects the route. Default "provider". */
     by?: "provider" | "api";
+    /** Brain used when no route matches. If omitted, an unmatched model yields an error. */
     fallback?: Brain;
 }
+/**
+ * Route to different brains by a Model field (default `model.provider`). Lets one Runner serve
+ * multiple providers/gateways; compose with `createFailoverBrain` for per-route failover.
+ *
+ * @example
+ * createRoutingBrain({
+ *   "vllm":   createOpenAIBrain({ baseUrl: VLLM }),
+ *   "openai": createOpenAIBrain({ baseUrl: OPENAI, apiKey }),
+ * }, { fallback: createOpenAIBrain({ baseUrl: VLLM }) });
+ */
 export declare function createRoutingBrain(routes: Record<string, Brain>, opts?: RoutingBrainOptions): Brain;

package/dist/brain/status-sink.d.ts

@@ -1,6 +1,29 @@
 import type { BrainStatus } from "../core/types.js";
+/** Run `fn` with a per-task brain-status sink in scope. ALS propagates it through the async brain calls
+ *  inside `fn` (the harness's prompt → brain.stream → connect/retry loop), so {@link emitBrainStatus}
+ *  reaches THIS task's sink and nothing else. */
 export declare function runWithStatusSink<T>(emit: (s: BrainStatus) => void, fn: () => Promise<T>): Promise<T>;
+/**
+ * Report a brain-layer liveness status to the active per-task sink, if any. A no-op outside a
+ * {@link runWithStatusSink} scope (e.g. compaction's `complete`, or a brain used standalone).
+ *
+ * HRD-BRN-6: swallow-guarded, like its sibling {@link emitBrainTelemetry} — an ADVISORY frame must never
+ * change a brain call's outcome. It could: the emit forwards straight into deployment-supplied code, and
+ * the circuit breaker's fast-fail emits the `circuit_open` frame from a void-ed async IIFE BEFORE the
+ * error terminal is pushed, so a throwing sink took the whole call down (`result()` pending forever plus
+ * an unhandled rejection) instead of costing one status frame. `stream-engine.ts` already wrapped its own
+ * call site for this exact reason and states the contract ("an advisory frame must never break a settled
+ * call"); the guard belongs HERE so every call site inherits it rather than each remembering.
+ */
 export declare function emitBrainStatus(status: BrainStatus): void;
+/**
+ * Silent-fallback telemetry (service [398] C1/C4/C5/C6) — the brain→runner TELEMETRY channel, a
+ * SECOND ALS sink parallel to the status one. Statuses are user-facing liveness frames (wire
+ * `status` events); telemetry is operator-facing fallback accounting the Runner bridges to trace
+ * events (`brain.failover` / `breaker.transition` / `brain.retry` / `vision.placeholder`). Kept
+ * separate so widening telemetry never bloats the shell-visible status vocabulary. Same contract:
+ * fire-and-forget, no-op outside a {@link runWithBrainTelemetry} scope, MUST NOT throw.
+ */
 export type BrainTelemetry = {
     kind: "failover";
     servedIndex: number;
@@ -18,9 +41,15 @@ export type BrainTelemetry = {
 } | {
     kind: "vision_placeholder";
     count: number;
-} | {
+}
+/** PDF read: a `document` content block was substituted with a text placeholder because the serving
+ *  API/model cannot take native document input (openai brain always; anthropic brain when the model
+ *  declares no vision). Silent quality loss → frame (same [398] C4 discipline as vision_placeholder). */
+ | {
     kind: "document_placeholder";
     count: number;
 };
+/** Run `fn` with a per-task brain-telemetry sink in scope (Runner-side; compose with runWithStatusSink). */
 export declare function runWithBrainTelemetry<T>(emit: (t: BrainTelemetry) => void, fn: () => Promise<T>): Promise<T>;
+/** Report a brain-layer fallback/telemetry event to the active per-task sink, if any. */
 export declare function emitBrainTelemetry(t: BrainTelemetry): void;

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

@@ -1,47 +1,194 @@
 import { type AssistantMessage, type Model, createAssistantMessageEventStream } from "../internal/llm.js";
 import { type BrainTimeoutConfig } from "./timeout.js";
+/**
+ * Shared streaming engine for the OpenAI- and Anthropic-shaped brains (design/32, consolidation).
+ *
+ * It owns the **bug-prone machinery that was duplicated verbatim** across `openai.ts` and
+ * `anthropic.ts` — the connect-timeout + retry loop, the three-tier timer logic (first-token + idle
+ * watchdog) with their flag resets, the SSE read loop + line framing, the one-shot cleanup, and the
+ * `.catch/.finally` error wrapping. Centralizing the timer logic is the point: the same first-token /
+ * idle reset bug was fixed twice (1.38.2 / 1.40.2) precisely because this lived in two copies.
+ *
+ * Each provider keeps its OWN request-shaping (`buildRequest`) and SSE parsing + finalization
+ * (`makeParser`) — those genuinely differ (chat-completions deltas vs typed content-block events,
+ * thinking signatures, per-provider usage/finish-reason) and stay verbatim in the adapters, so this
+ * refactor is behavior-preserving (safety net: resilience/streaming/brain tests).
+ */
 export interface StreamEngineConfig extends BrainTimeoutConfig {
+    /**
+     * Retries for transient failures (network / 5xx / 429) BEFORE the body streams, and for the
+     * mid-stream tier-C re-send that shares this budget. Absent ⇒ {@link resolveMaxRetries} (the
+     * `SEMA_MAX_RETRIES` env, else 10). An explicit value here is authoritative and NOT clamped —
+     * deployment sovereignty, same posture as the timeout fields. Sovereignty covers a chosen NUMBER: a
+     * non-finite value (CLS-A-8) falls back to the env/default instead of disabling the budget.
+     */
     maxRetries?: number;
+    /** First-retry backoff ms; each further attempt doubles it (capped, +≤25% jitter). Default 500. */
     retryDelayMs?: number;
 }
+/**
+ * Resolve the transient-failure retry budget — explicit config > `SEMA_MAX_RETRIES` env > default 10
+ * (the same three-level shape as the shell's timeout caps). A non-numeric, negative, or empty env
+ * value is ignored rather than silently meaning "zero retries"; an oversized one is clamped.
+ */
 export declare function resolveMaxRetries(configured: number | undefined): number;
+/**
+ * Is `rebuilt` still THE SAME REQUEST as `original`, differing only in the output cap and the values
+ * that follow from it (ruled 2026-08-05)?
+ *
+ * `buildRequest` re-reads the adapter's model, config, options and context, so a re-shaped re-send is
+ * only trustworthy to the extent that those did not move underneath it. Rather than deep-copying all
+ * of them, the two built requests are compared directly: same destination, same headers, and a body
+ * identical outside {@link SSERequest.capDerivedPaths}. That covers a changed model id, prompt, tool
+ * set, temperature, reasoning posture, or passthrough parameter with one rule instead of a list of
+ * things to remember.
+ *
+ * Conservative on anything it cannot read: a body that is not a JSON object compares by exact string,
+ * so an unparseable pair declines rather than being waved through.
+ */
 export declare function sameRequestModuloCap(original: SSERequest, rebuilt: SSERequest, imposedCap: number): boolean;
+/**
+ * CC parity (`Q1b`, ruled 2026-08-05) — read the provider's EXPLICIT retry verdict off the response.
+ *
+ * The status code is an inference about whether a re-send can help; this header is the provider
+ * SAYING so, and it outranks the inference in BOTH directions:
+ *   - `x-should-retry: true`  — retry even a status the predicate calls terminal (the upstream knows
+ *     the condition is transient, e.g. a fenced-off shard behind a 4xx).
+ *   - `x-should-retry: false` — do NOT retry even a 5xx/429/408/409. Without this, a provider that
+ *     has already decided the request is unservable is re-sent the same request up to the whole
+ *     budget (10 by default), which costs the caller and the upstream alike for a known-refused call.
+ *
+ * Returns `undefined` for an absent header AND for any value other than the two exact tokens — "no
+ * opinion", so the status-code predicate decides and the pre-existing behavior is byte-identical.
+ * Exact-match (no case folding / trimming) is deliberate: it mirrors CC's comparison, and `Headers`
+ * already normalizes surrounding whitespace, so anything else reaching here is a value we did not
+ * define and must not guess at.
+ *
+ * Tolerates a `doFetch` (BYOM injection point) whose Response-shaped return has no usable `headers`.
+ */
 export declare function shouldRetryHeaderVerdict(res: Response | undefined): boolean | undefined;
 export interface SSERequest {
     url: string;
     headers: Record<string, string>;
     body: string;
+    /**
+     * The per-request output cap this request ACTUALLY carries on the wire, when the adapter sets one
+     * (the adapters disagree on the body key, so the engine cannot read it off `body`). Absent means
+     * "no cap sent" or "this adapter does not report it".
+     *
+     * The context-overflow recovery needs it because the number the PROVIDER echoes back in its error
+     * is not evidence of what was sent: a stale or malformed 400 reporting a larger cap than the
+     * request carried would otherwise let the recovery "lower" the cap to a value ABOVE the caller's
+     * own explicit bound. It doubles as the check that an adapter honored an imposed cap at all.
+     */
     outputCapTokens?: number;
+    /**
+     * The body PATHS this adapter may legitimately re-derive when the engine imposes a different output
+     * cap — the cap's own key(s), plus anything computed from it. Dotted for nested leaves
+     * (`"thinking.budget_tokens"`), deliberately: naming the whole `thinking` object would excuse a
+     * change of reasoning MODE as if it followed from the cap, when only the budget does.
+     *
+     * The engine uses this to check that a re-shaped re-send is still THE SAME REQUEST. `buildRequest`
+     * re-reads the adapter's model/config/options/context, so a deployment that changes any of them
+     * while a call is in flight could otherwise turn "lower the cap and try again" into a request with
+     * a different model id, prompt, tool set, or reasoning posture. Everything outside these paths must
+     * come back identical; an adapter that declares nothing therefore permits no body change at all.
+     */
     capDerivedPaths?: readonly string[];
+    /**
+     * Called by the engine once, if and only if THIS request becomes the one that is sent.
+     *
+     * `buildRequest` is also called SPECULATIVELY — the context-overflow recovery builds a candidate
+     * and may then decline it. Any bookkeeping the adapter keeps for its own later diagnostics (which
+     * output cap actually went out, which knob supplied it, whether thinking was requested) therefore
+     * belongs here rather than in the build: assigned during a build, a rejected candidate's numbers
+     * would outlive it and be reported against the request that really was sent.
+     */
     onCommitted?: () => void;
 }
+/**
+ * Per-attempt request overrides the ENGINE imposes on a re-send (ruled 2026-08-05). Absent — which is
+ * every ordinary build — the adapter shapes its request exactly as before, byte for byte.
+ *
+ * An adapter MUST honor every field it can express. Ignoring one is not silent: the only producer is
+ * the context-overflow recovery, whose no-progress guard sees the unchanged cap come back in the next
+ * provider error and fails loud with the original failure instead of looping.
+ */
 export interface BuildRequestOverrides {
+    /**
+     * The per-request output cap to send, outranking every caller/model knob for THIS attempt. Set when
+     * the provider reported that `input + max_tokens` exceeds the context limit; whichever body key the
+     * adapter uses for the cap (`max_tokens` / `max_completion_tokens` / `max_output_tokens`) must carry
+     * this value, and any field derived from the cap must be re-derived from it — the point of routing
+     * this through the adapter rather than patching the serialized body.
+     */
     maxOutputTokens?: number;
 }
+/** Controls that the engine passes to the per-stream parser. */
 export interface StreamControls {
     out: ReturnType<typeof createAssistantMessageEventStream>;
+    /** Shared mutable partial-snapshot message; the parser mutates `content` and emits `{ ...partial }`. */
     partial: AssistantMessage;
+    /** Call on every CONTENT delta (text/thinking/tool input) — resets the first-token + idle watchdogs. */
     sawContentToken(): void;
+    /** Cancel the underlying stream (e.g. degenerate-repetition cutoff). The read loop then ends. */
     cancel(): void;
 }
 export interface StreamParser {
+    /** Handle one raw SSE line (`data: {...}`); parse, emit events, call `ctrl.sawContentToken()` on content. */
     onLine(line: string): void;
+    /** Build + emit the final `done`/`error` message after the stream ends. */
     finalize(): void;
+    /**
+     * design/124 §0.5-2: introspection for the mid-stream failure tiering. Read directly off the
+     * parser's accumulated state (cheap, no side effects):
+     * - `hasSubstantiveText`  — non-blank answer text (or a streamed refusal) has been emitted → tier A
+     *   (partial finalize) territory.
+     * - `hasCompletedToolCall` — at least one tool call CLOSED successfully (a `toolcall_end` was
+     *   emitted, so an in-stream executor may already be running it) → tier A; also the retry-safety
+     *   assertion (§0.5-4): a re-send is FORBIDDEN once this is true (double execution).
+     * - `hasOnlyThinking` — thinking streamed but nothing substantive (no non-blank text, no completed
+     *   tool call) → tier B (seal + whole-turn retry). A dangling tool-call accumulation alongside the
+     *   thinking does not veto this (nothing was admitted; the retry's snapshot replacement drops it).
+     */
     snapshot(): {
         hasSubstantiveText: boolean;
         hasCompletedToolCall: boolean;
         hasOnlyThinking: boolean;
     };
+    /**
+     * design/124 §0.5-2 tier B: seal the UI stream before a whole-turn retry — emit `thinking_end` for
+     * any OPEN thinking block (the block state is parser-private; the engine cannot emit a correct
+     * close). The retry attempt's parser may then legally REOPEN a thinking block at the SAME
+     * contentIndex — consumers render by partial snapshot (replacement semantics), so index reuse is
+     * part of the event contract (see AssistantMessageEvent thinking_start note). Idempotent.
+     */
     sealForRetry(): void;
 }
+/**
+ * Run one streaming request end-to-end and drive the provider `parser`. Returns a fresh event stream;
+ * never throws (errors are pushed as `error` events, mirroring the Brain contract).
+ */
 export declare function runStreamingBrain(args: {
     model: Model;
     doFetch: typeof fetch;
     signal?: AbortSignal;
     config: StreamEngineConfig;
+    /** HTTP error message prefix (e.g. "gateway" / "anthropic"). */
     httpLabel: string;
+    /** Build the one request. May throw (→ surfaced as an error event). Called again with
+     *  {@link BuildRequestOverrides} when the engine re-shapes a re-send (context-overflow recovery). */
     buildRequest: (overrides?: BuildRequestOverrides) => SSERequest;
+    /** Create the per-stream parser once the partial + controls exist. */
     makeParser: (ctrl: StreamControls) => StreamParser;
+    /**
+     * 1.296 件A — per-call ADVISORY stall watchdogs (`StreamOptions.stallTimeouts`). Priority chain:
+     * brain construction-time config (`BrainTimeoutConfig.connectTimeoutMs`/`firstTokenTimeoutMs`/
+     * `idleTimeoutMs`) wins whenever PRESENT — including an explicit 0/negative, which means
+     * "deliberately disabled" — and only an ABSENT (undefined) field adopts the advisory value; both
+     * absent ⇒ off. `connectMs` bounds the fetch→response-headers wait: the engine's post-headers
+     * timers can't see a gateway that never returns headers.
+     */
     stallTimeouts?: {
         connectMs?: number;
         firstTokenMs?: number;