@sema-agent/core 5.20.0 → 5.21.1

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

@@ -1,69 +1,209 @@
 import type { Static, TSchema } from "typebox";
 import type { AssistantMessage, AssistantMessageEvent, DocumentContent, ImageContent, Message, Model, SimpleStreamOptions, StreamFn as LlmStreamFn, TextContent, Tool, ToolResultMessage } from "../llm/index.js";
+/**
+ * Stream function used by the agent loop.
+ *
+ * Contract:
+ * - Must not throw or return a rejected promise for request/model/runtime failures.
+ * - Must return an AssistantMessageEventStream.
+ * - Failures must be encoded in the returned stream via protocol events and a
+ *   final AssistantMessage with stopReason "error" or "aborted" and errorMessage.
+ */
 export type StreamFn = LlmStreamFn;
+/**
+ * Configuration for how tool calls from a single assistant message are executed.
+ *
+ * - "sequential": each tool call is prepared, executed, and finalized before the next one starts.
+ * - "parallel": tool calls are prepared sequentially, then allowed tools execute concurrently.
+ *   `tool_execution_end` is emitted in tool completion order after each tool is finalized,
+ *   while tool-result message artifacts are emitted later in assistant source order.
+ */
 export type ToolExecutionMode = "sequential" | "parallel";
+/**
+ * Controls how many queued user messages are injected when the agent loop reaches a queue drain point.
+ *
+ * - "all": drain and inject every queued message at that point.
+ * - "one-at-a-time": drain and inject only the oldest queued message, leaving the rest queued for later drain points.
+ */
 export type QueueMode = "all" | "one-at-a-time";
+/** A single tool call content block emitted by an assistant message. */
 export type AgentToolCall = Extract<AssistantMessage["content"][number], {
     type: "toolCall";
 }>;
+/**
+ * Result returned from `beforeToolCall`.
+ *
+ * Returning `{ block: true }` prevents the tool from executing. The loop emits an error tool result instead.
+ * `reason` becomes the text shown in that error result. If omitted, a default blocked message is used.
+ *
+ * Returning `{ updatedInput }` (without `block`) REWRITES the arguments the tool executes with — the
+ * loop replaces the validated args with `updatedInput` and **re-runs `validateToolArguments` on it**
+ * before execution, so a rewrite can never smuggle schema-invalid args into `tool.execute()`. This is
+ * the generic carrier the higher layer uses for arg redaction/clamping (design/37); the loop itself
+ * stays policy-agnostic. `block` wins over `updatedInput` if both are set.
+ *
+ * Keep in sync with the harness hook result `ToolCallResult` (harness/types.ts), which the harness's
+ * `beforeToolCall` callback returns verbatim.
+ */
 export interface BeforeToolCallResult {
     block?: boolean;
     reason?: string;
     updatedInput?: unknown;
 }
+/**
+ * Partial override returned from `afterToolCall`.
+ *
+ * Merge semantics are field-by-field:
+ * - `content`: if provided, replaces the tool result content array in full
+ * - `details`: if provided, replaces the tool result details value in full
+ * - `isError`: if provided, replaces the tool result error flag
+ * - `terminate`: if provided, replaces the early-termination hint
+ *
+ * Omitted fields keep the original executed tool result values.
+ * There is no deep merge for `content` or `details`.
+ */
 export interface AfterToolCallResult {
     content?: (TextContent | ImageContent | DocumentContent)[];
     details?: unknown;
     isError?: boolean;
+    /**
+     * Hint that the agent should stop after the current tool batch.
+     * Early termination only happens when every finalized tool result in the batch sets this to true.
+     */
     terminate?: boolean;
 }
+/** Context passed to `beforeToolCall`. */
 export interface BeforeToolCallContext {
+    /** The assistant message that requested the tool call. */
     assistantMessage: AssistantMessage;
+    /** The raw tool call block from `assistantMessage.content`. */
     toolCall: AgentToolCall;
+    /** Validated tool arguments for the target tool schema. */
     args: unknown;
+    /** Current agent context at the time the tool call is prepared. */
     context: AgentContext;
 }
+/** Context passed to `afterToolCall`. */
 export interface AfterToolCallContext {
+    /** The assistant message that requested the tool call. */
     assistantMessage: AssistantMessage;
+    /** The raw tool call block from `assistantMessage.content`. */
     toolCall: AgentToolCall;
+    /** Validated tool arguments for the target tool schema. */
     args: unknown;
+    /** The executed tool result before unknown `afterToolCall` overrides are applied. */
     result: AgentToolResult<unknown>;
+    /** Whether the executed tool result is currently treated as an error. */
     isError: boolean;
+    /** Current agent context at the time the tool call is finalized. */
     context: AgentContext;
 }
+/** Context passed to `shouldStopAfterTurn`. */
 export interface ShouldStopAfterTurnContext {
+    /** The assistant message that completed the turn. */
     message: AssistantMessage;
+    /** Tool result messages passed to the preceding `turn_end` event. */
     toolResults: ToolResultMessage[];
+    /** Current agent context after the turn's assistant message and tool results have been appended. */
     context: AgentContext;
+    /** Messages that this loop invocation will return if it exits at this point. Prompt runs include the initial prompt messages; continuation runs do not include pre-existing context messages. */
     newMessages: AgentMessage[];
 }
+/** Replacement runtime state used by the agent loop before starting another provider request. */
 export interface AgentLoopTurnUpdate {
+    /** Context for the next provider request. */
     context?: AgentContext;
+    /** Model for the next provider request. */
     model?: Model;
+    /** Thinking level for the next provider request. */
     thinkingLevel?: ThinkingLevel;
 }
 export interface PrepareNextTurnContext extends ShouldStopAfterTurnContext {
 }
+/**
+ * Prompt-too-long recovery seam (design/118 ④b, the CC reactive-compact chain adapted to sema's
+ * "brain outside" architecture). The LOOP owns the retry transition; the CALLER owns the policy —
+ * `recover` typically compacts/trims the transcript (the harness/runner wires it to the engine
+ * compaction machinery). Retries happen INSIDE the turn (no extra `turn_start`); the failed
+ * assistant is dropped from the retry context and never enters the run's returned messages.
+ */
 export interface LoopPromptTooLongRecovery {
+    /**
+     * Produce a replacement transcript to retry the provider request with (attempt starts at 1).
+     * Return undefined to give up — the loop then surfaces the original error unchanged.
+     * Contract: must not throw or reject.
+     */
     recover: (messages: AgentMessage[], attempt: number) => Promise<AgentMessage[] | undefined>;
+    /** Override the prompt-too-long classifier. Default: a conservative provider-message pattern. */
     detect?: (message: AssistantMessage) => boolean;
+    /** Max recovery retries per turn. Default: 2. */
     maxRetries?: number;
+    /**
+     * M1 (docs/PARITY-CONTEXT-TRANSACTIONS-2026-07-10 §4): withhold the failed assistant's
+     * message_start/message_end stream events while a recovery attempt is pending — CC 198 holds
+     * these errors inside its stream decoder (`claude-cli-2.1.198.pretty.js:473371-473374`) and only
+     * leaks them once recovery's outcome is known. Recovery succeeded ⇒ the failure stays invisible
+     * to event consumers; failed/declined ⇒ the events leak at that point (terminal truth unchanged).
+     * Default true (CC-aligned). `false` restores the pre-M1 live leak of the interim error.
+     */
     withholdErrorEvents?: boolean;
 }
+/**
+ * Truncated-output auto-continue (design/118 ④b, the CC max_output_tokens recovery). When a turn
+ * stops with `stopReason: "length"` and produced NO tool calls, the loop injects a synthetic
+ * continue nudge (a `custom` message, `display: false`) and runs another turn, up to `maxContinues`
+ * CONSECUTIVE times (the counter resets on any non-length turn). Absent ⇒ OFF (a "length" answer
+ * ends the run — the pre-④b behavior).
+ *
+ * RB-258: when the budget IS configured and runs out on a still-`length` turn, the loop ends with the
+ * dedicated terminal reason `truncated_output_exhausted` (visible on the `LoopTraceSink`) instead of a
+ * plain `completed` — the caller can tell "kept hitting the output cap" apart from "actually finished".
+ * The OFF case is unchanged (no budget ⇒ nothing to exhaust ⇒ still `completed`).
+ */
 export interface LoopTruncatedOutputRecovery {
+    /** Max consecutive auto-continues. Default: 3. */
     maxContinues?: number;
 }
+/**
+ * Malformed-tool-use retry (design/119 S2, CC 2.1.198 :473745-473785). A turn that stops with
+ * `toolUse` but carries ZERO parseable tool calls (the brain dropped truncated/invalid ones) used to
+ * end the run silently mid-task. When enabled, inject a synthetic retry nudge and run another turn,
+ * up to `maxRetries` per run (CC: once). Absent ⇒ OFF (pre-S2 behavior).
+ */
 export interface LoopMalformedToolUseRecovery {
+    /** Max retries per run. Default: 1. */
     maxRetries?: number;
 }
+/**
+ * Thinking-only retry (design/119 S2, CC 2.1.198 :473786-473825 — the adaptive-thinking era
+ * companion). A turn that stops normally with thinking block(s) but NO visible text and NO tool
+ * calls used to end the run as a silent empty success. When enabled, inject a "respond with visible
+ * output" nudge and run another turn, up to `maxRetries` per run (CC: once). Absent ⇒ OFF.
+ */
 export interface LoopThinkingOnlyRecovery {
+    /** Max retries per run. Default: 1. */
     maxRetries?: number;
 }
+/** Recovery chains the loop can drive (design/118 ④b + design/119 S2). All absent ⇒ the zero-recovery loop.
+ *  REF-D22 (keep-with-reason, 2026-08): `engine/harness/agent-harness.ts`'s `HarnessLoopRecovery` mirrors
+ *  this shape — `truncatedOutput`/`malformedToolUse`/`thinkingOnly` already reference the named types
+ *  below by direct import (no drift risk); `degenerateOutput` (2 fields) is hand-copied there and is a
+ *  candidate for a future `Pick`-style extraction; `promptTooLong` is
+ *  INTENTIONALLY forked — the harness side is a session-level `recover(attempt)` reduction, this loop
+ *  side is `recover(messages, attempt)` and also carries `withholdErrorEvents`, so the two can never share
+ *  one type. (`agent-harness.ts` is outside this file's edit scope — its side of this mutual-reference
+ *  note is pending.) */
 export interface LoopRecoveryOptions {
     promptTooLong?: LoopPromptTooLongRecovery;
     truncatedOutput?: LoopTruncatedOutputRecovery;
     malformedToolUse?: LoopMalformedToolUseRecovery;
     thinkingOnly?: LoopThinkingOnlyRecovery;
+    /** TB 尸检 T1-4: a degenerate-repetition CUTOFF turn (the brain cancelled the stream and stamped the
+     *  turn errored) gets a bounded "take a different approach" continue instead of ending the run — the
+     *  salvaged prefix is real work, and one bad sampling run shouldn't void it. `detect` is caller-injected
+     *  (core owns the brain's DEGENERATE_MESSAGE constant; the loop stays brain-agnostic). Consecutive cap
+     *  `maxContinues` (default 2); a second consecutive degeneration falls through to the normal error
+     *  terminal (assemble → `output.degenerate` + salvagedOutput, unchanged). */
     degenerateOutput?: {
         detect: (message: AssistantMessage) => boolean;
         maxContinues?: number;
@@ -71,94 +211,378 @@ export interface LoopRecoveryOptions {
 }
 export interface AgentLoopConfig extends SimpleStreamOptions {
     model: Model;
+    /** Error-recovery chains (design/118 ④b). Absent ⇒ no recovery (errors end the run as before). */
     recovery?: LoopRecoveryOptions;
+    /**
+     * design/130 P1: per-CALL dynamic output-token cap, evaluated immediately before EACH provider
+     * call (the static `maxTokens` from SimpleStreamOptions is snapshotted once per run — this seam
+     * exists so a wall-clock-aware host can shrink individual calls as the budget drains). A
+     * `number` return overrides `maxTokens` for that call only; `undefined` leaves the static chain
+     * untouched. The provider must be cheap and side-effect-light: it runs on the hot path.
+     */
     maxTokensPerCall?: () => number | undefined;
+    /**
+     * 1.296 件A: per-CALL advisory stall watchdogs, evaluated immediately before EACH provider call
+     * and forwarded as `StreamOptions.stallTimeouts` — the host supplies values so a SILENT stream
+     * (zero deltas) is bounded by the brain's retryable stall machinery instead of hanging the run.
+     * Advisory: a brain's construction-time `BrainTimeoutConfig` field wins when present; `undefined`
+     * return ⇒ nothing supplied. Must be cheap (hot path).
+     */
     stallTimeoutsPerCall?: () => import("../llm/types.js").StallTimeouts | undefined;
+    /**
+     * design/120 P1: concurrency cap inside a parallel tool batch. Default 10 (CC 198's production
+     * default — its knob is the CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY env; sema takes config).
+     */
     maxToolConcurrency?: number;
+    /**
+     * design/120 P2: in-stream tool execution (CC StreamingToolExecutor, admission narrowed).
+     * When true, a concurrency-safe tool call whose arguments completed mid-stream (`toolcall_end`)
+     * starts executing while the model is still streaming, instead of waiting for the full response.
+     *
+     * Default: OFF (undefined) — behavior is exactly the P1 partitioned batch pipeline.
+     *
+     * Setting this true is the HOST'S PROMISE that no `beforeToolCall` gate on this run can durably
+     * suspend (mint a checkpoint + abort): in-stream calls still run the full prepare chain (defense
+     * in depth — block/updatedInput work as normal), but a mid-stream durable suspend has no stable
+     * leaf to hang its checkpoint on. The harness wires this only when no `tool_call` hook handler
+     * is registered (snapshot per turn); registering a suspending handler mid-run after opting in is
+     * a host contract violation (undefined behavior). Admission per call additionally requires:
+     * `toolExecution !== "sequential"`, the tool's `executionMode !== "sequential"`, the source-order
+     * barrier (once any call bounces to the batch pipeline, every later call bounces too — the CC
+     * processQueue FIFO-break equivalent), and in-flight < `maxToolConcurrency`.
+     */
     streamingToolExecution?: boolean;
+    /**
+     * Converts AgentMessage[] to LLM-compatible Message[] before each LLM call.
+     *
+     * Each AgentMessage must be converted to a UserMessage, AssistantMessage, or ToolResultMessage
+     * that the LLM can understand. AgentMessages that cannot be converted (e.g., UI-only notifications,
+     * status messages) should be filtered out.
+     *
+     * Contract: must not throw or reject. Return a safe fallback value instead.
+     * Throwing interrupts the low-level agent loop without producing a normal event sequence.
+     *
+     * @example
+     * ```typescript
+     * convertToLlm: (messages) => messages.flatMap(m => {
+     *   if (m.role === "custom") {
+     *     // Convert custom message to user message
+     *     return [{ role: "user", content: m.content, timestamp: m.timestamp }];
+     *   }
+     *   if (m.role === "notification") {
+     *     // Filter out UI-only messages
+     *     return [];
+     *   }
+     *   // Pass through standard LLM messages
+     *   return [m];
+     * })
+     * ```
+     */
     convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /**
+     * Optional transform applied to the context before `convertToLlm`.
+     *
+     * Use this for operations that work at the AgentMessage level:
+     * - Context window management (pruning old messages)
+     * - Injecting context from external sources
+     *
+     * Contract: must not throw or reject. Return the original messages or another
+     * safe fallback value instead.
+     *
+     * @example
+     * ```typescript
+     * transformContext: async (messages) => {
+     *   if (estimateTokens(messages) > MAX_TOKENS) {
+     *     return pruneOldMessages(messages);
+     *   }
+     *   return messages;
+     * }
+     * ```
+     */
     transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
+    /**
+     * Resolves an API key dynamically for each LLM call.
+     *
+     * Useful for short-lived OAuth tokens (e.g., GitHub Copilot) that may expire
+     * during long-running tool execution phases.
+     *
+     * Contract: must not throw or reject. Return undefined when no key is available.
+     */
     getApiKey?: (provider: string) => Promise<string | undefined> | string | undefined;
+    /**
+     * Called after each turn fully completes and `turn_end` has been emitted.
+     *
+     * If it returns true, the loop emits `agent_end` and exits before polling steering or follow-up queues,
+     * without starting another LLM call. The current assistant response and any tool executions finish normally.
+     *
+     * Use this to request a graceful stop after the current turn, e.g. before context gets too full.
+     *
+     * Contract: must not throw or reject. Throwing interrupts the low-level agent loop without producing a normal event sequence.
+     */
     shouldStopAfterTurn?: (context: ShouldStopAfterTurnContext) => boolean | Promise<boolean>;
+    /**
+     * Called after `turn_end` and before the loop decides whether another provider request should start.
+     * Return replacement context/model/thinking state to affect the next turn in this run.
+     * Return undefined to keep using the current context/config.
+     */
     prepareNextTurn?: (context: PrepareNextTurnContext) => AgentLoopTurnUpdate | undefined | Promise<AgentLoopTurnUpdate | undefined>;
+    /**
+     * Returns steering messages to inject into the conversation mid-run.
+     *
+     * Called after the current assistant turn finishes executing its tool calls, unless `shouldStopAfterTurn` exits first.
+     * If messages are returned, they are added to the context before the next LLM call.
+     * Tool calls from the current assistant message are not skipped.
+     *
+     * Use this for "steering" the agent while it's working.
+     *
+     * Contract: must not throw or reject. Return [] when no steering messages are available.
+     */
     getSteeringMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Returns follow-up messages to process after the agent would otherwise stop.
+     *
+     * Called when the agent has no more tool calls and no steering messages.
+     * If messages are returned, they're added to the context and the agent
+     * continues with another turn.
+     *
+     * Use this for follow-up messages that should wait until the agent finishes.
+     *
+     * Contract: must not throw or reject. Return [] when no follow-up messages are available.
+     */
     getFollowUpMessages?: () => Promise<AgentMessage[]>;
+    /**
+     * Tool execution mode.
+     * - "sequential": execute tool calls one by one
+     * - "parallel": preflight tool calls sequentially, then execute allowed tools concurrently;
+     *   emit `tool_execution_end` in tool completion order after each tool is finalized,
+     *   then emit tool-result message artifacts later in assistant source order
+     *
+     * Default: "parallel"
+     */
     toolExecution?: ToolExecutionMode;
+    /**
+     * Called before a tool is executed, after arguments have been validated.
+     *
+     * Return `{ block: true }` to prevent execution. The loop emits an error tool result instead.
+     * The hook receives the agent abort signal and is responsible for honoring it.
+     */
     beforeToolCall?: (context: BeforeToolCallContext, signal?: AbortSignal) => Promise<BeforeToolCallResult | undefined>;
+    /**
+     * Classifies an in-loop abort for the short-circuit error results the loop mints when `signal`
+     * fires around tool execution (the "Operation aborted" / "operation aborted before execution"
+     * family). When supplied, a non-undefined return value is attached as the minted result's
+     * `details` — a host that KNOWS why the signal fired (e.g. a durable approval gate parked the
+     * batch) stamps a structured marker such as `{ code: "gate.parked" }`, so a consumer can
+     * distinguish a park poison frame from a plain cancel WITHOUT parsing the result text. The
+     * abort texts themselves are a consumer contract and never change here. Evaluated at mint time
+     * (after the abort fired), so the host reads its own post-abort state, not a snapshot.
+     */
     abortResultDetails?: () => Record<string, unknown> | undefined;
+    /**
+     * Called after a tool finishes executing, before `tool_execution_end` and tool-result message events are emitted.
+     *
+     * Return an `AfterToolCallResult` to override parts of the executed tool result:
+     * - `content` replaces the full content array
+     * - `details` replaces the full details payload
+     * - `isError` replaces the error flag
+     * - `terminate` replaces the early-termination hint
+     *
+     * Any omitted fields keep their original values. No deep merge is performed.
+     * The hook receives the agent abort signal and is responsible for honoring it.
+     */
     afterToolCall?: (context: AfterToolCallContext, signal?: AbortSignal) => Promise<AfterToolCallResult | undefined>;
 }
+/**
+ * Thinking/reasoning level for models that support it.
+ * Note: "xhigh" is only supported by selected model families. Use model thinking-level metadata
+ * from openclaw/plugin-sdk/llm to detect support for a concrete model.
+ */
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 export interface BashExecutionMessage {
+    /** Harness role for shell command transcripts. */
     role: "bashExecution";
+    /** Command line that was executed. */
     command: string;
+    /** Captured command output, usually already truncated for context. */
     output: string;
+    /** Process exit code when the command reached process exit. */
     exitCode: number | undefined;
+    /** True when the command was interrupted before normal completion. */
     cancelled: boolean;
+    /** True when output was shortened for transcript/context storage. */
     truncated: boolean;
+    /** Optional path containing the complete output when truncation occurred. */
     fullOutputPath?: string;
+    /** Millisecond timestamp for transcript ordering. */
     timestamp: number;
+    /** Exclude this command transcript from model context while keeping it in session history. */
     excludeFromContext?: boolean;
 }
 export interface CustomMessage<T = unknown> {
+    /** Harness role for application-defined transcript content. */
     role: "custom";
+    /** Application-defined discriminator for rendering or handling this message. */
     customType: string;
+    /** Content replayed into model context when this message is included. */
     content: string | (TextContent | ImageContent)[];
+    /** Whether UI surfaces should display this message. */
     display: boolean;
+    /** Optional application-specific metadata. */
     details?: T;
+    /** [c209-C] R3: this custom message is an ENGINE-INJECTED note (the loop's own recovery nudges) —
+     *  convertToLlm threads the marker onto the minted user message (`UserMessage.provenance`), so
+     *  derived views (auto-mode window, compaction serializer) present it under a neutral engine label,
+     *  never `[user]` authority. Set by the INJECTOR at mint time; absent ⇒ verbatim user-lane render. */
     provenance?: "engine-note";
+    /** Millisecond timestamp for transcript ordering. */
     timestamp: number;
 }
 export interface CompactionSummaryMessage {
+    /** Harness role for summaries that replace compacted transcript history. */
     role: "compactionSummary";
+    /** Summary text inserted back into model context. */
     summary: string;
+    /** Estimated context tokens before compaction. */
     tokensBefore: number;
+    /** Timestamp may be numeric in memory or string when loaded from older persisted rows. */
     timestamp: number | string;
+    /** RB-398-b① ([2105]): how many transcript messages this summary stands in for — counted at
+     *  render time by `buildSessionContext` (the one place entries become context), so it covers the
+     *  cumulative elision across repeated compactions. Drives the wrapper's scale disclosure
+     *  (`convertToLlm`); absent (directly constructed messages, older render paths) ⇒ the wrapper is
+     *  byte-identical to the historical constant. */
     elidedMessages?: number;
+    /** Optional estimated context tokens after compaction. */
     tokensAfter?: number;
+    /** Optional first retained entry id from the compaction range. */
     firstKeptEntryId?: string;
+    /** Optional implementation-specific compaction metadata. */
     details?: unknown;
 }
+/**
+ * Extensible interface for custom app and harness messages.
+ * Apps can extend via declaration merging.
+ */
 export interface CustomAgentMessages {
     bashExecution: BashExecutionMessage;
     custom: CustomMessage;
     compactionSummary: CompactionSummaryMessage;
 }
+/**
+ * AgentMessage: Union of LLM messages + custom messages.
+ * This abstraction allows apps to add custom message types while maintaining
+ * type safety and compatibility with the base LLM messages.
+ */
 export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
+/** Channel-safe progress text emitted by a running tool. */
 export interface AgentToolProgress {
+    /** Public text suitable for user-facing progress surfaces. */
     text: string;
+    /** Tool progress is rendered by channel progress UIs. */
     visibility: "channel";
+    /** Progress text must not contain secrets, private args, or fetched content. */
     privacy: "public";
+    /** Optional stable id for progress line replacement. */
     id?: string;
 }
+/** Final or partial result produced by a tool. */
 export interface AgentToolResult<T> {
+    /** Text, image or document content returned to the model. */
     content: (TextContent | ImageContent | DocumentContent)[];
+    /** Arbitrary structured details for logs or UI rendering. */
     details: T;
+    /** [1331]③ — mark a RETURNED failure receipt as an error without throwing (keeps structured
+     *  `details` while the wire tool_result carries is_error:true; a non-thrown failure marked
+     *  non-error walks the shell's success rendering and can vanish). Omitted = success. */
     isError?: boolean;
+    /** Optional public progress hint for partial tool updates; never model content. */
     progress?: AgentToolProgress;
+    /**
+     * Hint that the agent should stop after the current tool batch.
+     * Early termination only happens when every finalized tool result in the batch sets this to true.
+     */
     terminate?: boolean;
 }
+/** Callback used by tools to stream partial execution updates. */
 export type AgentToolUpdateCallback<T = unknown> = (partialResult: AgentToolResult<T>) => void;
+/** Tool definition used by the agent runtime. */
 export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unknown> extends Tool<TParameters> {
+    /** VENDORED EDIT (design/115 P0): inherited from Tool — additional names that dispatch to this tool (RB-476-A: no first-party legacy names remain; the seam serves third-party ToolSpec.aliases). */
     aliases?: string[];
+    /** Human-readable label for UI display. */
     label: string;
+    /**
+     * Optional compatibility shim for raw tool-call arguments before schema validation.
+     * Must return an object that matches `TParameters`.
+     */
     prepareArguments?: (args: unknown) => Static<TParameters>;
+    /** [1245] — OPTIONAL approval display projection: how this tool's args render for a human
+     *  approval surface (live onAsk dialogs, durable approval inboxes). Pure and cheap; the gate
+     *  clamps/serializes the result, strips control characters from every string leaf, and swallows
+     *  throws. **UNTRUSTED + ADVISORY-ONLY** (codex [1245] F1): the projection is authored by the
+     *  tool over model-authored args and can misrepresent the executable action — renderers MUST
+     *  contextually escape it, and approval surfaces MUST offer the bound raw args alongside
+     *  (boundInputHash binds args, never the preview). NEVER adjudication input. Mechanism-neutral:
+     *  any tool may declare one (run_workflow projects its script meta). */
     approvalPreview?: (args: unknown) => unknown;
+    /** Execute the tool call. Throw on failure instead of encoding errors in `content`. */
     execute: (toolCallId: string, params: Static<TParameters>, signal?: AbortSignal, onUpdate?: AgentToolUpdateCallback<TDetails>) => Promise<AgentToolResult<TDetails>>;
+    /**
+     * Per-tool execution mode override.
+     * - "sequential": this tool must execute one at a time with other tool calls.
+     * - "parallel": this tool can execute concurrently with other tool calls.
+     *
+     * If omitted, the tool is treated as NOT concurrency-safe unless its input-level
+     * `isConcurrencySafe` hook opts a call in (fail-closed; CC 2.1.206 TOOL_DEFAULTS parity).
+     */
     executionMode?: ToolExecutionMode;
+    /**
+     * MCP server self-declared result-size threshold (CC 198 `_meta["anthropic/maxResultSizeChars"]`,
+     * pretty.js:320015/:320061 — consumer caps at 500K). Set by the MCP materializer when the server
+     * declares it; consulted by the offload mount in prepare-task. Absent on non-MCP tools.
+     */
     mcpMaxResultSizeChars?: number;
+    /**
+     * RB-400-a — MCP server-declared inline pin (CC 220 `_meta["anthropic/alwaysLoad"]`): set by the
+     * MCP materializer when the server's tools/list entry declares it; prepare-task folds these names
+     * into the defer classification's exemption set, ahead of the MCP constant-defer arm — the
+     * server's own channel for keeping one tool's full schema inlined. Absent on non-MCP tools.
+     */
     mcpAlwaysLoad?: boolean;
+    /**
+     * design/120 P1.5 (CC `isConcurrencySafe(parsedInput)` parity): INPUT-level concurrency refinement
+     * for a tool whose safety depends on its arguments — CC's only real consumer is
+     * Bash (a read-only command is safe to parallelize; a write command is not). Consulted by the
+     * partitioner for every tool WITHOUT an explicit `executionMode:"parallel"` (a statically-parallel
+     * tool needs no refinement); `true` = treat THIS CALL as concurrency-safe. A throw = false
+     * (fail-closed, CC same). The partitioner validates the call's args against the tool schema FIRST
+     * (schema-invalid ⇒ unsafe, CC 206 safeParse parity) and hands the hook the validated+coerced
+     * args — still treat defensively (a direct caller may pass raw args). Omitted ⇒ the static mode stands.
+     */
     isConcurrencySafe?: (args: unknown) => boolean;
 }
+/** Context snapshot passed into the low-level agent loop. */
 export interface AgentContext {
+    /** System prompt included with the request. */
     systemPrompt: string;
+    /** S4 (additive): the physical system-block face for block-aware brains. When present it always
+     *  corresponds to the same bytes as `systemPrompt` (M13 projection duty — producer-enforced). */
     systemBlocks?: Array<{
         text: string;
         cacheControlBoundary: boolean;
     }>;
+    /** Transcript visible to the model. */
     messages: AgentMessage[];
+    /** Tools available for this run. */
     tools?: AgentTool[];
 }
+/**
+ * Events emitted by the Agent for UI updates.
+ *
+ * `agent_end` is the last event emitted for a run, but awaited `Agent.subscribe()`
+ * listeners for that event are still part of run settlement. The agent becomes
+ * idle only after those listeners finish.
+ */
 export type AgentEvent = {
     type: "agent_start";
 } | {

package/dist/engine/lsp/frame-decoder.d.ts

@@ -1,2 +1,15 @@
+/**
+ * LSP base-protocol framing over a byte stream (stdio) — `Content-Length: <n>\r\n\r\n<n bytes of JSON>`. A
+ * language server speaks JSON-RPC over stdin/stdout with THIS framing (the part a WebSocket transport skips,
+ * since each WS message is already one message). Ported 1:1 from service's unit-tested `lsp-frames` bridge
+ * decoder + CC's `StreamMessageReader`/`StreamMessageWriter` (vscode-jsonrpc) — hand-rolled here to keep core
+ * dependency-free (the framing is trivial; a native LSP-client dep is not worth it).
+ */
+/** Encode a JSON-RPC message body as an LSP base-protocol frame (header + payload) ready to write to stdin. */
 export declare function encodeFrame(json: string): Buffer;
+/**
+ * A stateful decoder: feed it stdout chunks, get back complete JSON payloads (0+ per chunk — a frame can span
+ * chunks, and a chunk can hold several). `maxBytes` caps the buffer so a server that never emits a delimiter
+ * (or a corrupt Content-Length) can't grow it unboundedly — on overflow the buffer is dropped (fail-safe).
+ */
 export declare function createFrameDecoder(maxBytes?: number): (chunk: Buffer) => string[];