@sema-agent/core 5.20.0 → 5.21.1

package/dist/engine/llm/types.d.ts

@@ -8,6 +8,12 @@ export type ImagesApi = KnownImagesApi | (string & {});
 export type Provider = string;
 export type KnownImagesProvider = "openrouter";
 export type ImagesProvider = string;
+/**
+ * Effort/intensity TIERS (no "off" — this is the value a provider effort field takes). ⚠ Name clash
+ * by history with the loop-layer `ThinkingLevel` (engine/loop/types.ts), which is the SEVEN-value
+ * on/off+tier knob ("off" | these six). Rule of thumb: harness/task config uses the loop's 7-tier
+ * type; provider compat fields (`reasoningEffortLevels`/`effortLevels`) use this 6-tier one.
+ */
 export type ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export type ModelThinkingLevel = "off" | ThinkingLevel;
 export type ThinkingLevelMap = Partial<Record<ModelThinkingLevel, string | null>>;
@@ -18,52 +24,191 @@ export interface ProviderResponse {
     status: number;
     headers: Record<string, string>;
 }
+/**
+ * design/131 — per-task resilience overrides (intent flags, NOT decorator config). A bench/eval or
+ * critical task can say "fail rather than fall back" without any new global switch; the deployment's
+ * decorator stack stays the single topology owner. All default to today's behavior when absent.
+ */
 export interface ResilienceOptions {
+    /** false = this task forbids reactive model DEGRADE (the degrading brain passes the failure through). */
     allowDegrade?: boolean;
+    /** false = this task forbids cross-gateway FAILOVER (only the primary brain is tried). */
     allowFailover?: boolean;
+    /** true = this task ignores an OPEN circuit breaker's fast-fail (the probe goes through; outcomes
+     *  are STILL recorded so shared observation is undiminished). Operator-facing — an open breaker
+     *  exists to protect the provider; bypass only where true failure shape matters (benchmarks). */
     bypassBreaker?: boolean;
 }
+/** 1.296 件A — per-call advisory stall-watchdog values (see {@link StreamOptions.stallTimeouts}). */
 export interface StallTimeouts {
+    /** Advisory connect watchdog (ms) — bounds the fetch→response-headers wait (件1a: a gateway that
+     *  never returns headers is invisible to every post-headers watchdog, including the absolute
+     *  deadline timer). Fires as the brain's existing retryable `network` connect timeout. */
     connectMs?: number;
+    /** Advisory first-token watchdog (ms) — first thinking delta counts as the first token. */
     firstTokenMs?: number;
+    /** Advisory mid-stream idle watchdog (ms) — re-armed on every delta after the first. */
     idleMs?: number;
 }
 export interface StreamOptions {
     temperature?: number;
     maxTokens?: number;
+    /**
+     * Stop sequences forwarded to providers that support them. Providers map this
+     * to their native request field, such as OpenAI `stop` or Anthropic
+     * `stop_sequences`.
+     */
     stop?: string[];
     signal?: AbortSignal;
     apiKey?: string;
+    /**
+     * Preferred transport for providers that support multiple transports.
+     * Providers that do not support this option ignore it.
+     */
     transport?: Transport;
+    /**
+     * Prompt cache retention preference. Providers map this to their supported values.
+     * Default: "short".
+     */
     cacheRetention?: CacheRetention;
+    /**
+     * Optional session identifier for providers that support session-based caching.
+     * Providers can use this to enable prompt caching, request routing, or other
+     * session-aware features. Ignored by providers that don't support it.
+     */
     sessionId?: string;
+    /**
+     * Optional provider prompt-cache affinity key, distinct from transcript/session identity.
+     * Providers that do not support separate cache affinity ignore it.
+     */
     promptCacheKey?: string;
+    /**
+     * Optional callback for inspecting or replacing provider payloads before sending.
+     * Return undefined to keep the payload unchanged.
+     */
     onPayload?: (payload: unknown, model: Model) => MaybePromise<unknown>;
+    /**
+     * Optional callback invoked after an HTTP response is received and before
+     * its body stream is consumed.
+     */
     onResponse?: (response: ProviderResponse, model: Model) => void | Promise<void>;
+    /**
+     * Optional custom HTTP headers to include in API requests.
+     * Merged with provider defaults; can override default headers.
+     * Not supported by all providers (e.g., AWS Bedrock uses SDK auth).
+     */
     headers?: Record<string, string>;
+    /**
+     * HTTP request timeout in milliseconds for providers/SDKs that support it.
+     * For example, OpenAI and Anthropic SDK clients default to 10 minutes.
+     */
     timeoutMs?: number;
+    /**
+     * service [405] P0 — true when `maxTokens` on THIS call was DYNAMICALLY SHRUNK by the wall-clock
+     * cap (design/130 P1), not statically configured. A provider hitting max_tokens with ONLY
+     * reasoning output should then finish as a RECOVERABLE `length` stop (the loop's truncated-output
+     * continue picks it up; the next call is cap-exempt via the runtime reasoning observation) instead
+     * of the static-config fail-loud error — under a dynamic cap the truncation is the ENGINE's doing,
+     * not a deployment mistake.
+     */
     maxTokensDynamic?: boolean;
+    /**
+     * Blackboard [477] — the STATIC leg of the [405] dynamicCut family. True = the caller (the agent
+     * loop) is prepared to recover a `length` stop, so a provider hitting the STATIC max_tokens with
+     * ONLY reasoning output (a budget-ignoring thinking model — e.g. a Qwen gateway that ignores the
+     * thinking control plane and eats the whole static budget in one thought) may finish as a
+     * RECOVERABLE `length` stop tagged `staticReasoningCut` instead of the fail-loud config error.
+     * The loop grants this only while its per-run stop-loss budget lasts (2 downgrades), then stops
+     * passing it — the third truncation fails loud again (no infinite truncate/continue burn).
+     * Absent/false ⇒ today's behavior: reasoning-only static max_tokens is a fail-loud error (a
+     * genuine misconfiguration must stay loud — e.g. the compaction summarizer relies on the
+     * `length_empty` errorKind to escalate its budget).
+     */
     staticReasoningCutDowngrade?: boolean;
+    /**
+     * design/131 (service [404] 拍) — per-task resilience INTENT flags, threaded per call so the
+     * resilience decorator stack (degrading / failover / circuit-breaker) can stand aside for THIS
+     * task. Intent-only: no decorator topology rides the wire; each layer reads the flag it owns and
+     * defaults to today's behavior when absent. See design/131-per-task-resilience-overrides.md.
+     */
     resilience?: ResilienceOptions;
+    /**
+     * 1.296 件A — per-call ADVISORY stall watchdogs, supplied by the engine on every call so a SILENT
+     * stream cannot hang the run: they bound the first-token wait and mid-stream silence with the
+     * brain's existing retryable `network` stall machinery — TB2.0 run89: 680s of
+     * zero deltas. ADVISORY, not an override: a brain whose construction-time `BrainTimeoutConfig`
+     * sets the corresponding field keeps it — deployment sovereignty, including an explicit
+     * 0/negative meaning "deliberately disabled" — and only an ABSENT (undefined) field adopts the
+     * per-call value. Priority chain: brain explicit config > this per-call advisory > off.
+     * `firstTokenMs` is reasoning-safe: the first THINKING delta already counts as the first token
+     * (see BrainTimeoutConfig.firstTokenTimeoutMs, design/17 O5).
+     */
     stallTimeouts?: StallTimeouts;
+    /**
+     * Maximum retry attempts for providers/SDKs that support client-side retries.
+     * For example, OpenAI and Anthropic SDK clients default to 2.
+     */
     maxRetries?: number;
+    /**
+     * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.
+     * If the server's requested delay exceeds this value, the request fails immediately
+     * with an error containing the requested delay, allowing higher-level retry logic
+     * to handle it with user visibility.
+     * Default: 60000 (60 seconds). Set to 0 to disable the cap.
+     */
     maxRetryDelayMs?: number;
+    /**
+     * Optional metadata to include in API requests.
+     * Providers extract the fields they understand and ignore the rest.
+     * For example, Anthropic uses `user_id` for abuse tracking and rate limiting.
+     */
     metadata?: Record<string, unknown>;
 }
 export type ProviderStreamOptions = StreamOptions & Record<string, unknown>;
 export interface ImagesOptions {
     signal?: AbortSignal;
     apiKey?: string;
+    /**
+     * Optional callback for inspecting or replacing provider payloads before sending.
+     * Return undefined to keep the payload unchanged.
+     */
     onPayload?: (payload: unknown, model: ImagesModel) => MaybePromise<unknown>;
+    /**
+     * Optional callback invoked after an HTTP response is received.
+     */
     onResponse?: (response: ProviderResponse, model: ImagesModel) => void | Promise<void>;
+    /**
+     * Optional custom HTTP headers to include in API requests.
+     * Merged with provider defaults; can override default headers.
+     */
     headers?: Record<string, string>;
+    /**
+     * HTTP request timeout in milliseconds for providers/SDKs that support it.
+     */
     timeoutMs?: number;
+    /**
+     * Maximum retry attempts for providers/SDKs that support client-side retries.
+     */
     maxRetries?: number;
+    /**
+     * Maximum delay in milliseconds to wait for a retry when the server requests a long wait.
+     * If the server's requested delay exceeds this value, the request fails immediately
+     * with an error containing the requested delay, allowing higher-level retry logic
+     * to handle it with user visibility.
+     * Default: 60000 (60 seconds). Set to 0 to disable the cap.
+     */
     maxRetryDelayMs?: number;
+    /**
+     * Optional metadata to include in API requests.
+     * Providers extract the fields they understand and ignore the rest.
+     */
     metadata?: Record<string, unknown>;
 }
 export type ProviderImagesOptions = ImagesOptions & Record<string, unknown>;
 export interface SimpleStreamOptions extends StreamOptions {
+    /** [1076]③a: widened to include the explicit "off" — an off that reaches the wire layer lets the
+     *  brains emit the provider DISABLE key on binary enable formats (default-on Qwen gateways reason
+     *  on absence, so absence ≠ off there). Both brains guard: off never enables thinking. */
     reasoning?: ModelThinkingLevel;
 }
 export type StreamFunction<TApi extends Api = Api, TOptions extends StreamOptions = StreamOptions> = (model: Model<TApi>, context: Context, options?: TOptions) => AssistantMessageEventStreamContract;
@@ -76,6 +221,9 @@ export interface ThinkingContent {
     type: "thinking";
     thinking: string;
     thinkingSignature?: string;
+    /** When true, the thinking content was redacted by safety filters. The opaque
+     *  encrypted payload is stored in `thinkingSignature` so it can be passed back
+     *  to the API for multi-turn continuity. */
     redacted?: boolean;
 }
 export interface ImageContent {
@@ -83,6 +231,11 @@ export interface ImageContent {
     data: string;
     mimeType: string;
 }
+/** A binary document payload (today: PDF only — `application/pdf`). Produced by the Read tool's PDF
+ *  branch (CC FileReadTool parity: the file is sent to the model as a native `document` content block
+ *  so an Anthropic-family model reads the text layer directly). Provider support is uneven: the
+ *  anthropic brain forwards it as `{type:"document",source:{type:"base64",…}}`; the openai brain has
+ *  no equivalent block and substitutes an honest text placeholder (never a silent drop). */
 export interface DocumentContent {
     type: "document";
     data: string;
@@ -110,23 +263,120 @@ export interface Usage {
     };
 }
 export type StopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+/**
+ * design/171 §6.1 — WHO a piece of human input came from, as an attribution label. THE single
+ * definition, at its layering-legal home (the engine cannot import core): the persisted steer
+ * queue (`core/checkpoint-store`) RE-EXPORTS this type, so the live message seat and the parked
+ * entry can never drift apart.
+ *
+ * **Normative:** an actor NEVER participates in any permission / approval / scope decision — authority
+ * belongs to the principal, always. This is display-and-audit provenance, nothing more.
+ *
+ * `hostAsserted` must be derived by the host from INGRESS CREDENTIALS and must never be taken from a
+ * request body (same rule the parked steer queue's `trusted` flag already follows: the service computes
+ * it from a verified principal, the core stores it VERBATIM and never recomputes it). Enforcement lives
+ * at the ingress that mints the assertion; the core's job is to carry it unchanged.
+ */
 export interface ActorAssertion {
+    /** Namespaced stable subject id (`"slack:U123"` / `"sso:alice@example.com"`) — the namespace prevents
+     *  two ingresses from colliding on the same raw id. */
     id: string;
+    /** True iff the HOST derived this identity from ingress credentials. `false` = an unverified
+     *  self-claim, which a renderer must mark as such; never settable from a request body. */
     hostAsserted: boolean;
+    /** Who asserted it (Slack app id, SSO IdP, …) — present when the host can name its ingress. */
     issuer?: string;
 }
+/** design/171 — the ONE canonical copy of an {@link ActorAssertion}: exactly the three contract
+ *  fields, a fresh object. Every seat that RETAINS an assertion (message mint, event build, steer
+ *  acceptance) snapshots through here, so a caller mutating its own object after the call — or
+ *  riding junk extra keys on it — can never rewrite persisted attribution. */
 export declare function snapshotActorAssertion(actor: ActorAssertion): ActorAssertion;
 export interface UserMessage {
     role: "user";
     content: string | (TextContent | ImageContent)[];
     timestamp: number;
+    /**
+     * [c209-C] codex 收口 C1/C2 — EXACT character length of the ENGINE-PREPENDED prefix on this
+     * user-lane message (first-frame listing/`<skills>` reminders + a UserPromptSubmit
+     * additionalContext reminder ahead of the objective; the trusted engine-authored head of a resume
+     * continuation). Derived views that re-present user messages under a `[user]`/`[User]:` label
+     * (auto-mode classifier window, compaction summarizer input) slice EXACTLY this many chars off the
+     * head — metadata, never shape-guessing, so a user who legitimately opens their own prompt with a
+     * `<system-reminder>` block is NEVER mis-stripped. Additive schema field: absent on old sessions
+     * (⇒ rendered verbatim — conservative direction: a classifier seeing engine listings is
+     * acceptable, losing real user text is not). Never sent to a provider (brains rebuild wire
+     * messages field-by-field).
+     */
     enginePrefixChars?: number;
+    /**
+     * [c209-C] R4 codex 终判 — the ENGINE-TRUSTED SEGMENTS of this user-lane message, as half-open
+     * `[start, end)` UTF-16 code-unit ranges into the flattened text content (ascending,
+     * non-overlapping). Generalizes {@link UserMessage.enginePrefixChars} beyond the head: the resume
+     * continuation preserves ISSUE ORDER (parked steer first, wake message second — the public
+     * contract on ResumeOutcome `wake` / ResumeRun / the resume entry, which a custom Brain may rely
+     * on to read "the last state that appears"), so a TRUSTED engine `<system-reminder>` frame can
+     * legally sit AFTER an untrusted fenced segment; each such frame is recorded as its own segment
+     * wherever it lands. Derived views treat segment bytes as engine guidance (auto-mode window:
+     * neutral note, never `[user]`; compaction serializer: stripped) and everything OUTSIDE the
+     * segments verbatim under user authority.
+     *
+     * Relationship with `enginePrefixChars`: ONE of the two per message — `enginePrefixChars` is
+     * retained as sugar for the single head segment `[0, chars)` (first-frame listings / prompt-hook
+     * context, where the engine bytes are a pure prefix); when both are present (foreign/corrupt
+     * data), `engineSegments` WINS and the prefix field is ignored. Malformed ranges (non-integer,
+     * out of range, descending/overlapping) invalidate the whole field ⇒ verbatim render
+     * (conservative direction, same as an out-of-range prefix). Same additive / old-session-verbatim /
+     * never-on-the-wire posture as `enginePrefixChars`.
+     */
     engineSegments?: ReadonlyArray<{
         start: number;
         end: number;
     }>;
+    /**
+     * [c209-C] codex 收口 C1/C2 — this ENTIRE message is engine-minted guidance (deadline nudges,
+     * graceful-finalize write-out steers, boundary attachment bundles, final-verification / stop-hook
+     * reminders), not user speech. Derived views must not present it under `[user]` authority
+     * (auto-mode window: neutral annotation; compaction serialization: skipped). Same additive /
+     * old-session-verbatim / never-on-the-wire posture as {@link UserMessage.enginePrefixChars}.
+     *
+     * [c209-C] R4 codex 终判 — MUTUALLY EXCLUSIVE with {@link UserMessage.provenance}: a message is
+     * either wholly SKIPPABLE (`engineMinted`) or MUST-STAY-VISIBLE (`provenance:"engine-note"`),
+     * never both. The exclusion is enforced at runtime (mint clamp in the harness'
+     * `createUserMessage`, normalization at the session import gate) and defensively at every
+     * projection: a double-stamped message is treated as `engine-note` — the must-stay-visible
+     * invariant outranks the may-skip one (dropping visible content is the unrecoverable direction).
+     */
     engineMinted?: true;
+    /**
+     * [c209-C] R3 codex 收口 — the "visible but not the user" THIRD state. This message is an
+     * ENGINE-INJECTED note whose CONTENT the model must read (LSP `<new-diagnostics>` blocks,
+     * task-notification frames, TaskStream steering, dynamic memory re-recall, loop recovery
+     * guidance), but which is NOT user speech. Two-state contrast with {@link UserMessage.engineMinted}:
+     *   - `engineMinted`            ⇒ engine guidance whose content derived views may SKIP ENTIRELY
+     *                                 (nudges/finalize/attachment bundles — re-delivered by their own
+     *                                 machinery, no summary/classifier value);
+     *   - `provenance:"engine-note"` ⇒ the content STAYS VISIBLE in derived views (the classifier /
+     *                                 summarizer needs it to follow the run), but under a NEUTRAL
+     *                                 engine label — never `[user]`/`[User]:` authority (an engine
+     *                                 note must not read as user authorization).
+     * [c209-C] R4: the two are MUTUALLY EXCLUSIVE — see the exclusion note on
+     * {@link UserMessage.engineMinted} (double-stamp ⇒ `engine-note` wins everywhere).
+     * Same additive / old-session-verbatim / never-on-the-wire posture as the fields above.
+     */
     provenance?: "engine-note";
+    /**
+     * design/171 §5.2 — WHO spoke this user-lane message, when the session is shared by several people
+     * (thread-style multiplayer). Attribution metadata ONLY: absent = the caller supplied none
+     * (anonymous — every pre-171 session and every single-user host). Persisted on the message;
+     * NEVER sent to a provider (brains rebuild wire messages field-by-field, and
+     * {@link stripEngineMetadata} strips it for a custom Brain that whole-object-serializes). The
+     * model-facing rendering is the SPEAKER ENVELOPE minted by the single projection point
+     * (`projectHumanInput`) INTO the text content — this field is the machine-readable side. The
+     * session-import gate strips foreign values by default (an importer must not re-assert historical
+     * identity; operator-declared trusted imports may keep them). Same additive /
+     * old-session-verbatim posture as the engine-provenance fields above.
+     */
     actor?: ActorAssertion;
 }
 export interface AssistantMessage {
@@ -139,15 +389,64 @@ export interface AssistantMessage {
     responseId?: string;
     diagnostics?: AssistantMessageDiagnostic[];
     usage: Usage;
+    /** TB 尸检 T1-5 (codex 1.238 复审 F3): the provider never delivered a usage frame for this message (e.g. a
+     *  degenerate-repetition cutoff cancelled the stream first) — `usage` above is a zero-synthesized shell.
+     *  Consumers must treat the numbers as UNKNOWN, not zero. Absent ⇒ usage is provider-reported. */
     usageMissing?: true;
     stopReason: StopReason;
     errorMessage?: string;
+    /** Structured cause for `stopReason:"error"` a caller can react to programmatically (errorMessage is
+     *  human-facing prose and NOT a contract). `"length_empty"` = a max_tokens cut that produced reasoning/
+     *  scratch but NO answer text (both brains surface that as an error, not a "length" stop) — the compaction
+     *  summary path escalates its token budget on it. Extend the union as new recoverable causes are classified.
+     *
+     *  RB-464: `"degenerate"` is the DELIBERATE brain-side cut (the repetition loop). It used to be
+     *  identifiable only by comparing `errorMessage` against the exported sentinel string
+     *  `DEGENERATE_MESSAGE` across call sites in two layers — safer than prose matching, but still a
+     *  string standing in for a typed terminal cause: any producer that builds the same text without
+     *  importing the constant is silently invisible to every one of those sites. It is classified here
+     *  instead, on the field whose own contract invites exactly this ("extend the union…"), rather than
+     *  on a second parallel field — two typed causes for one `stopReason:"error"` would leave every
+     *  reader asking which one is authoritative. `errorMessage` still carries the sentinel prose
+     *  verbatim for display.
+     *
+     *  ⚠️ Brain OBLIGATION (RB-482 #12, 5.1.0): stamping this field on every cut turn is part of the
+     *  Brain contract — the sentinel-prose fallback readers are RETIRED, so a custom Brain that stamps
+     *  only `errorMessage` prose is no longer recognized as a cut (terminal-cause.ts reads this field
+     *  and nothing else). Widening note: exhaustive switches on this union gain arms as it grows. */
     errorKind?: "length_empty" | "degenerate";
+    /**
+     * design/124 tier A: this final message was PARTIALLY FINALIZED after a mid-stream connection
+     * loss/stall — the substantive streamed prefix (text and/or completed tool calls) was promoted to
+     * final content instead of failing the turn (CC 198 queryModelStreaming parity: avoid re-billing +
+     * keep the displayed content consistent with the result). `stopReason` is synthesized from the
+     * content ("toolUse" when a completed tool call streamed, else "stop"); `errorMessage` carries the
+     * CC-verbatim warning ("Response stalled mid-stream." / "Connection closed mid-response."), visible
+     * to the model in the transcript. Downstream semantics (agent-loop): `partialFinalized &&
+     * stopReason==="stop"` gets a BOUNDED continue nudge (an unattended run must not book the cut as an
+     * incomplete success); `partialFinalized && stopReason==="toolUse"` executes normally (a truncated
+     * trailing call was already dropped by the finalize malformed path). Additive — absent everywhere else.
+     */
     partialFinalized?: true;
+    /**
+     * Degenerate-repetition telemetry for THIS call (clay 2026-07-10: counts + detected segment, not just
+     * a boolean). `cut` = the event that cancelled the stream (always paired with the DEGENERATE_MESSAGE
+     * errorMessage); `spared` = repetitions that landed in a detection window but were exempted by a
+     * 2e1c161 structural allowance (code-line shape / divider run) — deduped per stream by rule+segment.
+     * The RSI raw material for judging whether the allowance is too wide or too narrow. Additive —
+     * absent when the detector never hit anything.
+     */
     repetition?: {
         cut?: RepetitionEvent;
         spared?: RepetitionEvent[];
     };
+    /**
+     * Blackboard [477]: this `length` stop is a DOWNGRADED reasoning-only STATIC max_tokens hit — the
+     * model spent the entire static output budget on thinking (budget-ignoring gateway shape) and the
+     * brain, granted `StreamOptions.staticReasoningCutDowngrade`, finished the turn as a recoverable
+     * `length` instead of the fail-loud config error. The agent loop counts these per run to enforce
+     * the 2-downgrade stop-loss. Additive — absent everywhere else (incl. the dynamicCut shape).
+     */
     staticReasoningCut?: true;
     timestamp: number;
 }
@@ -161,6 +460,16 @@ export interface ToolResultMessage<TDetails = unknown> {
     timestamp: number;
 }
 export type Message = UserMessage | AssistantMessage | ToolResultMessage;
+/**
+ * RB-3 (campaign S4 carry): strip the engine-provenance metadata fields from user messages before
+ * serializing a Context to an external wire. The five fields (`enginePrefixChars`/`engineSegments`/
+ * `engineMinted`/`provenance`/`actor`, the last per design/171 §5.2) are INTERNAL coordination
+ * between the engine's minting side and its consumers (permission classifier, compaction summarizer,
+ * prompt suggestions, multiplayer attribution) — they must never reach a provider payload. The
+ * built-in brains construct their own wire shapes and are immune; a CUSTOM Brain that
+ * whole-object-serializes messages (`JSON.stringify(context.messages)`) would leak them — run the
+ * array through this projection first.
+ */
 export declare function stripEngineMetadata(messages: Message[]): Message[];
 export type ImagesInputContent = TextContent | ImageContent;
 export type ImagesOutputContent = TextContent | ImageContent;
@@ -182,13 +491,24 @@ export interface AssistantImages {
 import type { TSchema } from "typebox";
 export interface Tool<TParameters extends TSchema = TSchema> {
     name: string;
+    /** VENDORED EDIT (design/115 P0): canonical tool renames keep old model/SDK wire names as aliases. */
     aliases?: string[];
     description: string;
+    /** R2 双形轴 — classic-profile description variant (see ToolSpec.descriptionClassic). Swapped in
+     *  for `description` at mount time when the run's promptProfile is "classic"; absent = one form. */
     descriptionClassic?: string;
     parameters: TParameters;
 }
 export interface Context {
     systemPrompt?: string;
+    /**
+     * Campaign S4 (prompt-assembly §5.4, ADDITIVE): the system prompt as PHYSICAL blocks with
+     * per-block cache-span boundaries. Compatibility projection duty (plan M13): when present,
+     * `systemPrompt` is ALWAYS also populated with the equivalent joined text — a Brain that only
+     * reads `systemPrompt` gets wire-equivalent input (single merged block), never a dropped prompt.
+     * Brains that understand blocks (Anthropic) materialize one system entry per block, ending a
+     * prompt-cache span where `cacheControlBoundary` is set. Absent ⇒ legacy single-string face.
+     */
     systemBlocks?: Array<{
         text: string;
         cacheControlBoundary: boolean;
@@ -196,6 +516,14 @@ export interface Context {
     messages: Message[];
     tools?: Tool[];
 }
+/**
+ * Event protocol for AssistantMessageEventStream.
+ *
+ * Streams should emit `start` before partial updates, then terminate with either:
+ * - `done` carrying the final successful AssistantMessage, or
+ * - `error` carrying the final AssistantMessage with stopReason "error" or "aborted"
+ *   and errorMessage.
+ */
 export type AssistantMessageEvent = {
     type: "start";
     partial: AssistantMessage;
@@ -203,7 +531,13 @@ export type AssistantMessageEvent = {
     type: "text_start";
     contentIndex: number;
     partial: AssistantMessage;
-} | {
+}
+/**
+ * VENDORED EDIT (upstream cherry-pick 6fcc945702, monthly diff 2026-06-13): plain text deltas may
+ * omit `partial` to avoid retaining one full assistant snapshot per token; consumers replay
+ * `delta` from the latest start/end partial checkpoint (agent-loop reconstructs).
+ */
+ | {
     type: "text_delta";
     contentIndex: number;
     delta: string;
@@ -213,7 +547,17 @@ export type AssistantMessageEvent = {
     contentIndex: number;
     content: string;
     partial: AssistantMessage;
-} | {
+}
+/**
+ * design/124 tier B contract note: after a mid-stream failure with only thinking streamed, the
+ * brain seals the block (`thinking_end`) and RE-SENDS the whole turn WITHOUT a second `start` —
+ * the retry attempt may then legally reopen a thinking block at the SAME contentIndex (the openai
+ * parser hardcodes thinking at index 0; the anthropic wire restarts block indexing per attempt).
+ * Consumers that render by `partial` snapshot are naturally correct (each retry event carries a
+ * fresh snapshot that REPLACES the previous attempt's content — CC's "drop the thinking" semantics);
+ * a consumer keying blocks by index gets exactly the intended replacement.
+ */
+ | {
     type: "thinking_start";
     contentIndex: number;
     partial: AssistantMessage;
@@ -236,7 +580,21 @@ export type AssistantMessageEvent = {
     contentIndex: number;
     delta: string;
     partial: AssistantMessage;
-} | {
+}
+/**
+ * design/120 P2.0 provider contract — `toolcall_end` may trigger IN-STREAM TOOL EXECUTION
+ * (agent-loop P2), so its emission carries real semantics, not just UI progress:
+ * - Emit it only when the call's input is COMPLETE and parsed to a valid JSON object (`toolCall`
+ *   is executable as-is). A malformed/truncated accumulation must emit nothing (fail-closed: the
+ *   call then never executes in-stream; the brain's finalize surfaces it via its malformed path).
+ * - Emit AT MOST ONCE per call, and every emitted call MUST appear — same `id`, same `arguments`
+ *   object identity not required but same values — in the terminal `done` message's content.
+ *   (One-directional: content may carry calls that never emitted `toolcall_end`, e.g. trailing
+ *   calls closed at finalize or text-repaired calls; those simply run on the post-stream batch
+ *   path.) An `error` terminal is allowed to lack the block; the loop's error-final reconciliation
+ *   merges executor-held calls back into the persisted content (design/120 §5.4).
+ */
+ | {
     type: "toolcall_end";
     contentIndex: number;
     toolCall: ToolCall;
@@ -258,22 +616,103 @@ export interface AssistantMessageEventStreamContract extends AsyncIterable<Assis
 export interface AssistantMessageEventStreamLike extends AsyncIterable<AssistantMessageEvent> {
     result(): Promise<AssistantMessage>;
 }
+/**
+ * Compatibility settings the OpenAI-compatible completions brain actually reads.
+ *
+ * Thirteen further members were declared here until 2026-08-04 and consumed by NOTHING in the engine
+ * (`supportsStore`, `supportsDeveloperRole`, `supportsUsageInStreaming`, `requiresToolResultName`,
+ * `requiresAssistantAfterToolResult`, `requiresThinkingAsText`, `openRouterRouting`,
+ * `vercelGatewayRouting`, `zaiToolStream`, `supportsStrictMode`, `cacheControlFormat`,
+ * `sendSessionAffinityHeaders`, `supportsLongCacheRetention`) — leftovers of the vendored era whose
+ * behaviour never crossed into the first-party brain, several of them promising a "Default:
+ * auto-detected from URL" that no code performs. They are removed rather than kept: a model author who
+ * sets a declared-only knob gets silence, which is worse than a compile error (same ruling as
+ * {@link OpenAIResponsesCompat}, and now gated by `gate:field-liveness`).
+ */
 export interface OpenAICompletionsCompat {
+    /** Whether the provider supports `reasoning_effort`. Default: auto-detected from URL. */
     supportsReasoningEffort?: boolean;
+    /**
+     * Which `reasoning_effort` tiers this endpoint accepts. Absent → the conservative default
+     * (`minimal | low | medium | high`), so a higher requested tier (`xhigh`/`max`) clamps down to `high`
+     * rather than 422'ing a stock OpenAI endpoint. Declare a higher tier here when the provider genuinely
+     * takes it (e.g. `["minimal","low","medium","high","xhigh"]`). See sema-core design/96 S5.
+     */
     reasoningEffortLevels?: ThinkingLevel[];
+    /** Which field to use for max tokens. Absent → inferred from the model id (no URL auto-detection):
+     *  newer stock-OpenAI families that REQUIRE `max_completion_tokens` (gpt-5*, the o1/o3/o4 families,
+     *  chatgpt-4o*) get it; every other id keeps `max_tokens`, the only spelling many third-party
+     *  OpenAI-compatible endpoints accept. Declare explicitly to override the inference
+     *  (design/119 #3; see `inferMaxTokensField` in brain/openai). */
     maxTokensField?: "max_completion_tokens" | "max_tokens";
+    /** Whether all replayed assistant messages must include an empty reasoning_content field when reasoning is enabled. Default: auto-detected from URL. */
     requiresReasoningContentOnAssistantMessages?: boolean;
+    /** Format for reasoning/thinking parameter. "openai" uses reasoning_effort, "openrouter" uses reasoning: { effort }, "deepseek" uses thinking: { type } plus reasoning_effort, "together" uses reasoning: { enabled } plus reasoning_effort when supported, "zai" uses top-level enable_thinking: boolean, "qwen" uses top-level enable_thinking: boolean, and "qwen-chat-template" uses chat_template_kwargs.enable_thinking. Default: "openai". */
     thinkingFormat?: "openai" | "openrouter" | "deepseek" | "together" | "zai" | "qwen" | "qwen-chat-template";
 }
+/** Compatibility settings for OpenAI Responses APIs. */
+/**
+ * Compatibility settings the Open Responses lane (`createOpenResponsesBrain`) actually reads.
+ * The two former members (`sendSessionIdHeader` / `supportsLongCacheRetention`) had ZERO consumers
+ * anywhere in the engine — declared-only fields that told a typed model author two knobs existed
+ * while the two REAL knobs were unreachable through the typed surface (ruled 2026-08-04, review of
+ * the adapter landing). This declaration now states exactly what the adapter consumes.
+ */
 export interface OpenAIResponsesCompat {
+    /** Does this endpoint accept `reasoning.effort` at all? Absent ⇒ yes. */
     supportsReasoningEffort?: boolean;
+    /** The effort tiers THIS endpoint accepts. Absent ⇒ the engine's default ladder (higher tiers clamp down). */
     reasoningEffortLevels?: ThinkingLevel[];
 }
+/**
+ * Compatibility settings the Anthropic Messages brain actually reads. Four further members
+ * (`supportsEagerToolInputStreaming`, `supportsLongCacheRetention`, `sendSessionAffinityHeaders`,
+ * `supportsCacheControlOnTools`) were declared here with zero consumers until 2026-08-04 — each one
+ * described request behaviour (beta headers, `cache_control` placement, session-affinity routing) that
+ * the brain performs unconditionally or not at all, so declaring the opposite changed nothing. Removed;
+ * see {@link OpenAIResponsesCompat} for the ruling and `gate:field-liveness` for the guard.
+ */
 export interface AnthropicMessagesCompat {
+    /**
+     * How this endpoint takes extended thinking (CC 2.1.198 parity, design/119).
+     * - `"budget"` (default, pre-Fable models): `thinking: { type: "enabled", budget_tokens }`.
+     * - `"adaptive"` (Fable 5 / Opus 4.8/4.7 class): `thinking: { type: "adaptive" }` — NO
+     *   `budget_tokens` (these models 400 on a budget), no max_tokens bump; the intensity is carried
+     *   by `output_config.effort` instead (see {@link effortLevels}). `off` omits the field entirely
+     *   (these models also reject `{type:"disabled"}`).
+     */
     thinkingMode?: "budget" | "adaptive";
+    /**
+     * Effort tiers this endpoint accepts via `output_config.effort` (CC 2.1.198 `effort` /
+     * `xhigh_effort` / `max_effort` capability bits collapsed into one declared set, matching the
+     * `reasoningEffortLevels` pattern on {@link OpenAICompletionsCompat}). Present ⇒ the brain sends
+     * `output_config: { effort }` plus the `effort-2025-11-24` beta header, clamping the requested
+     * tier DOWN into this set (e.g. Fable 5 = `["low","medium","high","xhigh","max"]`; a model without
+     * `xhigh_effort` declares up to `"high"` and higher requests clamp). Absent ⇒ no `output_config`
+     * is ever sent (pre-effort models unchanged).
+     */
     effortLevels?: ThinkingLevel[];
+    /**
+     * Whether the endpoint accepts `temperature` at all. CC 2.1.198 sends temperature only to a
+     * legacy allowlist — Fable-5-class models NEVER receive it (400 risk), independent of thinking
+     * state. Default true (existing models unchanged); `false` drops a caller temperature
+     * unconditionally, not just under extended thinking.
+     */
     supportsTemperature?: boolean;
+    /**
+     * design/119 S4 (CC 2.1.198 `context_management` capability): when thinking is enabled, send
+     * `context_management: { edits: [{ type: "clear_thinking_20251015", keep: "all" }] }` plus the
+     * `context-management-2025-06-27` beta — an explicit opt-OUT of the server's default
+     * thinking-clearing, preserving cross-turn reasoning continuity (what CC sends on first-party
+     * endpoints). Declare only on endpoints that accept the beta (real Anthropic); an
+     * Anthropic-COMPATIBLE gateway (e.g. DeepSeek's anthropic endpoint) must leave it off.
+     */
     contextManagement?: boolean;
+    /**
+     * design/119 S4 (CC 2.1.198): attach the `interleaved-thinking-2025-05-14` beta on tool-enabled
+     * requests with thinking on (thinking blocks may interleave with tool_use). Declare per endpoint;
+     * absent = no beta (pre-119 behavior; a deployment could already do this via static `headers`).
+     */
     interleavedThinking?: boolean;
 }
 export interface Model<TApi extends Api = Api> {
@@ -283,7 +722,20 @@ export interface Model<TApi extends Api = Api> {
     provider: Provider;
     baseUrl: string;
     reasoning: boolean;
+    /**
+     * design/111 — this model's DEFAULT thinking level (per-model preset). The thinking-resolution chain is
+     * `spec.thinking ?? role.thinking ?? model.defaultThinking` (prepare-task) — a caller/role still overrides, but
+     * a model that should "think by default" (e.g. an Anthropic reasoning model defaulting to `medium`) declares it
+     * here instead of every task/role re-specifying. Absent ⇒ no model-level default (chain falls to `undefined` =
+     * thinking off unless a caller/role asks). It is the REQUESTED tier; the per-endpoint clamp (`resolveReasoning`/
+     * `reasoningEffortLevels`) still bounds it — a stock-OpenAI endpoint clamps `max`→`high`, while an
+     * `anthropic-messages` budget endpoint honors the full range up to `max` unclamped.
+     */
     defaultThinking?: ThinkingLevel;
+    /**
+     * Maps OpenClaw thinking levels to provider/model-specific values.
+     * Missing keys use provider defaults. null marks a level as unsupported.
+     */
     thinkingLevelMap?: ThinkingLevelMap;
     input: ("text" | "image")[];
     cost: {
@@ -293,14 +745,59 @@ export interface Model<TApi extends Api = Api> {
         cacheWrite: number;
     };
     contextWindow: number;
+    /**
+     * Optional effective runtime cap used for compaction/session budgeting.
+     * Keeps provider/native contextWindow metadata intact while allowing a
+     * smaller practical window.
+     */
     contextTokens?: number;
+    /**
+     * Optional AUTOCOMPACT window — the window the compaction trigger and the clearStale frontier
+     * are derived from when it differs from the physical request window (dual-window semantics).
+     * CC 2.1.207 posture: its 1M sonnet keeps the PHYSICAL window at 1M while a per-model dynamic
+     * config lowers only the autocompact window to 967000, so the reactive trigger lands at 934000
+     * (= 967000 − 33000); a single window value cannot express both. Consumed by the trigger-side
+     * geometry only (`editBudget`/`sanitizeCompactionSettings`/`shouldCompact` window); the request
+     * hard-stop guard (`guardBudget`) and physical request budgeting stay on
+     * `contextTokens ?? contextWindow`. Absent ⇒ `contextTokens ?? contextWindow`.
+     */
     autoCompactTokens?: number;
+    /**
+     * design/123 D2 — structural token-estimate coefficient: how many CHARACTERS ≈ one token for this
+     * model's tokenizer. Used by every structural (non-usage-anchored) token estimate in the engine:
+     * the compaction trigger's anchor-less fallback, the request-layer defenses (clearStaleToolResults /
+     * trimToBudget), cut-point accounting, the prompt-overhead term, and the summarization input guard.
+     * API-agnostic model property (NOT a wire knob), hence top-level and not `compat`.
+     *
+     * Default **4** (byte-compatible with the historical chars/4 heuristic; CC 198's legacy-family
+     * value — claude-3.x / opus·sonnet-4-x / haiku-4-5). Newer families tokenize denser (CC 198 uses
+     * **3** for the sonnet-5/fable-5 class). CJK-heavy deployments should consider **2–3**: chars/4
+     * underestimates Chinese by 60–75%, which lets the defenses pass over-window requests.
+     */
     charsPerToken?: number;
     maxTokens: number;
+    /** Provider-specific request/runtime parameters passed through to provider plugins. */
     params?: Record<string, unknown>;
+    /**
+     * Extra request-BODY params merged into the provider call (design/40): official provider knobs core
+     * doesn't model as first-class — OpenAI `frequency_penalty`/`presence_penalty`/`top_p`/`seed`/`logit_bias`,
+     * Anthropic `top_k`/`top_p`/`stop_sequences`, etc. Keys core owns (messages/tools/temperature/…) are
+     * stripped (core wins). **Anchored on the Model and stable across turns** — reuse the SAME Model object
+     * (stable key-insertion order) for every turn sharing a cache namespace, or the serialized body bytes
+     * change and the prefix cache breaks (design/9/31). Not for per-turn variation.
+     */
     extraBody?: Record<string, unknown>;
+    /** Extra request HEADERS merged into the provider call. Cannot override auth / content-type / version. */
     headers?: Record<string, string>;
+    /**
+     * design/119 S3 (CC 2.1.198 parity): model-declared system-prompt guidance sections, appended to
+     * the assembled system prompt. This is the declarative home for per-model behavioral patches (CC
+     * ships Fable-5 "mitigations" baked behind model-name checks; sema keeps the MECHANISM generic —
+     * any Model can carry guidance — and the CONTENT as preset data, zero model-name matching in core).
+     * Each entry is one section; joined with blank lines.
+     */
     promptGuidance?: string[];
+    /** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
     compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" ? OpenAIResponsesCompat : TApi extends "anthropic-messages" ? AnthropicMessagesCompat : never;
 }
 export interface ImagesModel<TApi extends ImagesApi = ImagesApi> extends Omit<Model, "api" | "provider" | "reasoning" | "contextWindow" | "maxTokens" | "compat"> {