@sema-agent/core 5.20.0 → 5.21.0

package/dist/brain/anthropic.d.ts

@@ -1,15 +1,45 @@
 import type { Brain } from "../core/types.js";
 import { type StreamEngineConfig } from "./stream-engine.js";
 export interface AnthropicBrainConfig extends StreamEngineConfig {
+    /** Base URL of the Anthropic(-compatible) API. Default `https://api.anthropic.com`. Overridden by model.baseUrl. */
     baseUrl?: string;
+    /** API key (`x-api-key`). Overridden by per-call options.apiKey / getApiKeyAndHeaders. */
     apiKey?: string;
+    /** `anthropic-version` header. Default `2023-06-01`. */
     version?: string;
+    /** Extra headers merged into every request (e.g. `anthropic-beta`). */
     headers?: Record<string, string>;
+    /** Custom fetch (tests / proxies). Defaults to global fetch. */
     fetchImpl?: typeof fetch;
+    /** `max_tokens` when the call/model doesn't specify one (Anthropic requires it). Default 4096. */
     defaultMaxTokens?: number;
+    /**
+     * Insert `cache_control: {type:"ephemeral"}` prompt-cache breakpoints on the last system block and
+     * the last tool, so the (stable) system + tools prefix is cached across requests. Default true.
+     */
     cacheBreakpoints?: boolean;
+    /**
+     * Detect **degenerate repetition** (the model looping on the same char/phrase forever) mid-stream
+     * and cut it off — the turn ends `error` ("degenerate repetition"). Default true.
+     */
     detectRepetition?: boolean;
+    /**
+     * Extended-thinking budget as a fraction of `max_tokens` when reasoning is on. Default 0.5.
+     * The budget is always clamped to `[1024, max_tokens - 1]` (Anthropic requires it strictly below
+     * `max_tokens`, ≥ 1024). Lower it to leave more room for the answer with verbose reasoning models.
+     */
     thinkingBudgetShare?: number;
+    /**
+     * Fixed extended-thinking budget in tokens (overrides `thinkingBudgetShare`). Still clamped to
+     * `[1024, max_tokens - 1]`. Use when you want a constant reasoning budget regardless of max_tokens.
+     */
     thinkingBudgetTokens?: number;
 }
+/**
+ * Create a Brain for the Anthropic Messages API (`/v1/messages`) with **prompt caching** and
+ * **extended-thinking replay**. Translates the unified Context into an Anthropic request and the
+ * streamed response back into the unified AssistantMessageEvent protocol. The connect/retry/timeout/
+ * read-loop machinery lives in the shared {@link runStreamingBrain} engine (design/32); this adapter
+ * owns the Anthropic request shaping + typed content-block SSE parsing + finalization.
+ */
 export declare function createAnthropicBrain(config?: AnthropicBrainConfig): Brain;

package/dist/brain/circuit-breaker.d.ts

@@ -1,26 +1,59 @@
 import type { Model } from "../internal/llm.js";
 import type { Brain } from "../core/types.js";
 import { type BrainErrorCode } from "./errors.js";
+/** Stable prefix of an open-breaker error's detail (`[network] circuit open for <key>`). Exported so
+ *  the degradation cascade can detect breaker-open **structurally** instead of string-matching a literal
+ *  (council #1) — reword the message only by changing this constant. */
 export declare const CIRCUIT_OPEN_MARKER = "circuit open for ";
 export type BreakerPhase = "closed" | "open" | "half-open";
 export interface BreakerSnapshot {
     phase: BreakerPhase;
+    /** Consecutive failures while closed. */
     failures: number;
+    /** When the breaker opened (epoch ms), for cooldown. */
     openedAt?: number;
+    /** Probes currently allowed through while half-open. */
     halfOpenInFlight?: number;
+    /**
+     * When the current half-open probe round was admitted (epoch ms) — the PROBE LEASE stamp.
+     *
+     * HRD-BRN-1: `record()` is the only writer that leaves half-open, and it only runs once the probe's
+     * stream settles. A probe that never settles — precisely the accepted-then-hangs gateway the breaker
+     * exists for, and the default shape since `firstTokenTimeoutMs`/`idleTimeoutMs` both default off —
+     * therefore held `halfOpenInFlight` forever and made half-open an ABSORBING state: no clock could
+     * release the key again. The lease bounds it: once `cooldownMs` has elapsed since this stamp, the
+     * in-flight probe is presumed lost and a fresh probe is admitted (see `tryPass`).
+     *
+     * Optional/additive: a snapshot deserialized by a shared backend that predates the field simply
+     * adopts a stamp on the first refusal, so the lease starts from then rather than never.
+     */
     halfOpenAt?: number;
 }
+/** Pluggable breaker state. In-memory by default; a deployment can back it with Redis/TiDB so all
+ *  replicas share one circuit (otherwise each replica trips independently and reacts slowly).
+ *
+ *  ATOMICITY: the breaker does read-modify-write (`get` → decide → `set`). The in-process Map is safe
+ *  under Node's single-threaded run-to-completion. A shared async backend MUST make get/set
+ *  **linearizable** (or expose CAS) — otherwise concurrent transitions (closed→open, open→half-open)
+ *  race (TOCTOU). Implement it with a Lua script / transaction / optimistic-version on the store. */
 export interface BreakerState {
     get(key: string): BreakerSnapshot | undefined;
     set(key: string, snap: BreakerSnapshot): void;
 }
 export interface CircuitBreakerOptions {
+    /** Consecutive transient failures that trip the breaker. Default 5. */
     failureThreshold?: number;
+    /** How long the breaker stays open before a half-open probe. Default 30_000 ms. */
     cooldownMs?: number;
+    /** Probes allowed through while half-open. Default 1. */
     halfOpenProbes?: number;
+    /** Error codes that count toward tripping. Default `["network","server","rate_limit"]`. */
     countCodes?: BrainErrorCode[];
+    /** Breaker key from a model. Default `"<provider>:<id>"` (per model+provider). */
     key?: (model: Model) => string;
+    /** State backend. Default in-memory (per process). */
     state?: BreakerState;
+    /** Clock, injectable for tests. */
     now?: () => number;
 }
 export declare function createCircuitBreakerBrain(inner: Brain, opts?: CircuitBreakerOptions): Brain;

package/dist/brain/context-overflow.d.ts

@@ -1,20 +1,77 @@
+/**
+ * Adaptive `max_tokens` recovery for the ONE provider 400 that is self-healing (CC parity `Fjp` /
+ * `Ijp`, ruled 2026-08-05).
+ *
+ * The failure: the input fits the model's context window, but `input + max_tokens` does not. Nothing
+ * downstream rescues it — the compaction layer's own detectors match "prompt is too long", a
+ * DIFFERENT message meaning the input ALONE overflows, so this 400 is classified `invalid_request`,
+ * is not retried, and terminates the task even though lowering this one request's output cap would
+ * have served it. The provider states every number needed to compute the fix in the error text.
+ *
+ * The recovery is deliberately NARROW: only a 400 whose body carries this exact sentence can trigger
+ * it, and anything the parser cannot read as three integers leaves the original failure untouched.
+ * Two fail-loud guards then bound it — a floor below which lowering the cap stops being useful, and
+ * a no-progress guard so a provider that keeps reporting the same numbers cannot loop the engine.
+ */
+/** CC parity (`Ijp`): the smallest output cap worth retrying with. Below this the answer room is so
+ *  small that a re-send is not a recovery, so the original 400 is surfaced instead. */
 export declare const FLOOR_OUTPUT_TOKENS = 3000;
+/** The three numbers the provider reported. */
 export interface ContextOverflowReport {
+    /** Tokens the provider measured in the request input. */
     inputTokens: number;
+    /** The output cap this request carried. */
     maxTokens: number;
+    /** The model's total context limit, as the provider counts it. */
     contextLimit: number;
 }
+/**
+ * Read the three numbers out of a provider 400 body, or `undefined` for every other failure —
+ * including a 400 of any other shape, a body whose provenance is unestablished, a truncated body, and
+ * numbers too large to be exact integers. A caller that gets `undefined` must surface the original
+ * failure unchanged.
+ */
 export declare function parseContextOverflow(status: number, body: string): ContextOverflowReport | undefined;
-export type OutputCapAdjustment = {
+/**
+ * What to do about a parsed overflow. `adjust` is the only outcome that re-sends; the other two are
+ * refusals that the caller must report ALONGSIDE the original provider failure, so an operator sees
+ * that a recovery was attempted and why it was declined rather than a bare 400.
+ */
+export type OutputCapAdjustment = 
+/** `current` is the cap this adjustment lowers FROM — the smallest one known to be in effect, which
+ *  is what a disclosure must name (the provider's echoed number may not be what was sent). */
+{
     outcome: "adjust";
     maxOutputTokens: number;
     current: number;
-} | {
+}
+/** The room left under the context limit is below {@link FLOOR_OUTPUT_TOKENS} — the input itself is
+ *  the problem, and no output cap makes this request servable. */
+ | {
     outcome: "below_floor";
     available: number;
-} | {
+}
+/** The recomputed cap is not STRICTLY below the cap already in effect — the previous adjustment
+ *  did not take effect, or the provider re-reported the same numbers, or the numbers would RAISE
+ *  the cap. Re-sending cannot help, and in the raising case would be actively worse. */
+ | {
     outcome: "no_progress";
     available: number;
     current: number;
 };
+/**
+ * Compute the lowered output cap for a re-send, or the reason not to.
+ *
+ * `otherCapsInEffect` are the caps the CALLER knows about beyond the one the provider echoed —
+ * typically the cap this engine already imposed on an earlier attempt, and the cap the request
+ * actually carried on the wire. The SMALLEST of all of them bounds the adjustment, and a new cap
+ * must be strictly below it. That single rule does three jobs:
+ *   - it terminates the loop (every accepted adjustment lowers the cap, and the floor bounds it);
+ *   - it makes an adapter that ignored an imposed cap fail loud after one round instead of looping;
+ *   - it keeps the recovery from ever RAISING a cap on the strength of a number the provider
+ *     reported but the request never carried.
+ *
+ * `report.maxTokens` is always one of the caps considered — the provider says the failing request
+ * carried it, and a value it did not carry can only be smaller in the direction that matters.
+ */
 export declare function planOutputCapAdjustment(report: ContextOverflowReport, otherCapsInEffect?: readonly (number | undefined)[]): OutputCapAdjustment;

package/dist/brain/degrading.d.ts

@@ -1,26 +1,93 @@
+/**
+ * Error/budget-aware **degradation cascade** (1.39, design/21, design/17 §5C).
+ *
+ * Unlike failover (a *peer* backup whose goal is "same quality, a gateway that's actually up"),
+ * degradation **deliberately downgrades** to a cheaper / different-provider model to KEEP SERVING when
+ * the primary is rate-limited or its circuit breaker is open — accepting some quality loss instead of
+ * failing the task. Opt-in; the served turn is tagged so the Runner can surface `TaskResult.degraded`.
+ *
+ * This file handles the four **reactive** triggers visible at the brain layer — `rate_limit`,
+ * `breaker_open`, `server_error` and `last_resort` (design/126; all four are the default gate, narrow it
+ * with `downgradeOn`). The proactive **near-budget** trigger needs the task budget (only the Runner sees
+ * it) and is not implemented here; `"budget"` is reserved in `DegradeReason` for it.
+ *
+ * Detection is **structural**, not literal string-matching: the breaker-open signal is
+ * `CIRCUIT_OPEN_MARKER` (exported from circuit-breaker.ts) and the code comes from the shared
+ * `extractErrorCode`. Degradation must be the **outermost** brain in a stack (so it sees the inner
+ * failover/breaker/timeout outcomes and can downgrade on them), and the downgrade target is the ordered
+ * `fallbacks` chain (RB-482 #3 — the single `fallback`+`fallbackModel` pair is retired):
+ *   `createDegradingBrain({ primary: failover(breaker(timeout(brain))), fallbacks: [{ brain, model }] })`.
+ */
 import { type AssistantMessageDiagnostic, type Model } from "../internal/llm.js";
 import type { Brain } from "../core/types.js";
+/** Diagnostic `type` the decorator stamps on a degraded turn's message; the Runner reads it back. */
 export declare const DEGRADED_DIAGNOSTIC_TYPE = "degraded";
+/** Why a turn was degraded. `"budget"` is reserved for the v2 near-budget trigger (Runner-level).
+ *  design/126 (CC 批 β) widens the reactive set: `"server_error"` = a `server`-class failure (5xx incl.
+ *  529 overloaded, 408/409) that ESCAPED the inner brain's own retry budget (CC parity: retry in place
+ *  first, then fall back — CC :600552); `"last_resort"` = an `http`-class status error (404
+ *  model-not-found and other non-retryable statuses — CC :600513/:600588 folds both into "try the next
+ *  model instead of dying"). Deliberate deviations from CC, documented in design/126 D2: `rate_limit`
+ *  stays a trigger (CC waits in place; an unattended headless task waiting forever is a dead task), and
+ *  `auth` (401/403) NEVER triggers (CC falls back on 403; silently swapping models over a
+ *  permission/key misconfiguration is worse than failing loud for headless). */
 export type DegradeReason = "breaker_open" | "rate_limit" | "budget" | "server_error" | "last_resort";
 export interface DegradationInfo {
+    /** The model id that was meant to serve (the primary). */
     from: string;
+    /** The cheaper model id that actually served (or the LAST model attempted when the chain failed too). */
     to: string;
+    /** The FIRST trigger that started the downgrade walk (later hops may fail for other reasons). */
     reason: DegradeReason;
+    /** design/126: the model ids attempted after the primary, in order (length 1 = the classic single
+     *  hop). Optional — absent on markers written by pre-chain versions. */
     chain?: string[];
 }
 interface DegradingBrainBaseOptions {
+    /** The preferred brain (typically `failover(breaker(timeout(openai)))`). */
     primary: Brain;
+    /**
+     * Which reactive triggers cause a downgrade. Default = all four reactive classes
+     * (`rate_limit`/`breaker_open`/`server_error`/`last_resort`). Pass it explicitly to narrow.
+     */
     downgradeOn?: DegradeReason[];
 }
+/** RB-482 #3 (ruled 2026-08-03): ONE form — the ordered `fallbacks` chain. The legacy single
+ *  `fallback`+`fallbackModel` pair is retired (a chain-of-one is `fallbacks: [{brain, model}]`), and
+ *  its pre-126 two-trigger default retires with it: every construction gets the full four-class gate
+ *  unless `downgradeOn` narrows it explicitly. */
 export type DegradingBrainOptions = DegradingBrainBaseOptions & {
+    /**
+     * design/126 (CC 批 β) — the ORDERED downgrade chain (up to 3 entries, CC `Kjd` parity; excess is
+     * truncated, duplicate model ids deduped, and an entry whose model id equals the model that just
+     * failed is skipped at walk time). Each hop carries its OWN brain — carry its credentials in its
+     * config (e.g. `createOpenAIBrain({ apiKey, baseUrl })`): the decorator clears the primary's
+     * per-call `apiKey`/`headers`/`metadata` for every hop so a hop never leaks the primary's identity
+     * to a different provider.
+     */
     fallbacks: Array<{
         brain: Brain;
         model: Model;
     }>;
 };
+/** Pull a degradation marker off a served message (used by the Runner to fill `TaskResult.degraded`). */
 export declare function readDegradation(msg: {
     diagnostics?: AssistantMessageDiagnostic[];
 } | undefined): DegradationInfo | undefined;
+/**
+ * design/131 (codex 131 审 A) — resilience-standdown pass-through: forward one brain's stream
+ * verbatim, but keep the decorator discipline that a REJECTING inner brain (throw instead of an
+ * error event) still leaves a terminal on the returned stream — otherwise `result()` never
+ * resolves and the harness hangs (the same class as the degradation-brain blocker).
+ *
+ * HRD-BRN-5: that discipline covered only the REJECT shape. An inner stream ENDED BARE (`end()` with no
+ * terminal event) drained the `for await` loop and then pushed nothing, so `result()` stayed pending
+ * forever — the exact hang class this function's contract claims to prevent, and reached through the
+ * two standdown knobs (`resilience.allowFailover:false` / `allowDegrade:false`) that a benchmark or eval
+ * harness turns on to see a provider's TRUE failure shape. Standing resilience down was therefore
+ * strictly MORE hang-prone than leaving it on, since the normal failover path awaits `inner.result()`
+ * and lands in its catch. Both shapes now leave exactly one terminal.
+ */
 export declare function passthroughStream(brain: Brain, model: Model, context: Parameters<Brain["stream"]>[1], options: Parameters<Brain["stream"]>[2]): ReturnType<Brain["stream"]>;
 export declare function createDegradingBrain(opts: DegradingBrainOptions): Brain;
 export {};

package/dist/brain/errors.d.ts

@@ -1,16 +1,58 @@
+/**
+ * Structured brain error so the *kind* of failure is machine-distinguishable end-to-end (the message
+ * is prefixed `[code]`, which the Runner lifts into `TaskResult.errorCode`). This lets an external
+ * caller react correctly without string-matching: `auth` → the API key is wrong, **stop and fix it**
+ * (it's not retried, so the caller gets a fast failure); `rate_limit` → back off; `network`/`server`
+ * → a transient outage worth retrying. Only `network`/`server`/`rate_limit` are retried by the brains.
+ */
 import type { Usage } from "../internal/llm.js";
+/** A zeroed `Usage` for synthetic error/short-circuit assistant messages (no tokens spent). Shared by
+ *  the circuit-breaker, degradation, and routing brains so the empty-usage shape lives in one place. */
 export declare const ZERO_USAGE: Usage;
+/** The single source of truth for brain error codes — the type, the `[code]` parser, and the prefix
+ *  stripper all derive from this one list, so adding a code can't silently diverge across call sites.
+ *
+ *  The last three are IN-BAND terminal-output codes ([1086]③): stamped on errored assistant MESSAGES
+ *  (never thrown as BrainError) so `TaskResult.errorCode` covers the error family end-to-end and
+ *  downstream consumers can bucket without string-matching. Deliberately behavior-neutral everywhere
+ *  else: the circuit breaker's default countCodes excludes them (model-output problems, not provider
+ *  outages), degradation maps them to nothing, and subagent retry classification keeps them in the
+ *  non-retryable "logic" bucket — exactly how these previously-uncoded messages already behaved.
+ *    - `stream_torn`  — the stream ended with no content and no finish/stop reason (response lost)
+ *    - `refusal`      — policy refusal / provider content filter withheld the output
+ *    - `length_empty` — max_tokens exhausted with no answer text (pairs with errorKind "length_empty") */
 declare const BRAIN_ERROR_CODES: readonly ["auth", "rate_limit", "invalid_request", "server", "network", "http", "stream_torn", "refusal", "length_empty"];
 export type BrainErrorCode = (typeof BRAIN_ERROR_CODES)[number];
+/** The full code list as a value, exported for exhaustive drift guards (e.g. the `errorClassOf` copy in
+ *  tool-errors.ts must classify every member — a code added here but missed there folds to "unknown"). */
 export declare const ALL_BRAIN_ERROR_CODES: readonly BrainErrorCode[];
+/** The in-band terminal-output subset (see the list doc above). The circuit breaker collapses these
+ *  to the legacy `"http"` bucket before counting (codex [1086]③ 审): its taxonomy is TRANSPORT-level,
+ *  and before these codes existed the same failures reached it as the unprefixed→"http" fallback — a
+ *  custom `countCodes: ["http"]` policy must keep counting them exactly as it always did. */
 export declare const IN_BAND_OUTPUT_CODES: ReadonlySet<BrainErrorCode>;
 export declare class BrainError extends Error {
     readonly code: BrainErrorCode;
     readonly status?: number;
     constructor(code: BrainErrorCode, detail: string, status?: number);
 }
+/** Map an HTTP status to an error class. 401/403 = auth (don't retry); 429 = rate limit; 5xx = server. */
 export declare function classifyHttp(status: number): BrainErrorCode;
+/** Lift the machine-readable code back out of a `[code] …` prefixed `errorMessage` (the single shared
+ *  parser — circuit breaker, degradation, and the Runner all read the prefix this way, council #7). */
 export declare function extractErrorCode(errorMessage: string | undefined): BrainErrorCode | undefined;
+/** Strip a leading `[code] ` prefix (including the trailing space) from an `errorMessage`, leaving the
+ *  human text. Pairs with {@link extractErrorCode} so a caller can lift the code and clean the message
+ *  without re-hardcoding the code list (the Runner does both when assembling `TaskResult`). */
 export declare function stripErrorCodePrefix(errorMessage: string): string;
+/** RB-386③ ([2090]) — render a transport-level error WITHOUT folding away its cause chain. undici's
+ *  `fetch` rejects with `TypeError("fetch failed", { cause })` where the CAUSE carries the actually
+ *  actionable fact (`connect ECONNREFUSED …` / `getaddrinfo ENOTFOUND …` / `SocketError: other side
+ *  closed` with a `code`); `String(e)` / `e.message` alone collapsed ALL THREE network-failure shapes
+ *  (refused / DNS / mid-stream disconnect) into the same opaque "fetch failed", end to end (BrainError
+ *  detail → TaskResult.errorMessage → bg-agent terminal notification / poll error). Walks the cause
+ *  chain (bounded), appending each layer's `code:`-prefixed message; layers whose message the parent
+ *  already contains are skipped (no duplicate noise). Falls back to the plain message for causeless
+ *  errors — those call sites' output is byte-identical to before. */
 export declare function describeNetworkError(e: unknown): string;
 export {};

package/dist/brain/failover.d.ts

@@ -1,2 +1,17 @@
 import type { Brain } from "../core/types.js";
+/**
+ * Compose several brains into one with ordered failover (primary → fallbacks).
+ *
+ * The happy path streams live from the first brain. A brain is only failed over to the next when it
+ * fails **before emitting any content** (e.g. the gateway is down / connection refused, OR a
+ * first-token timeout that fires after the stream opened but before any delta) — a clean upfront
+ * failure. The leading `start` event is **held back** until the first real content event, so an
+ * error between `start` and the first delta can still fail over without ever having forwarded a
+ * (then-duplicated) `start`. Once real content (text/thinking/tool) has streamed, the outcome
+ * (including a mid-stream error or abort) is propagated rather than restarted, so the consumer never
+ * sees duplicate `start`/text events. The last brain's result is always final.
+ *
+ * Each underlying brain keeps its own retry policy (e.g. `createOpenAIBrain({ maxRetries })`);
+ * failover is the cross-gateway layer on top.
+ */
 export declare function createFailoverBrain(brains: Brain[]): Brain;

package/dist/brain/media-degrade.d.ts

@@ -1,13 +1,52 @@
+/**
+ * Media degradation shared by the two message assemblers (anthropic.ts / openai.ts).
+ *
+ * Both lanes have to answer the same two questions on every request — "may this model see images?"
+ * and "what do I say when a media block cannot ride along?" — and both used to answer them with
+ * their own copy of the predicate and their own copy of the sentence. One construction point:
+ * a capability rule that drifts between lanes is a silent per-provider behavior difference, and a
+ * placeholder sentence that drifts is a string consumers grep for.
+ */
 import type { Model } from "../internal/llm.js";
+/**
+ * Whether the SERVING model accepts image input (`Model.input` contains "image").
+ *
+ * An ABSENT `input` is deliberately permissive (vision on): the field is caller-supplied metadata,
+ * and treating "not declared" as "not capable" would silently downgrade every caller who never
+ * filled it in. A caller that genuinely serves a text-only endpoint declares `input: ["text"]` and
+ * gets the placeholder path — the case a text-only API rejects with a hard 400 on an image part.
+ */
 export declare function modelSupportsVision(model?: Model): boolean;
+/** Placeholder for an image block dropped because the serving model declares no image input. */
 export declare const IMAGE_OMITTED_NO_VISION = "[image omitted: the serving model does not support image input]";
+/** {@link IMAGE_OMITTED_NO_VISION}, counted — a batch of dropped images states how many were lost. */
 export declare function imagesOmittedNoVisionNote(count: number): string;
+/** An image content block carrying both wire fields — the only shape any lane can actually send. */
 export interface SendableImage {
     type: "image";
     data: string;
     mimeType: string;
 }
+/**
+ * The blocks that would ride as REAL image media: `type:"image"` with both wire fields present.
+ *
+ * One predicate for both lanes and for both of its uses — deciding what to SEND and counting what was
+ * DROPPED. A block missing `data`/`mimeType` is discarded by every assembler on every path, error or
+ * not, so an omission note that counted it would blame the error for a loss it did not cause.
+ */
 export declare function sendableImages(blocks: readonly unknown[]): SendableImage[];
+/**
+ * Disclosure for media blocks stripped out of an ERROR tool result.
+ *
+ * The stripping itself is mandatory on both lanes and is NOT a choice this note softens: the
+ * Anthropic API rejects an image inside an `is_error` tool_result outright (CC messages.ts, image-in-error rejection —
+ * a passthrough attempt 400s the request forever, not once), and the OpenAI-compatible `tool` role
+ * carries text only, with the synthetic image-carrier user message deliberately not built for error
+ * results. What the note fixes is the SILENCE: an error whose attached evidence simply vanished
+ * reads to the model as an error that never had any, so it cannot ask for the evidence another way.
+ *
+ * @returns the note, or `undefined` when there is nothing to disclose (no media was dropped).
+ */
 export declare function errorResultMediaNote(counts: {
     images: number;
     documents: number;

package/dist/brain/model-presets.d.ts

@@ -1,4 +1,35 @@
+/**
+ * First-party model presets (design/119, CC 2.1.198 rebaseline).
+ *
+ * sema stays caller-injects-`Model` by design (no baked catalog — the CC catalog/alias/family layer
+ * is a product surface we deliberately don't carry). What IS worth shipping is the per-model
+ * CAPABILITY facts a caller can't guess from the docs page: the Fable-5-class wire contract
+ * (adaptive thinking form, effort tiers, temperature rejection) that a wrong guess turns into a
+ * hard 400. These presets are DATA, not mechanism — every field can be overridden by the caller.
+ *
+ * Pricing is deliberately NOT baked (CC 198 doesn't bake it either): `cost` defaults to zeros and a
+ * deployment that wants cost accounting fills in the current official per-MTok rates.
+ */
 import type { AnthropicMessagesCompat, Model } from "../internal/llm.js";
+/**
+ * The Fable-5-class Anthropic wire contract (CC 2.1.198 capability bits, design/119 P0):
+ * - `thinkingMode: "adaptive"` — `thinking: { type: "adaptive" }`, NO budget_tokens (400 on budget).
+ * - `effortLevels` — the full five-tier `output_config.effort` range (fable-5 has `xhigh_effort` +
+ *   `max_effort`; a model without those bits should declare a shorter list and higher requests clamp).
+ * - `supportsTemperature: false` — CC never sends temperature to this class, thinking on OR off.
+ */
 export declare const FABLE_5_COMPAT: AnthropicMessagesCompat;
+/**
+ * Fable-5 behavioral guidance (CC 2.1.198 `fable_5_mitigations` — Anthropic's own runtime patches
+ * for this model class's known behavior pitfalls, adapted; design/119 S3). Carried on the Model as
+ * `promptGuidance` DATA — the injection mechanism (`Model.promptGuidance` → system-prompt tail) is
+ * generic and model-name-free.
+ */
 export declare const FABLE_5_PROMPT_GUIDANCE: string[];
+/**
+ * A ready-to-use `claude-fable-5` {@link Model} (CC 2.1.198 registry facts: 1M-token native context
+ * window, 64k default max output — the 128k tier is opt-in via `maxTokens` override, knowledge
+ * cutoff Jan 2026, `default_effort: "high"`). Override anything per deployment; set `cost` for
+ * accounting (not baked — see module note).
+ */
 export declare function fable5Model(overrides?: Partial<Model>): Model;

package/dist/brain/open-responses.d.ts

@@ -1,11 +1,30 @@
 import type { Brain } from "../core/types.js";
 import { type StreamEngineConfig } from "./stream-engine.js";
 export interface OpenResponsesBrainConfig extends StreamEngineConfig {
+    /** Base URL of the Open Responses endpoint, WITHOUT the trailing `/responses`. Overridden by `model.baseUrl`. */
     baseUrl?: string;
+    /** API key. Overridden by per-call `options.apiKey`. */
     apiKey?: string;
+    /** Extra headers merged into every request (auth + content-type are hard-locked after the merge). */
     headers?: Record<string, string>;
+    /** Inject a custom fetch (tests / proxies). Defaults to global fetch. */
     fetchImpl?: typeof fetch;
+    /**
+     * Replay prior assistant reasoning items back to the endpoint on the turns that carry tool calls
+     * (see the file header — an endpoint in thinking mode REQUIRES it there and ignores it elsewhere).
+     * **On by default.** Set `false` only for an endpoint that rejects the `reasoning` input item;
+     * with it off, a thinking-mode endpoint refuses every replayed tool-call turn.
+     */
     replayReasoning?: boolean;
+    /**
+     * Detect **degenerate repetition** (the model looping on the same char/phrase forever) mid-stream
+     * and cut it off — the turn ends `error` (`errorKind:"degenerate"`) so the loop stops paying.
+     * Default true. Same detector, same cadence, same salvage rules as the other two lanes.
+     */
     detectRepetition?: boolean;
 }
+/**
+ * Create a Brain that talks to an Open Responses endpoint. See the file header for the stateless
+ * invariant, the capability-audit posture, and the reasoning-replay rule.
+ */
 export declare function createOpenResponsesBrain(config?: OpenResponsesBrainConfig): Brain;

package/dist/brain/openai.d.ts

@@ -1,13 +1,59 @@
 import type { Brain } from "../core/types.js";
 import { type StreamEngineConfig } from "./stream-engine.js";
 export interface OpenAIBrainConfig extends StreamEngineConfig {
+    /** Base URL of your OpenAI-compatible gateway (without /chat/completions). Overridden by model.baseUrl if set. */
     baseUrl?: string;
+    /** API key. Overridden by per-call options.apiKey / getApiKeyAndHeaders. */
     apiKey?: string;
+    /** Extra headers merged into every request. */
     headers?: Record<string, string>;
+    /** Inject a custom fetch (tests / proxies). Defaults to global fetch. */
     fetchImpl?: typeof fetch;
+    /**
+     * For weaker models that emit tool calls as TEXT (`<tool_call>{...}</tool_call>` / fenced json)
+     * instead of native tool calls: promote them to real tool calls. Off by default. Native models
+     * don't need this.
+     */
     repairTextToolCalls?: boolean;
+    /**
+     * Replay assistant `reasoning_content` back to the provider on follow-up requests (design/46).
+     * **On by default**, and **conditional**: thinking is replayed only on prior assistant **tool-call**
+     * turns — DeepSeek V4 **requires** it there (else it errors/degrades), while non-tool turns ignore it,
+     * so replaying there only bloats the context window (prefix-cache cuts the *cost* of that bloat but not
+     * the *window occupancy* → earlier compaction). Replaying just the tool-call turns is correctness-
+     * equivalent and leaner. Set `false` to never replay (e.g. a provider that rejects the field).
+     * Anthropic uses `createAnthropicBrain`, which always replays thinking blocks with their signature.
+     */
     replayThinking?: boolean;
+    /**
+     * Detect **degenerate repetition** (the model looping on the same char/phrase forever) mid-stream
+     * and cut it off — the turn ends `error` ("degenerate repetition") so the loop stops paying and a
+     * team member's looped output is treated as a failed turn, not a real statement. Default true.
+     */
     detectRepetition?: boolean;
 }
+/**
+ * Wire-field inference for the per-reply output cap when the model declares no explicit
+ * `compat.maxTokensField`. Newer stock-OpenAI model families REJECT `max_tokens` with a 400
+ * ("Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens'
+ * instead."): the o-series reasoning models (o1/o3/o4 and their -mini/-pro/dated variants), the gpt-5
+ * family, and chatgpt-4o. Everything else — older OpenAI models AND the long tail of third-party
+ * OpenAI-COMPATIBLE endpoints (vLLM, DeepSeek, llama.cpp, gateways) — keeps `max_tokens`, because many
+ * compat endpoints only recognize that spelling. Heuristic rules (deliberately conservative — an id the
+ * table can't confidently classify keeps the widely-supported `max_tokens`):
+ *   - `gpt-5…`            → max_completion_tokens (gpt-5, gpt-5-mini, gpt-5.x, …)
+ *   - `chatgpt-4o…`       → max_completion_tokens (chatgpt-4o-latest)
+ *   - `o1|o3|o4` (+ `-`/`.` suffix or bare) → max_completion_tokens (o1-preview, o3-mini, o4-mini, …)
+ *   - anything else       → max_tokens (gpt-4o/gpt-4.x accept both; third-party ids often ONLY this)
+ * An explicit `compat.maxTokensField` always wins over this inference. Exported so shells constructing
+ * Models from bare ids (e.g. the TB entry) can bake the same inference into compat metadata.
+ */
 export declare function inferMaxTokensField(modelId: string): "max_completion_tokens" | "max_tokens";
+/**
+ * Create a Brain that talks to an OpenAI-compatible chat-completions endpoint (your model gateway).
+ * Translates the unified Context into an OpenAI request and the streamed response back into the unified
+ * AssistantMessageEvent protocol, including native tool calls. The connect/retry/timeout/read-loop
+ * machinery lives in the shared {@link runStreamingBrain} engine (design/32); this adapter owns the
+ * OpenAI request shaping + chat-completions SSE parsing + finalization.
+ */
 export declare function createOpenAIBrain(config?: OpenAIBrainConfig): Brain;