@sema-agent/core 5.20.0 → 5.21.1

package/dist/core/mcp.d.ts

@@ -1,26 +1,121 @@
+/**
+ * MCP client integration. Protocol revision `2025-11-25`, supplied by `@modelcontextprotocol/sdk` 1.29.x
+ * (core pins the SDK and does not negotiate the revision itself). Client side only — core never implements
+ * an MCP server.
+ *
+ * ── DEPRECATION-IMMUNITY REGISTRY (MCP revision `2026-07-28`) ────────────────────────────────────────
+ * The `2026-07-28` revision deprecates four surfaces this module has NEVER implemented. That is not an
+ * accident and not an unfinished edge: each one was declined on its own merits, and the revision has now
+ * put all four on a deprecation clock. So there is no migration debt here — and, symmetrically, none of
+ * the four may be "completed" later on the grounds that the client looks incomplete next to the older
+ * revision's feature list:
+ *
+ *  1. **roots** (`roots/list`, `notifications/roots/list_changed`) — never implemented. The replacement the
+ *     revision itself names is what this module already does: directory/file scope travels as ordinary tool
+ *     arguments or resource URIs, never as a client-hosted root list a server can enumerate.
+ *  2. **sampling** (`sampling/createMessage`) — never implemented. A server that wants model inference uses
+ *     its own provider; core never lends the caller's model channel (or budget) to a connected server.
+ *  3. **logging** (`logging/setLevel`, `notifications/message`) — never implemented. Server diagnostics
+ *     arrive as stdio stderr, or as ordinary tool/resource content, or not at all.
+ *  4. **HTTP+SSE transport** — never implemented. `buildTransport` builds stdio and Streamable HTTP only;
+ *     the SDK's `SSEClientTransport` is not imported anywhere. The revision's SSE off-ramp is therefore a
+ *     no-op here.
+ *
+ * Consequence for future edits: adding any of the four is a REGRESSION, not a gap being closed. The bar for
+ * reopening one is a LATER protocol revision that revives the surface, or a concrete consumer requirement
+ * recorded under its own ticket — not the absence of the feature.
+ *
+ * Two more revision-relevant absences, same reasoning, different cause:
+ *  - `resources/subscribe` / `resources/unsubscribe` — the revision REMOVES the methods. Tool-list freshness
+ *    here is served by the explicit `RefreshMcpTools` tool over the existing connection, which is also the
+ *    only thing this module's connect-per-task connection lifetime can honestly support.
+ *  - `ping` — likewise removed by the revision. Liveness here is the idle watchdog plus per-call timeouts.
+ */
 import { type ProtocolId } from "./protocol-table.js";
 import type { AgentTool } from "../internal/harness-types.js";
 import type { ImageContent, TextContent } from "../internal/llm.js";
 import { type McpImageResizer } from "./image-downsample.js";
 import type { McpServerSpec, OnElicit, ToolEffect } from "./types.js";
+/**
+ * The safety axes (design/77 §4 irreversibility, design/70 egress) derived from one materialized MCP
+ * tool's server-advertised `annotations`. These ride alongside the {@link AgentTool} (which is vendored
+ * and carries no axis fields) so `prepare-task` can fold them into the SAME irreversibleTools/egressTools
+ * collection that `spec.tools` feeds — otherwise a destructive MCP tool would register no gate and a
+ * no-policy deployment would silently AUTO-ALLOW it (MAJOR-1). The `name` is the namespaced tool name
+ * (`<server>__<tool>`), matching the keys the gate looks up.
+ *
+ * Trust note (design F): a server's `annotations` are SERVER-controlled and "not guaranteed faithful" (MCP
+ * spec), so they may only ever TIGHTEN — `destructiveHint` adds an `ask`/suspend, `openWorldHint` adds an
+ * egress tighten — never LOWER. A server's `readOnlyHint` does NOT lower `effect` (that would let a hostile
+ * server lie on a mutating tool to escape repeat-safety + path-confinement). The ONLY trusted way to LOWER an
+ * MCP tool below the fail-closed `write` default is the caller's {@link McpServerSpec.toolAxes} override
+ * (caller = trust root). The synthetic first-party resource tools are the one exception — core sets their
+ * `read` effect itself because it authored them.
+ */
 export interface McpToolAxis {
+    /** Namespaced tool name (`mcp__<server>__<tool>` — design/108 ① CC parity). */
     name: string;
+    /** design/77 §4: `destructiveHint === true` → `"always"` (the gate always tightens allow→ask/suspend).
+     *  `"never"` appears ONLY via an explicit caller override — enforcement ignores it (tighten-only),
+     *  the ask's risk-axes report face consumes it (an explicit negative is a judgment, not silence). */
     irreversibility?: "always" | "never";
+    /** design/70: a non-readOnly tool with `openWorldHint === true` → egress (external write — never
+     *  auto-allowed). `false` appears ONLY via an explicit caller override — same posture as above:
+     *  enforcement ignores it, the report face consumes it. */
     egress?: boolean;
+    /**
+     * The repeat-safety / blast-radius class (NOT the data-trust axis — untrusted resource *content* is fenced
+     * separately by delimitUntrusted). `read`/`idempotent` here means "not write-capable", which keeps the tool
+     * off the LOUD ungated-write warning and out of path-confinement under a skill. Source is restricted by trust
+     * (design F): the SYNTHETIC first-party resource tools set `read` as a fact core controls, and the caller's
+     * {@link McpServerSpec.toolAxes} override may set any effect — a server's own `readOnlyHint` never sets it.
+     */
     effect?: ToolEffect;
 }
+/**
+ * REF-D17: one MCP tool dropped at intake (server/tool/reason) — the SINGLE shape {@link
+ * MaterializedMcp.droppedTools}, {@link McpRefreshResult.dropped}, and `turn-attachments.ts`'s
+ * disclosure rendering/batching all reference. MCP trust/disclosure is a security-relevant surface
+ * (the trust model was BREAKING-redone historically) — a drift between the connect-time and
+ * refresh-time shapes would make a real field change invisible at one of the two intake paths.
+ */
 export interface McpDroppedTool {
     server: string;
     tool: string;
     reason: string;
 }
+/** Tools materialized from one or more MCP servers, plus a disposer to disconnect them. */
 export interface MaterializedMcp {
     tools: AgentTool[];
+    /**
+     * Per-tool safety axes derived from each tool's MCP `annotations` (design/77 §4 / design/70). One entry
+     * per materialized tool that carries a tightening hint; `prepare-task` folds these into its
+     * irreversibleTools/egressTools sets so a destructive/open-world MCP tool REGISTERS the gate + tightens
+     * even on a no-policy deployment. Empty when no server advertised a relevant annotation.
+     */
     toolAxes: McpToolAxis[];
+    /**
+     * MCP server `instructions` (design/64 §17.3, CC `# MCP Server Instructions`): the optional guidance a
+     * connected server returns from `initialize`. The Runner injects these into the (stable) system prompt so
+     * the model uses the server's tools correctly. One entry per server that provided non-empty instructions.
+     */
     serverInstructions: Array<{
         server: string;
         text: string;
     }>;
+    /**
+     * G1 通告层续批 (CC `mcp_instructions_delta` parity) — the run-scoped instruction-delta ref the run
+     * loop drains at turn boundaries (`spec.attachments.mcpInstructions` opt-in; `newTools` consumption
+     * discipline: drained only when the announcement survived the byte cap intact).
+     * - `pendingRemovals`: an INSTRUCTION-BEARING server whose transport closed mid-task (the CC
+     *   "servers have disconnected — their instructions above no longer apply" copy is instruction-scoped,
+     *   so instruction-less servers are not tracked). `dispose()` disarms first: task teardown is not a
+     *   disconnect.
+     * - `pendingAdds`: the CC add lane ("# MCP Server Instructions" reminder). Structurally present for a
+     *   dynamic mid-task connect face; TODAY nothing populates it — sema connects all servers at prepare
+     *   and carries their initial instructions in the stable system prompt (design/64 §17.3, deliberate
+     *   CC deviation: prefix-cache-correct).
+     */
     instructionsDelta: {
         pendingAdds: Array<{
             server: string;
@@ -28,14 +123,74 @@ export interface MaterializedMcp {
         }>;
         pendingRemovals: string[];
     };
+    /**
+     * One entry per server that failed to connect / list its tools and was SKIPPED (fail-open,
+     * design/29). The task proceeds with the healthy servers' tools — a single bad server (missing
+     * stdio command, unreachable URL) must never brick every task in the scenario. The Runner forwards
+     * these to `onError(phase:"mcp")`. Empty when every server connected.
+     */
     warnings: Error[];
+    /**
+     * [cc216] Tools DROPPED at intake because the server advertised a schema no provider accepts
+     * ({@link mcpToolSchemaProblem}) — without the drop, one malformed tool schema riding the wire
+     * fails the WHOLE model request (provider 400), bricking the task for every healthy tool
+     * (CC 2.1.216 ships the same intake prune, `tengu_mcp_drop_invalid_tool_schemas`).
+     *
+     * HONEST REACH (pinned in mcp-dropped-tools.test.ts): with the bundled TS MCP SDK, a string-root
+     * schema already fails the SDK client's OWN zod at `listTools` — the whole server is skipped
+     * (warnings face) and this gate never sees the listing, losing healthy sibling tools with it
+     * (SDK-upstream failure mode, recorded). This per-tool gate is DEFENSE IN DEPTH: it binds when a
+     * transport/SDK revision delivers schemas the client does not fully validate.
+     *
+     * The drop is NEVER silent, two faces (CC parity — its `mcp_dropped_tools_delta` system reminder):
+     * - operator: prepare-task forwards each entry to `onError(phase:"mcp")` alongside `warnings`;
+     * - model: the run loop announces the entries ONCE at a turn boundary (`mcp_dropped_tools`
+     *   attachment, `mcpInstructions` opt-in lane) and DRAINS this array on intact delivery — same
+     *   survival-gated consumption discipline as `instructionsDelta`.
+     * `tool` is the server-advertised name, neutralized at intake (`inlineUntrusted`); `reason` is
+     * core-TEMPLATED but its structural-error paths may embed server-controlled property names, so
+     * the whole string is likewise neutralized + bounded at intake (single-line, ≤240 cps, fences
+     * defused) — the bound also keeps one rendered announce entry inside a single frame.
+     */
     droppedTools: McpDroppedTool[];
+    /**
+     * design/99 §E9 — per-server status, a PURE PROJECTION of THIS materialization (no new connection logic).
+     * One entry per declared server. **Semantics = the moment of this task leg's materialize** — core never
+     * persists MCP connections, so it is "did this leg connect", NOT a live session-health signal between tasks.
+     * A consumer (service) surfacing it as session status must understand that. `toolNames` are the namespaced
+     * (`<server>__<tool>`) names exposed.
+     *
+     * RB-437-a — READ THIS AS A SNAPSHOT, NOT A HEARTBEAT. `status` is the connect-time verdict and is never
+     * rewritten: a server that dies mid-task still reads `connected` here, because that IS what happened at
+     * materialize. The one live bit is {@link McpServerStatus.transportClosed} (set if and when core observes
+     * the transport go away — see its own note for the reach). For an authoritative answer about a server's
+     * health RIGHT NOW, call {@link refresh} — it is the only face that touches the connection.
+     */
     statuses: McpServerStatus[];
+    /**
+     * [1605] RefreshMcpTools (CC 2.1.218 parity, cli-锚形) — re-read the tool list of one server (or
+     * every CONNECTED server when `server` is omitted) over the EXISTING connection. NEVER dials or
+     * re-dials: a dead/never-connected server reports `not_connected`; a live listTools failure
+     * reports `failed` (the connection is left as-is). A refreshed entry carries the NEW intake
+     * result (tools/axes/dropped — the same schema-gate/namespacing/axis pipeline as connect) plus
+     * the added/removed namespaced tool names relative to the previous listing; the caller (the
+     * RefreshMcpTools tool mount in prepare-task) swaps them into the harness toolset.
+     *
+     * LEG-LOCAL fact (review, documented): refresh results do NOT ride a checkpoint — a durable
+     * resume re-materializes and takes a FRESH first listing, so refreshed tools may be absent on the
+     * resumed leg until RefreshMcpTools is called again (an honest not-found, never a silent
+     * misroute).
+     */
     refresh: (server?: string) => Promise<McpRefreshResult[]>;
     dispose: () => Promise<void>;
 }
+/** [1605] One per-server entry of {@link MaterializedMcp.refresh}. `added`/`removed` are namespaced
+ *  (`mcp__<server>__<tool>`) names; `tools`/`axes`/`dropped` are present only on `"refreshed"`. */
 export interface McpRefreshResult {
     server: string;
+    /** The server's namespaced-name prefix (`mcp__<normalized-server>__`) — the consumer's SPLICE
+     *  DOMAIN for the swap (review F4: a prefix domain is self-healing and decoupled from the diff
+     *  baseline, which advances even when a consumer skips a swap). Present on every entry. */
     prefix: string;
     status: "refreshed" | "not_connected" | "failed";
     toolCount: number;
@@ -46,8 +201,14 @@ export interface McpRefreshResult {
     dropped?: McpDroppedTool[];
     error?: string;
 }
+/** design/99 §E9 — projected per-server MCP status (see {@link MaterializedMcp.statuses}). NOTE: `serverInfo`
+ *  and `error` are SERVER-controlled strings (verbatim from the remote) — UNTRUSTED; a consumer rendering them
+ *  into a TUI/log must treat them as such (a hostile server could embed ANSI/break-out sequences). `toolNames`
+ *  are namespaced with a core-controlled `mcp__<server>__` prefix (design/108 ①). */
 export interface McpServerStatus {
     name: string;
+    /** The CONNECT-TIME verdict for this leg — "did this server connect and list its tools". Deliberately
+     *  frozen: a later death does not rewrite it (see {@link transportClosed} and `MaterializedMcp.refresh`). */
     status: "connected" | "failed";
     serverInfo?: {
         name: string;
@@ -55,48 +216,194 @@ export interface McpServerStatus {
     };
     toolNames?: string[];
     error?: string;
+    /**
+     * RB-437-a — set to `true` once core OBSERVES this server's transport close during the task; absent
+     * otherwise (never `false`: absence means "no close was observed", which is not the same as "alive").
+     * It mirrors exactly the flag core's own fail-fast path keys on, so `transportClosed === true` also
+     * means every further call to this server's tools/resources is refused without dialing.
+     *
+     * REACH (honest, and the reason `refresh()` stays the authority): this needs a transport-level close
+     * NOTIFICATION. A stdio server has one — the child process exiting closes the pipe. A streamable-HTTP
+     * endpoint does NOT: the SDK's HTTP transport raises `onclose` only when the client itself closes it,
+     * so an endpoint that dies is discovered per-REQUEST (as a translated transport failure carrying the
+     * server name and the outcome) and this field stays absent.
+     */
     transportClosed?: boolean;
 }
+/**
+ * design/108 ① (CC 2.1.187 parity) — the GLOBAL `mcp__` marker prefix. CC names every MCP tool
+ * `mcp__<server>__<tool>` so a consumer (permission allowlist, bypass-exempt, the flywheel's whitelist) can
+ * identify an MCP-originated tool by prefix ALONE, without knowing the per-deployment server names. Exported so
+ * downstream consumers share one source (the durable-resume canonicalizer is retired — RB-476-A).
+ * The value is OWNED by the protocol table (protocol-table.ts) — this export is the public face.
+ *
+ * The type is the LITERAL `"mcp__"`, not `string`: a downstream literal-typed position (a template-literal
+ * type, a keyed lookup) compiles against the literal and stops compiling the moment this widens — and the
+ * export-surface snapshot is name → kind, so it cannot see a widening at all. Annotated rather than
+ * asserted, so a table-side change to the prefix surfaces as a compile error here instead of being
+ * silently re-narrowed by a cast.
+ */
 export declare const MCP_PREFIX: "mcp__";
+/**
+ * F4-② (CC :320015/:320061): resolve a server's self-declared per-tool result-size threshold from its
+ * `_meta`. Non-numeric/non-finite/non-positive → undefined (declaration ignored); valid → capped at
+ * {@link MCP_META_RESULT_SIZE_CAP}. Exported for tests.
+ */
 export declare function resolveMcpDeclaredResultSize(meta: Record<string, unknown> | undefined): number | undefined;
+/**
+ * Apply the token gate to a mapped MCP content array (CC `$Mp`/`BMp` shape): text blocks consume a
+ * cumulative char budget of `tokens×4`; past the budget they are sliced/dropped head-keep, and the CC
+ * guidance note is appended as a final text block. Non-text blocks (images) pass through untouched —
+ * same convention as the offload wrapper. Exported for tests.
+ */
 export declare function gateMcpOutput(content: Array<TextContent | ImageContent>, limitTokens?: number): Array<TextContent | ImageContent>;
 export declare function structuredContentErrorLine(structuredContent: unknown, collectedText: string): string | undefined;
+/** Head+tail bound for MCP error text (exported for tests). */
 export declare function truncateMcpErrorText(s: string): string;
+/**
+ * Default per-call MCP tool timeout. The SDK's own default (60s) silently kills any long-running MCP tool
+ * with a -32001 and offers the deployment no knob; a very large default (matching the behavior of the
+ * reference agent client) lets the task-level budget/abort govern instead, while `MCP_TOOL_TIMEOUT` (ms)
+ * remains available to tighten it per deployment.
+ */
 export declare const MCP_TOOL_TIMEOUT_DEFAULT_MS = 100000000;
+/**
+ * The bounds EVERY `MCP_*` millisecond knob resolves into — CC 223-same (`MNs` @354067 and the idle leg
+ * `Pyd` @354076 both clamp into `[1000, 2147483647]`; the constants were already ported here, the clamp
+ * was not).
+ *
+ * The ceiling is not cosmetic: `setTimeout` stores its delay in a signed 32-bit field, so a larger value
+ * is silently rewritten to `1` — an operator WIDENING a bound past 24.85 days (the shape of "basically
+ * turn this watchdog off") gets the exact opposite: a bound that fires ~immediately on every call. The
+ * floor closes the other end of the same unit trap — a bare `30` is what someone thinking in seconds
+ * types, and a 30ms MCP bound is never anyone's intent.
+ */
 export declare const MCP_ENV_MS_MIN = 1000;
 export declare const MCP_ENV_MS_MAX = 2147483647;
+/** Test seam: the announcement de-dupes per process, so a test asserting the line must be able to clear
+ *  the ledger. Never called by production code. */
 export declare function __resetMcpEnvAnnouncements(): void;
+/** Resolve the per-call tool timeout in ms (env `MCP_TOOL_TIMEOUT`, else the large default). Exported for tests. */
 export declare function mcpToolTimeoutMs(): number;
+/**
+ * Resolve the TOTAL wall-clock ceiling for one tool call in ms (env `MCP_TOOL_TIMEOUT_TOTAL`, else the
+ * per-call timeout). The SDK's `resetTimeoutOnProgress` only re-arms the SDK's OWN per-call timer
+ * (`mcpToolTimeoutMs()` above — a different mechanism from {@link armMcpIdleWatchdog}'s idle watchdog
+ * below, despite the name-adjacent terms; disambiguated here on purpose, see that function's docstring
+ * for why sema needs both). It enforces a total bound ONLY when `maxTotalTimeout` is provided (protocol.js
+ * `_resetTimeout`), so without this a
+ * misbehaving/stuck server emitting periodic progress notifications could extend a call forever. Defaulting
+ * the ceiling to the per-call timeout means progress can keep an active call alive only within the same
+ * window the deployment already accepted; the resulting failure is the same -32001 timeout frame. Env
+ * parsing follows the `MCP_TOOL_TIMEOUT` discipline (unset/unparseable/non-positive → default). Exported
+ * for tests.
+ */
 export declare function mcpToolTotalTimeoutMs(perCallMs: number): number;
+/**
+ * RB-199 FO-1 (form-one audit, CC 2.1.220): a server that goes SILENT — alive, transport open, no error,
+ * no close, just never responds and never emits progress — has no bound tighter than the (deliberately
+ * enormous, ~27.8h-default) total ceiling above. CC bounds this with a SEPARATE idle watchdog distinct
+ * from its total ceiling (`j7u` @345484: stdio 30min / http-sse 5min).
+ *
+ * Narrower than the audit's original framing: a CLOSED transport is already handled correctly by the SDK
+ * itself — `Protocol._onclose` (shared/protocol.js) rejects every in-flight response handler immediately
+ * with `ConnectionClosed` the moment `onclose` fires, so this watchdog exists for the SILENT-but-open case
+ * only, not as a substitute for connection-close handling.
+ */
 export declare const MCP_IDLE_TIMEOUT_STDIO_DEFAULT_MS: number;
 export declare const MCP_IDLE_TIMEOUT_HTTP_DEFAULT_MS: number;
+/** Resolve the idle-watchdog bound in ms for a transport kind (env `MCP_IDLE_TIMEOUT_STDIO` /
+ *  `MCP_IDLE_TIMEOUT_HTTP`, else the CC-matched default). Exported for tests. */
 export declare function mcpIdleTimeoutMs(kind: "stdio" | "http"): number;
+/**
+ * Startup-phase (connect + initial listTools) timeout override in ms (env `MCP_TIMEOUT`); undefined keeps
+ * the SDK default. Startup deliberately stays bounded: a hung server at materialize time should fail open
+ * into a skipped-server warning quickly, not stall task preparation indefinitely.
+ */
 export declare function mcpStartupTimeoutMs(): number | undefined;
+/** The protocol-range condition name for a JSON-RPC error code, or `undefined` for every other code
+ *  (see {@link MCP_SPEC_ERROR_CODE_NAMES}). */
 export declare function describeMcpSpecErrorCode(code: unknown): string | undefined;
+/**
+ * RB-437-c — the SDK stamps `MCP error <code>: ` onto an McpError's message IN ITS CONSTRUCTOR, and it
+ * does so at BOTH ends of the wire: a server built on an MCP SDK throws an McpError, its already-stamped
+ * `.message` goes out as the JSON-RPC `error.message`, and the client constructs its own McpError over
+ * that string — so the failure reaches the model as `MCP error -32602: MCP error -32602: …`. Collapse a
+ * repeat of the SAME code (a leading stamp carrying a DIFFERENT code is server data, not a duplicate of
+ * ours, and is left alone). Exported for unit testing; not part of the package index.
+ */
 export declare function collapseMcpErrorPrefix(message: string): string;
+/** The first errno-shaped `code` on an error's cause chain. `fetch` reports every network failure as a
+ *  bare `TypeError: fetch failed` with the real cause nested underneath (and an AggregateError when a
+ *  host resolved to several addresses), so the code is never on the thrown error itself.
+ *  Exported for unit testing (RB-449 mcp-1); not part of the package index (src/index.ts re-exports are
+ *  explicit and do not name it — see the sibling `collapseMcpErrorPrefix`/`classifyDirReadInvalidParams`
+ *  comments for the same "exported for tests only" convention). */
 export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;
+/** What {@link describeHttpTransportFailure} could establish about a transport-level HTTP failure:
+ *  the condition to name in the model-facing copy, whether the request can be said NOT to have reached
+ *  the remote, and the HTTP status when the endpoint answered with one. */
 export interface HttpTransportFailure {
     condition: string;
+    /** `"no"` = provably never delivered (a connect-phase errno); `"unknown"` = the request may have run. */
     delivered: "no" | "unknown";
     httpStatus?: number;
 }
+/**
+ * RB-437-b — a streamable-HTTP failure that never became an MCP exchange at all: the POST failed at the
+ * network layer (endpoint gone / unresolvable), or the endpoint answered with something that is not an
+ * MCP response. The SDK surfaces the first as `fetch`'s bare `TypeError: fetch failed` and the second as
+ * a `StreamableHTTPError`; NEITHER carries the server name, the MCP context or an outcome — while the
+ * stdio path for the same event (the server went away) has all three. Returns the condition to name and
+ * whether the request can be said not to have reached the server, or `undefined` when the failure is not
+ * of this class (an McpError is an answer FROM the server: the exchange happened, so it is never one).
+ *
+ * Exported (not on the package index) for the A2A client leg, which faces the SAME `fetch` layer and owes
+ * the same outcome contract — one classifier, so the two protocols cannot drift on what "the request never
+ * reached them" means.
+ */
 export declare function describeHttpTransportFailure(err: unknown): HttpTransportFailure | undefined;
 export { normalizeNameSegment as normalizeMcpName, clampNameSegment } from "./protocol-naming.js";
 export * from "./image-downsample.js";
+/**
+ * design/116 W5-2 — compact, jq-friendly type signature for a `structuredContent` value, e.g.
+ * `{title: string, items: [{id: number}]}`. Port of CC 2.1.187 `inferCompactSchema` (services/mcp/client.ts,
+ * beside the structuredContent branch at client.ts:2676-2683): depth-2, first array element as the element
+ * type, ≤10 object entries then `, ...`.
+ */
 export declare function inferCompactSchema(value: unknown, depth?: number): string;
+/** The per-peer HTTP auth declaration every protocol spec carries in the same two fields — the static
+ *  headers the deployment configured, and the header name the per-task principal rides on (design/62).
+ *  Named rather than inlined because it is a cross-module signature: {@link McpServerSpec}'s http
+ *  transport and A2A's peer spec both satisfy it, and the resolver below serves both. */
 export interface ProtocolHttpAuth {
     headers?: Record<string, string>;
     principalHeader?: string;
 }
+/**
+ * Resolve the HTTP request headers for one remote PEER of `protocol`, injecting the per-task end-user
+ * principal (design/62). The principal is added **only** when the spec declares a `principalHeader` AND a
+ * `principal` is present; it is injected **last** so it overrides any same-named static header; an absent
+ * principal sends no such header (the remote must then default to deny/public, never admin). Pure +
+ * exported for testing and so a consumer can verify what its config sends.
+ *
+ * Shared across protocols (A2A reuses it verbatim), which is why the failure names its protocol from the
+ * ARGUMENT rather than from a hard-coded literal: a copy of this guard per protocol is exactly the
+ * "second mint" shape whose copies stop tracking each other. Callers must invoke it INSIDE their per-peer
+ * boundary — the throw is one peer's configuration defect, and the surrounding per-peer catch is what
+ * turns it into a skipped peer instead of a failed task.
+ */
 export declare function resolveProtocolHttpHeaders(protocol: ProtocolId, t: ProtocolHttpAuth, principal?: string): Record<string, string> | undefined;
 interface McpContentItem {
     type: string;
     text?: string;
     data?: string;
     mimeType?: string;
+    /** `resource_link` block: a pointer to a server resource. */
     uri?: string;
     name?: string;
     description?: string;
+    /** `resource` block: an embedded resource (text or binary). */
     resource?: {
         uri?: string;
         mimeType?: string;
@@ -105,6 +412,7 @@ interface McpContentItem {
     };
 }
 export declare function mapContent(content: Array<McpContentItem>, serverName?: string, imageResizer?: McpImageResizer): Promise<Array<TextContent | ImageContent>>;
+/** One tool's schema-normalization outcome (CC 220 `zyo` @336616-336654's return shape). */
 export type McpSchemaNormalizeResult = {
     outcome: "unchanged";
 } | {
@@ -116,15 +424,88 @@ export type McpSchemaNormalizeResult = {
     outcome: "drop";
     reason: string;
 };
+/**
+ * RB-199 FO-2 (form-one audit, CC 2.1.220 `zyo` @336616-336654): flatten a root-level `anyOf`/`oneOf`/
+ * `allOf` combinator into a plain `{type:"object", properties, required}` shape a provider's tool-schema
+ * validator accepts, INSTEAD of leaving `mcpToolSchemaProblem` below to drop the whole tool. Without this,
+ * a server advertising the common "zod union" combinator shape (structurally VALID JSON Schema — the
+ * existing gate's root-type/structural checks both pass it) gets forwarded as-is and a strict provider
+ * (Anthropic) 400s the ENTIRE model request at the wire — the exact failure `mcpToolSchemaProblem`'s own
+ * docstring promises to contain ("a single misconfigured server never bricks the whole task"). A schema
+ * with no top-level combinator key is passed through `{outcome:"unchanged"}` — the vast majority of tools
+ * never reach the union-handling code below at all (fail-open by construction, matching CC's own early exit).
+ * Properties are collected from the top-level `properties` FIRST (so a sibling `properties` block — legal
+ * alongside a combinator, and semantically load-bearing — is never shadowed by a same-named combinator-
+ * branch property), then from every combinator branch present, in declaration order; the FIRST property of
+ * a given name wins (matches CC's own `!(d in r)` guard) — differing branches disagreeing on the SAME
+ * property's shape is a real ambiguity CC accepts too, not a sema gap. `required` is unioned from the
+ * top-level `required` PLUS `allOf` branches ONLY (never `anyOf`/`oneOf` branches — those are alternatives;
+ * unioning their `required` would demand fields the caller may legitimately omit by picking a different
+ * branch, exactly the correctness bug CC's own asymmetry avoids). Any exception during the walk (a $ref
+ * cycle degenerate enough to defeat the local-only resolver, e.g.) is caught and mapped to `outcome:"drop"`
+ * — a normalizer crash is evidence the schema is pathological, not a reason to propagate an exception out
+ * of the per-tool intake loop into the per-SERVER catch (same isolation principle `mcpToolSchemaProblem`'s
+ * own docstring already states for structural validation).
+ */
 export declare function normalizeMcpToolSchema(schema: unknown): McpSchemaNormalizeResult;
+/**
+ * [cc216] Deterministic intake gate for a server-advertised tool `inputSchema` — returns a
+ * CORE-authored reason string when the schema would be rejected at the provider wire, else
+ * `undefined` (tool is kept). Deliberately CONSERVATIVE (fail-open): only shapes that are
+ * *structurally* unusable are dropped — anything a provider might accept rides through. An ABSENT
+ * schema is fine (intake defaults it to `{type:"object"}` below). CC 2.1.216 gates the same prune
+ * per-server via remote config (its rollout mechanism, not the mechanism itself); sema's gate is
+ * the deterministic predicate alone. RB-199 FO-2: run {@link normalizeMcpToolSchema} on the schema
+ * FIRST — a root-level anyOf/oneOf/allOf reaching this gate unflattened is exactly the shape this
+ * gate's own docstring promise ("a single misconfigured server never bricks the whole task") existed
+ * to catch, and this gate alone does not catch it (no type key ⇒ passes the root-type check; the
+ * combinator's own structure is legal JSON Schema ⇒ passes validateJsonSchemaShape too).
+ */
 export declare function mcpToolSchemaProblem(schema: unknown): string | undefined;
 export declare function materializeMcpTools(specs: McpServerSpec[], principal?: string, onElicit?: OnElicit, imageResizer?: McpImageResizer): Promise<MaterializedMcp>;
+/**
+ * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.
+ * Unlike server hints, the caller may RAISE or LOWER any axis: `effect` sets the repeat-safety class (lower to
+ * `read`/`idempotent` or raise to `write`); `egress: false` / `irreversibility: "never"` REMOVE a server-added
+ * tighten the caller knows is wrong. Returns `undefined` when nothing remains set.
+ */
+/** Exported for tests — the override algebra above is a contract face (negatives must survive). */
 export declare function applyCallerAxisOverride(name: string, hint: McpToolAxis | undefined, override: {
     effect?: ToolEffect;
     egress?: boolean;
     irreversibility?: "always" | "never";
 } | undefined): McpToolAxis | undefined;
+/** Read a first-page `-32602` message as either meaning (see {@link DIR_READ_NOT_A_DIRECTORY_RE}). Exported
+ *  for the discrimination nails; the message is SERVER-authored and is only ever classified here, never
+ *  trusted as instructions. */
 export declare function classifyDirReadInvalidParams(message: string): "not_found" | "not_directory";
+/**
+ * RB-408 G12 — `tools/call` result parse that accepts the MCP `2026-07-28` widening of
+ * `structuredContent` from "a JSON object" to ANY JSON value (the same revision that relaxes
+ * `inputSchema`/`outputSchema` to the full JSON Schema 2020-12 keyword set).
+ *
+ * SDK 1.29's `CallToolResultSchema` still types the field as a record, so a spec-legal array / string /
+ * number / boolean / null fails validation for the WHOLE result — and the failure takes the `content`
+ * blocks down with it: a server returning perfectly usable text plus a scalar `structuredContent`
+ * produced nothing but `Invalid tools/call result: expected record, received number`. That is a silent
+ * capability loss dressed as a protocol error, and it gets WORSE as servers adopt the revision.
+ *
+ * The widening is deliberately surgical: `structuredContent` is lifted out, the SDK's own strict schema
+ * runs over the remainder (so content-block validation, the `content` default and the loose passthrough
+ * of unknown top-level keys are byte-for-byte what they were), and the lifted value is re-attached
+ * VERBATIM — same reference, no rebuild. An object-valued `structuredContent` therefore behaves exactly
+ * as before, and a malformed `content` array is still rejected: this must not become a validation bypass.
+ * Same duck-typing posture as {@link LenientListToolsResultSchema} (no direct `zod` dependency — the SDK's
+ * `zod-compat` shim calls `.safeParse(data)` on any object lacking a Zod-4 `_zod` marker).
+ *
+ * RESIDUAL, SDK-side and deliberately not widened here: `Client.callTool` guards its `outputSchema`
+ * validation with a TRUTHINESS test on `result.structuredContent`, so a tool that declares an
+ * `outputSchema` and returns a falsy scalar (`0`, `""`, `false`, `null`) is still rejected by the SDK with
+ * "has an output schema but did not return structured content". That path is LOUD (never a silent drop),
+ * is bounded to outputSchema-declaring tools, and widening it means replacing `callTool` itself — which
+ * would mean re-implementing the two guards it exists for (the output validator and the
+ * `taskSupport:"required"` refusal, both keyed off SDK-private caches).
+ */
 export declare function parseCallToolResultLenient(data: unknown): {
     success: true;
     data: unknown;

package/dist/core/media-byte-cap.d.ts

@@ -1,11 +1,32 @@
 import type { AgentMessage } from "../internal/harness-types.js";
+/**
+ * Aggregate MEDIA (image) byte budget — the multimodal sibling of {@link AGGREGATE_TOOL_RESULT_BUDGET_CHARS}
+ * (which only counts TEXT, design/64 §17.2). batch-C added image reads (`Read` → `ImageContent`); each is bounded
+ * per-image (`MAX_IMAGE_READ_BYTES`), but N images accumulate ACROSS turns in the context and would otherwise grow
+ * the request unboundedly (a real gap — CC 2.1.196 added the same cap, `tengu_media_byte_cap`, validating it).
+ *
+ * This caps the SUM of inline image bytes across the whole message list: while over budget, the OLDEST images are
+ * stripped (replaced with a short text marker) until it fits — recent media (most relevant) is kept. Like the text
+ * budget it is a REQUEST-ONLY, NON-DESTRUCTIVE transform (returns a new array; the durable session keeps the full
+ * image, and the model can re-`Read` the file if it still needs it) applied in the `harness.on("context")` hook,
+ * and DETERMINISTIC (same messages + limit → same strip set → byte-identical request → prompt-cache safe).
+ */
+/** Default aggregate inline-media budget (bytes). Generous — only the pathological "N parallel huge image reads"
+ *  case strips. Bounds the request while leaving normal multimodal use untouched. Overridable per-deployment. */
 export declare const AGGREGATE_MEDIA_BUDGET_BYTES: number;
+/** Telemetry for one strip pass (mirrors CC's `tengu_media_byte_cap_stripped` fields). */
 export interface MediaStripInfo {
     totalBytes: number;
     limitBytes: number;
     removedCount: number;
     removedBytes: number;
 }
+/**
+ * Cap the aggregate inline-image bytes across `messages` to `limitBytes`, stripping OLDEST images first. Returns the
+ * SAME array when already within budget or the limit is non-positive/non-finite (no allocation, no-op). Otherwise a
+ * shallow-cloned array with the stripped messages replaced (originals untouched). `onStripped` fires once if anything
+ * was removed.
+ */
 export declare function capAggregateMediaBytes(messages: AgentMessage[], opts: {
     limitBytes: number;
     onStripped?: (info: MediaStripInfo) => void;