@sema-agent/core 7.5.2 → 7.6.1

package/dist/core/mcp-failure.d.ts

@@ -0,0 +1,142 @@
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+/**
+ * The closed set of failure classes ({@link McpFailure.kind}):
+ *  · `connect_refused`   — a connect-phase errno (ECONNREFUSED / ENOTFOUND / EAI_AGAIN / EHOSTUNREACH /
+ *                          ENETUNREACH / UND_ERR_CONNECT_TIMEOUT): the request provably never left;
+ *  · `connection_failed` — any other errno / undici code on the cause chain (a reset or a timeout
+ *                          mid-exchange): the request may have run;
+ *  · `connection_closed` — the SDK reported the transport closed (`McpError` `ConnectionClosed`): in
+ *                          flight the fate is unknowable, and for a server already known dead the
+ *                          request was never attempted — the two are told apart by `delivered`;
+ *  · `http_status`       — the HTTP endpoint answered with a status instead of an MCP response
+ *                          (`httpStatus` carries the number: 401/403 = re-authorize, 5xx = down);
+ *  · `not_mcp_response`  — the HTTP endpoint answered something that is not an MCP payload and no status;
+ *  · `spawn_failed`      — a stdio server process could not be started (a missing/unexecutable command);
+ *  · `timeout`           — the request timed out (the SDK's per-call timer, the total ceiling, or the
+ *                          idle watchdog — `details` names which);
+ *  · `protocol`          — the server ANSWERED with an MCP/JSON-RPC error (a version mismatch, a rejected
+ *                          capability, an ordinary `-32603`): the exchange happened;
+ *  · `invalid_config`    — the declaration itself could not be dialed (a malformed `url`): a fault to
+ *                          fix in the spec, never an outage to wait out;
+ *  · `unknown`           — the thrown value carried no structure this table reads.
+ */
+export declare const MCP_FAILURE_KINDS: readonly ["connect_refused", "connection_failed", "connection_closed", "http_status", "not_mcp_response", "spawn_failed", "timeout", "protocol", "invalid_config", "unknown"];
+export type McpFailureKind = (typeof MCP_FAILURE_KINDS)[number];
+/** The closed set of delivery verdicts ({@link McpFailure.delivered}). */
+export declare const MCP_DELIVERY_VERDICTS: readonly ["yes", "no", "unknown"];
+export type McpDelivered = (typeof MCP_DELIVERY_VERDICTS)[number];
+/**
+ * The delivery verdict each KIND carries when the failure happened on an established connection
+ * (`phase: "request"`) — the disposition table over {@link MCP_FAILURE_KINDS}. The classifier's rows
+ * read the thrown value's STRUCTURE and mint a class; what that class means for delivery is decided
+ * here, once, so no two rows can disagree about the same word and a new kind cannot arrive without
+ * saying what it means for delivery (the fence below reds `tsc` with the missing word spelled out).
+ */
+export declare const DELIVERED_BY_KIND: {
+    readonly connect_refused: "no";
+    readonly connection_failed: "unknown";
+    readonly connection_closed: "unknown";
+    readonly http_status: "unknown";
+    readonly not_mcp_response: "unknown";
+    readonly spawn_failed: "no";
+    readonly timeout: "unknown";
+    readonly protocol: "yes";
+    readonly invalid_config: "no";
+    readonly unknown: "unknown";
+};
+/** The fence over the delivery table: `never` while every kind has a verdict. */
+export type DeliveryTableCoversEveryMcpFailureKind = AssertAllKeysHandled<Exclude<McpFailureKind, keyof typeof DELIVERED_BY_KIND>>;
+/** Where the failure was judged: at the dial (connect + initial listing), where an errno on a stdio
+ *  transport is the child process failing to spawn, or on a request over an established connection. */
+export type McpFailureSite = {
+    phase: "connect";
+    transport: "stdio" | "http" | undefined;
+} | {
+    phase: "request";
+};
+/**
+ * The one MCP failure record. Both fields are always present; `httpStatus` rides only with
+ * `kind === "http_status"`.
+ */
+export interface McpFailure {
+    /**
+     * @contract mcp.failure.kind — the failure's CLASS, one of {@link MCP_FAILURE_KINDS}, decided by
+     * {@link classifyMcpFailure} from the thrown value's structure alone (never from its message). It is
+     * the SAME word on every face: the per-server status's and the wiring manifest's `errorCode`, the
+     * thrown request error's `details.code`, and the `tool_end` frame's `errorCode`. Closed: a consumer
+     * switching on it is complete; a new class is a new word for consumers, never a re-meaning of one.
+     */
+    kind: McpFailureKind;
+    /**
+     * @contract mcp.failure.delivered — whether the request REACHED the server, as a first-class fact
+     * beside the class: `"yes"` = the server answered (a `protocol` rejection proves the exchange
+     * happened); `"no"` = provably never sent (a connect-phase errno, a spawn failure, a malformed
+     * declaration, a server already known dead — safe to retry or abandon, nothing executed); `"unknown"`
+     * = the client stopped waiting or lost the pipe mid-exchange (a timeout, an in-flight close, a reset,
+     * an HTTP status from a gateway in front of the server) — the request MAY have executed, so a
+     * write-capable tool's side effects must be verified before a retry. Two failures with the same
+     * `kind` can differ here (`connection_closed` in flight vs. against a dead server), which is why the
+     * verdict is its own field and not folded into the class. It is a function of the class and the SITE,
+     * never of the row that matched: {@link DELIVERED_BY_KIND} says what a class means on an established
+     * connection, and at the dial the verdict is `"no"` for every class but the two minted from an answer
+     * ({@link CONNECT_KEEPS_THE_TABLE_VERDICT}) — a connect failure is a server whose tools never mounted,
+     * so no TOOL CALL of the caller's was dispatched, let alone executed. Read
+     * {@link CONNECT_KEEPS_THE_TABLE_VERDICT} for what a dial's `"no"` does not promise (an elicitation
+     * answered during the dial has already crossed the connection) and for the facts that would let the
+     * rule be narrower.
+     */
+    delivered: McpDelivered;
+    /** The HTTP status the endpoint answered with; present iff `kind === "http_status"`. */
+    httpStatus?: number;
+}
+/**
+ * The first errno-shaped / undici-shaped `code` on an error's cause chain (`E[A-Z_]+`, `UND_ERR_*`,
+ * Node's `ERR_*`). `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. The E-prefixed alternative allows `_`: Node's
+ * DNS-temporary-failure errno is literally `EAI_AGAIN`.
+ */
+export declare function networkErrorCode(err: unknown, depth?: number): string | undefined;
+/** What a row reads OFF the thrown value: the failure's class, and the status the `http_status` class
+ *  carries. A row does NOT write the delivery verdict — that follows from the kind and the SITE, in
+ *  one place ({@link DELIVERED_BY_KIND} + {@link classifyMcpFailure}), so a row cannot spell it wrong. */
+export type McpFailureClass = {
+    kind: McpFailureKind;
+    httpStatus?: number;
+};
+/** One row of the classifier: `when` reads structure only; `reads` names the class it saw. */
+export interface McpFailureRule {
+    /** The row's name, for the discrimination pins (one pin per row) and for a reader of a verdict. */
+    readonly name: string;
+    readonly when: (err: unknown, at: McpFailureSite) => boolean;
+    readonly reads: (err: unknown) => McpFailureClass;
+}
+/**
+ * The ORDERED classifier. First match wins; the final row matches everything. The order is part of
+ * the contract — the SDK's typed errors go first because they are an answer FROM the exchange (an
+ * McpError is never a transport failure, whatever its text says), then the HTTP transport's typed
+ * error, then the cause-chain codes from most specific (a configuration fault, a spawn) to least
+ * (a connect-phase errno, any other network code).
+ */
+export declare const FAILURE_CLASSIFIER: ReadonlyArray<McpFailureRule>;
+/**
+ * Classify one MCP failure into {@link McpFailure}: the CLASS comes from the first matching row of
+ * {@link FAILURE_CLASSIFIER} (structure only), the VERDICT from {@link DELIVERED_BY_KIND} and the site
+ * — one predicate for the dial ({@link CONNECT_KEEPS_THE_TABLE_VERDICT}), never a per-row spelling.
+ * Total: every input maps to a record.
+ */
+export declare function classifyMcpFailure(err: unknown, at: McpFailureSite): McpFailure;
+/**
+ * What a transport-level HTTP failure can be said to be, in words for a model-facing line: the
+ * condition to name, and the delivery verdict. `undefined` for every failure that is NOT of the HTTP
+ * transport family (an McpError is an answer FROM the server; a bare error with no structure is
+ * `unknown` and gets no transport story). Shared with 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 interface HttpTransportFailure {
+    condition: string;
+    delivered: McpDelivered;
+    httpStatus?: number;
+}
+export declare function describeHttpTransportFailure(err: unknown): HttpTransportFailure | undefined;

package/dist/core/mcp-failure.js

@@ -0,0 +1,145 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export const MCP_FAILURE_KINDS = [
+    "connect_refused",
+    "connection_failed",
+    "connection_closed",
+    "http_status",
+    "not_mcp_response",
+    "spawn_failed",
+    "timeout",
+    "protocol",
+    "invalid_config",
+    "unknown",
+];
+export const MCP_DELIVERY_VERDICTS = ["yes", "no", "unknown"];
+export const DELIVERED_BY_KIND = {
+    connect_refused: "no",
+    connection_failed: "unknown",
+    connection_closed: "unknown",
+    http_status: "unknown",
+    not_mcp_response: "unknown",
+    spawn_failed: "no",
+    timeout: "unknown",
+    protocol: "yes",
+    invalid_config: "no",
+    unknown: "unknown",
+};
+const CONNECT_KEEPS_THE_TABLE_VERDICT = new Set(["protocol", "http_status"]);
+const NETWORK_CODES_NEVER_DELIVERED = new Set([
+    "ECONNREFUSED",
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "UND_ERR_CONNECT_TIMEOUT",
+]);
+export function networkErrorCode(err, depth = 0) {
+    if (depth > 5 || !(err instanceof Error))
+        return undefined;
+    const code = err.code;
+    if (typeof code === "string" && /^(?:E[A-Z_]+|UND_ERR_[A-Z_]+)$/.test(code))
+        return code;
+    if (err instanceof AggregateError) {
+        for (const inner of err.errors) {
+            const found = networkErrorCode(inner, depth + 1);
+            if (found !== undefined)
+                return found;
+        }
+    }
+    return networkErrorCode(err.cause, depth + 1);
+}
+const isNodeErrCode = (code) => code.startsWith("ERR_");
+export const FAILURE_CLASSIFIER = [
+    {
+        name: "sdk connection closed",
+        when: (err) => err instanceof McpError && err.code === ErrorCode.ConnectionClosed,
+        reads: () => ({ kind: "connection_closed" }),
+    },
+    {
+        name: "sdk request timeout",
+        when: (err) => err instanceof McpError && err.code === ErrorCode.RequestTimeout,
+        reads: () => ({ kind: "timeout" }),
+    },
+    {
+        name: "server answered with a protocol error",
+        when: (err) => err instanceof McpError,
+        reads: () => ({ kind: "protocol" }),
+    },
+    {
+        name: "http endpoint answered a status",
+        when: (err) => err instanceof StreamableHTTPError && typeof err.code === "number" && err.code > 0,
+        reads: (err) => ({ kind: "http_status", httpStatus: err.code }),
+    },
+    {
+        name: "http endpoint answered a non-mcp payload",
+        when: (err) => err instanceof StreamableHTTPError,
+        reads: () => ({ kind: "not_mcp_response" }),
+    },
+    {
+        name: "malformed declaration",
+        when: (err, at) => at.phase === "connect" && err instanceof Error && err.code === "ERR_INVALID_URL",
+        reads: () => ({ kind: "invalid_config" }),
+    },
+    {
+        name: "node error code, not a network errno",
+        when: (err) => {
+            const code = networkErrorCode(err);
+            return code !== undefined && isNodeErrCode(code);
+        },
+        reads: () => ({ kind: "unknown" }),
+    },
+    {
+        name: "stdio spawn failed",
+        when: (err, at) => at.phase === "connect" && at.transport === "stdio" && networkErrorCode(err) !== undefined,
+        reads: () => ({ kind: "spawn_failed" }),
+    },
+    {
+        name: "connect-phase errno",
+        when: (err) => {
+            const code = networkErrorCode(err);
+            return code !== undefined && NETWORK_CODES_NEVER_DELIVERED.has(code);
+        },
+        reads: () => ({ kind: "connect_refused" }),
+    },
+    {
+        name: "network errno past the connect phase",
+        when: (err) => networkErrorCode(err) !== undefined,
+        reads: () => ({ kind: "connection_failed" }),
+    },
+    {
+        name: "no structure",
+        when: () => true,
+        reads: () => ({ kind: "unknown" }),
+    },
+];
+export function classifyMcpFailure(err, at) {
+    for (const rule of FAILURE_CLASSIFIER) {
+        if (!rule.when(err, at))
+            continue;
+        const read = rule.reads(err);
+        const dialled = at.phase === "connect" && !CONNECT_KEEPS_THE_TABLE_VERDICT.has(read.kind);
+        return { ...read, delivered: dialled ? "no" : DELIVERED_BY_KIND[read.kind] };
+    }
+    return { kind: "unknown", delivered: "unknown" };
+}
+export function describeHttpTransportFailure(err) {
+    const f = classifyMcpFailure(err, { phase: "request" });
+    switch (f.kind) {
+        case "http_status":
+            return { condition: `its HTTP endpoint answered ${f.httpStatus} instead of an MCP response`, delivered: f.delivered, httpStatus: f.httpStatus };
+        case "not_mcp_response":
+            return { condition: "its HTTP endpoint answered something that is not an MCP response", delivered: f.delivered };
+        case "connect_refused":
+            return { condition: `its HTTP endpoint could not be reached (${networkErrorCode(err)})`, delivered: f.delivered };
+        case "connection_failed":
+            return { condition: `the connection to its HTTP endpoint failed (${networkErrorCode(err)})`, delivered: f.delivered };
+        case "connection_closed":
+        case "spawn_failed":
+        case "timeout":
+        case "protocol":
+        case "invalid_config":
+        case "unknown":
+            return undefined;
+    }
+}

package/dist/core/mcp-server-spec.d.ts

@@ -0,0 +1,217 @@
+/**
+ * How a deployment DECLARES an external tool server and what an elicitation round-trip looks like:
+ * `McpServerSpec` (stdio / HTTP / in-process MCP), `A2aServerSpec` (the agent-to-agent peer) and the
+ * elicit pair (`McpElicitRequest` / `McpElicitResponse` / `OnElicit`). Named `mcp-server-spec.ts`, not
+ * `mcp.ts`: `src/core/mcp.ts` is the CLIENT, and two files a letter apart would be a worse hazard than
+ * a longer name. Layer 0 vocabulary; `types.ts` re-exports every name below.
+ */
+import type { ToolContentOrigin, ToolEffect } from "./tool-spec.js";
+/** Definition of an MCP server to connect to for the duration of one task, then discard. */
+export interface McpServerSpec {
+    /** Stable name; tool names are namespaced as `<name>__<tool>` to avoid collisions. */
+    name: string;
+    /**
+     * Where this declaration CAME FROM, in the declaring side's own words (a shell's `plugin` / `user` /
+     * `project` / `local` config tiers, or anything else the deployment finds useful). Core reads
+     * nothing off it: it is echoed verbatim (single-line, length-bounded) onto the wiring manifest's
+     * per-server read face (`WiringManifest.mcp[].source`) so a consumer can group servers by their
+     * declaring tier without keeping a side table keyed on names. Optional; absent stays absent.
+     */
+    source?: string;
+    transport: {
+        kind: "stdio";
+        command: string;
+        args?: string[];
+        env?: Record<string, string>;
+    } | {
+        kind: "http";
+        url: string;
+        /** Static headers sent on every request (e.g. an auth bearer for the MCP server itself). */
+        headers?: Record<string, string>;
+        /**
+         * Per-task **end-user principal** header (design/62). When set, the Runner injects the running task's
+         * authenticated {@link TaskSpec.principal} as this header (e.g. `"X-Agent-Principal"`) on every call to
+         * this server's tools, so the MCP server can enforce per-user RBAC. Absent {@link TaskSpec.principal}
+         * ⇒ the header is **not** sent (the MCP server must default to deny/public, never admin). Overrides any
+         * same-named static `headers` entry. The principal is Runner-held and the model/worker can neither read
+         * nor set it (it is not a tool argument) — see {@link TaskSpec.principal}.
+         */
+        principalHeader?: string;
+    };
+    /** Optional allowlist of tool names to expose (others are dropped). ORTHOGONAL to
+     *  {@link contentOrigin} and usefully paired with it (design/378 §2): the class declaration follows
+     *  the server's roster, so a high-assurance deployment that wants a CLOSED tool set writes both —
+     *  a tool a later refresh adds then lands outside this list and is simply not mounted. Existing
+     *  semantics, no new mechanism; the refresh receipt still names every added tool either way. */
+    allowTools?: string[];
+    /**
+     * design/99 §E23 — opt in to INBOUND elicitation for THIS server: when `true` AND a {@link RunnerDeps.onElicit}
+     * seam is wired, core advertises the `elicitation` capability to this server and registers a handler, so the
+     * server may send an `elicitation/create` request to ask the END USER for input mid-tool-call. **Default OFF
+     * (fail-closed)**: never advertise unless explicitly wired, so a untrusted/over-eager server cannot pull a human
+     * into the loop. v1 is LIVE-ONLY — `onElicit` answers synchronously on the open connection (no durable
+     * suspend; a durable/cross-replica elicitation needs the deferred E22 longer-lived connection).
+     */
+    elicitation?: boolean;
+    /**
+     * Caller-side per-tool safety-axis overrides, keyed by the server's REMOTE (un-namespaced) tool name. The
+     * CALLER is the trust root: unlike a server's self-declared annotations (which may only TIGHTEN), a caller
+     * override is AUTHORITATIVE and may LOWER an effect (vouch a tool is `read`/`idempotent`) as well as raise it
+     * (`egress` / irreversible). This is the ONLY trusted way to drop an MCP tool below the fail-closed `write`
+     * default (design F). Folds over the server hints in prepare-task (caller > server hint > fail-closed write).
+     *
+     * A DIFFERENT AXIS from {@link contentOrigin}: this one is about what a call DOES (repeat-safety,
+     * blast radius, reversibility — it feeds the approval gate); the content class is about what a call
+     * BRINGS BACK (memory-write governance, no gate/policy/roster effect). Neither implies the other —
+     * a read-only tool can return third-party text, and a deployment's own writer brings back nothing
+     * external — so vouching on one axis never quietly vouches on the other.
+     */
+    toolAxes?: Record<string, {
+        effect?: ToolEffect;
+        egress?: boolean;
+        irreversibility?: "always" | "never";
+    }>;
+    /**
+     * design/378 — declare {@link ToolSpec.contentOrigin} on behalf of THIS SERVER'S ENTIRE TOOL SET
+     * (tools a mid-task refresh adds included), with the same authority and the same responsibility a
+     * directly-mounted host tool's own declaration carries.
+     *
+     * WHY THE SEAT EXISTS. Without it the class keys on the MOUNT SHAPE rather than on lineage: a tool
+     * the deployment wrote and runs itself is structurally `"external"` the moment it arrives over the
+     * MCP protocol namespace, so every call marks the session's memory externally exposed. The
+     * per-name channels cannot express the fact either — {@link import("./memory.js").MemorySpecInput.trustedTools}
+     * is a per-REQUEST allowlist keyed on the MINTED name (the host would have to predict the charset
+     * normalization) whose own definition is "the exception channel for UNDECLARED tools", and it says
+     * nothing about tools the server adds later.
+     *
+     * THIS IS A TRUST DECLARATION, not a routing hint. Use it only for servers inside the deployment's
+     * trust boundary — a process, socket or service the deployment itself runs. Declaring a THIRD-PARTY
+     * server means treating its output as content the deployment wrote: the class names are
+     * BOUNDARY-relative, never topological, so neither the transport kind nor the address is evidence
+     * of lineage (a stdio child can be an untrusted package; a loopback URL can be your own service) and
+     * core deliberately does not gate on either. The declaration covers THE PEER THIS ENTRY CONNECTS TO
+     * — authenticating that peer (socket permissions, credentials) is the host's mounting duty.
+     *
+     * SEMANTICS. `"local"` ⇒ invocations no longer mark this session's memory; `"execution"` ⇒ the same,
+     * except that {@link import("./memory.js").MemorySpecInput.execIsExternalContent} can still upgrade
+     * the class for a strict deployment (which is why this seat takes the three-value vocabulary and not
+     * a single "mine" flag — an execution-shaped tool mounted over MCP must stay inside that knob's
+     * reach); `"external"` is an explicit PIN, and pins are not no-ops — a declaration beats the
+     * `trustedTools` allowlist, so writing it forecloses the per-name exemption for this server's tools.
+     * ABSENT ⇒ the pre-378 behavior byte for byte: the protocol namespace classifies the tools
+     * `"external"` (fail-closed). A value outside the vocabulary is refused at the preparation door
+     * (`config.mcp_content_class`), never folded to a class.
+     *
+     * COVERAGE, stated honestly: the class rides this server's own mounted tools. The cross-server
+     * resource faces (ListMcpResourcesTool / ReadMcpResourceTool / ReadMcpResourceDirTool) aggregate
+     * over every connected server in one call, so they stay `"external"` and still mark — over-marking,
+     * the safe direction. A delegated child's pool is a separate static declaration surface
+     * ({@link ToolSpec.agentToolPool} entries carry their own `contentOrigin`): a deployment handing
+     * this server's tools to children mirrors the value there, and not mirroring it over-marks.
+     *
+     * TRUST SOURCE — a DEPLOYMENT-plane key. It redefines where the trust boundary runs, which puts it
+     * on the same authority plane as {@link RunnerDeps} wiring, not on the request plane. Core sees one
+     * `TaskSpec` and cannot tell a deployment-baseline entry from one a request supplied, so any
+     * assembly layer that accepts REQUEST-side MCP entries must reject or strip this key from them:
+     * "allowed to mount a server" is not "allowed to redefine the deployment's trust boundary", and a
+     * caller-supplied `"local"` would otherwise be self-authorization around the session mark. A
+     * single-tenant superuser surface (a host reading its own `--mcp-config` file) IS the deployment
+     * plane and needs no such gate.
+     */
+    contentOrigin?: ToolContentOrigin;
+}
+/**
+ * Definition of one A2A (agent-to-agent protocol) PEER to talk to for the duration of one task.
+ *
+ * The peer is a remote AGENT, not a data source: it acts on its own side. That single fact sets the
+ * defaults — every skill this peer advertises mounts with `egress: true` and `effect: "write"` (ruled
+ * 2026-08-03), so it registers the approval gate and is never auto-allowed on a no-policy deployment,
+ * and its replies reach the model inside an untrusted-data fence. {@link toolAxes} is the only trusted
+ * way down from those defaults (design F: the caller is the trust root).
+ *
+ * Skills mount as `a2a__<peer>__<skill>` (the protocol table's second namespace).
+ */
+export interface A2aServerSpec {
+    /** Stable local name for this peer; it becomes the namespace segment of every mounted tool name. */
+    name: string;
+    /** The peer's service URL. Doubles as the origin the well-known agent-card paths resolve against, and
+     *  as the JSON-RPC endpoint when the card does not name a different one. */
+    url: string;
+    /** Explicit agent-card location, when the peer does not publish at a well-known path. Set ⇒ it is used
+     *  ALONE (no well-known probing behind the operator's back). */
+    cardUrl?: string;
+    /** Static headers sent on every request to this peer (e.g. an auth bearer). */
+    headers?: Record<string, string>;
+    /**
+     * Per-task **end-user principal** header (design/62), same contract as the MCP side: when set, the
+     * Runner injects the running task's authenticated {@link TaskSpec.principal} under this header name on
+     * every call to this peer, so the peer can enforce per-user authorization. Absent principal ⇒ the
+     * header is not sent (the peer must then default to deny/public, never admin). Overrides any same-named
+     * static entry in {@link headers}. The principal is Runner-held: the model can neither read nor set it.
+     */
+    principalHeader?: string;
+    /** Optional allowlist of skill ids to expose (others are not mounted). */
+    allowSkills?: string[];
+    /**
+     * Caller-side per-skill safety-axis overrides, keyed by the peer's REMOTE skill id. The CALLER is the
+     * trust root, so this may LOWER the fail-closed default (`egress:true` + `effect:"write"`) as well as
+     * raise it — e.g. `{ egress: false, effect: "read" }` vouches that a skill only reads. Note that
+     * lowering `effect` WITHOUT clearing `egress` is a contradiction prepare-task refuses by design (an
+     * external write must be repeat-unsafe).
+     */
+    toolAxes?: Record<string, {
+        effect?: ToolEffect;
+        egress?: boolean;
+        irreversibility?: "always" | "never";
+    }>;
+}
+/**
+ * design/99 §E23 — an INBOUND MCP elicitation request (a connected server asking the END USER for input
+ * mid-tool-call). Handed to the deployment's {@link RunnerDeps.onElicit} seam. **UNTRUSTED**: `message` /
+ * `requestedSchema` / `url` are SERVER-controlled — core never interprets `requestedSchema`; a consumer that
+ * shows `message` to a human MUST fence it (`delimitUntrusted`).
+ */
+export interface McpElicitRequest {
+    /** The {@link McpServerSpec.name} of the server that issued the request. */
+    server: string;
+    /** The server's human-facing prompt (UNTRUSTED — fence before display). */
+    message: string;
+    /** Form mode: the server's requested input schema (a flat object of scalars). OPAQUE to core. */
+    requestedSchema?: unknown;
+    /**
+     * URL mode: a server-controlled URL the user is asked to visit (UNTRUSTED — a phishing/social-engineering
+     * surface; a consumer MUST scrutinize/fence it before showing it). **Inactive**: core advertises FORM mode
+     * only, so the SDK rejects url-mode requests before this seam — the field is never populated today.
+     *
+     * Where url mode is heading (MCP revision `2026-07-28`), because the earlier note here ("reserved for a
+     * future url-mode opt-in") pointed at machinery that no longer exists: the revision REMOVES the
+     * `2025-11-25` url-mode correlator (`elicitationId`) and the `notifications/elicitation/complete`
+     * notification that went with it. A url interaction is instead carried by the revision's multi-round-trip
+     * request flow — the server answers with an input-required result, the client RETRIES the original
+     * request, and the server correlates across retries through its OWN opaque request state rather than a
+     * client-visible id. The one thing both shapes agree on is the server-supplied URL itself, which is what
+     * this field holds. So the field stays; anything that would have hung off the removed correlator must not
+     * be added here without re-reading the protocol revision core actually speaks.
+     */
+    url?: string;
+    /** The running task's authenticated end-user (design/62), if any — for routing the prompt to the right human. */
+    principal?: string;
+}
+/** design/99 §E23 — the deployment's answer to an {@link McpElicitRequest} (returned to the MCP server). */
+export interface McpElicitResponse {
+    action: "accept" | "decline" | "cancel";
+    /** Submitted values (accept only); core passes them through opaquely, never validated against the schema. */
+    content?: Record<string, string | number | boolean | string[]>;
+}
+/**
+ * design/99 §E23 — the LIVE-ONLY inbound-elicitation seam. A deployment provides it (e.g. the sema shell
+ * prompts the user at the terminal) and returns the answer SYNCHRONOUSLY; core replies to the server on the
+ * still-open connection. Absent ⇒ no server is advertised the elicitation capability (fail-closed). Not a
+ * durable suspend — a crash/replica-change loses an in-flight elicitation (acceptable for an interactive shell).
+ *
+ * 🔴 THROTTLING IS THE DEPLOYMENT'S JOB: once a server is opted in, it may issue elicitations at any frequency
+ * (one per tool call, or many) — core imposes NO rate/count limit (an elicitation is not a tool call and does
+ * not ride the policy gate). `onElicit` is the choke point: throttle, aggregate, or `decline`/`cancel` an
+ * over-eager or untrusted server here (the request's `AbortSignal` is forwarded so a deadline can cancel it).
+ */
+export type OnElicit = (req: McpElicitRequest, signal?: AbortSignal) => Promise<McpElicitResponse>;

package/dist/core/mcp-server-spec.js

@@ -0,0 +1 @@
+export {};

package/dist/core/mcp.d.ts

@@ -1,4 +1,5 @@
 import { type ProtocolId } from "./protocol-table.js";
+import { type McpDelivered, type McpFailureKind } from "./mcp-failure.js";
 import type { AgentTool } from "../internal/harness-types.js";
 import type { ImageContent, TextContent } from "../internal/llm.js";
 import { type McpImageResizer } from "./image-downsample.js";
@@ -258,11 +259,13 @@ export interface McpServerStatus {
     };
     toolNames?: string[];
     error?: string;
-    /** Present iff `status === "failed"` — the failure's CLASS, judged from the thrown error object at
-     *  connect time ({@link mcpFailureCodeOf}; the closed set is {@link MCP_FAILURE_CODES} plus the
-     *  `http_<status>` form). A consumer keys an action off THIS (a `http_401` is a re-authorization
-     *  door, a `spawn_failed` is a missing binary) instead of parsing the neutralized `error` text. */
-    errorCode?: McpFailureCode;
+    /** Present iff `status === "failed"` — the connect-time failure record, spread flat: {@link McpFailure.kind}
+     *  as `errorCode`, {@link McpFailure.delivered} as `delivered`, and `httpStatus` when the kind is
+     *  `http_status`. A consumer keys an action off THESE (a `http_status` 401 is a re-authorization door,
+     *  a `spawn_failed` is a missing binary) instead of parsing the neutralized `error` text. */
+    errorCode?: McpFailureKind;
+    delivered?: McpDelivered;
+    httpStatus?: number;
     /**
      * 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").
@@ -380,78 +383,6 @@ export declare function describeMcpSpecErrorCode(code: unknown): string | undefi
  * 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;
-/**
- * The closed vocabulary of MCP connect-failure classes a per-server status record may carry
- * ({@link McpServerStatus.errorCode}, relayed onto the wiring manifest's `mcp[]` read face). The
- * transport family is named by the failure's SHAPE wherever the SDK exposes one (error class, JSON-RPC
- * code, errno on the cause chain, HTTP status), so a consumer can map a class to an action without
- * parsing the neutralized error string. Two words are the exception and are text-derived, because
- * undici and the SDK surface those two conditions as bare messages with no code: `network` (a
- * `TypeError` whose message matches `fetch failed|terminated|network` and carries no errno) and the
- * non-`McpError` arm of `connection_closed` (a message matching `not connected|connection closed`).
- * A wording change in those libraries moves such a failure to `unknown`, never to a wrong word; the
- * classifier table pins both regexes. An HTTP endpoint that answered with a status is
- * reported in the `http_<status>` form (`http_401` = the endpoint wants (re-)authorization, `http_5xx` =
- * the endpoint is down) — a template member of the type beside these fixed words. Additive-only: a new
- * word here is a new arm for consumers, never a re-meaning of an existing one.
- *  · `connect_refused`   — a connect-phase errno (ECONNREFUSED / ENOTFOUND / …): the request provably never left;
- *  · `connection_failed` — a network errno past the connect phase (reset / timed out mid-exchange);
- *  · `network`           — the HTTP request failed at the network layer with no errno on the cause chain;
- *  · `not_mcp_response`  — the HTTP endpoint answered something that is not an MCP payload (no status to name);
- *  · `spawn_failed`      — a stdio server process could not be started (a missing/unexecutable command);
- *  · `connection_closed` — the transport closed during the handshake (the server process exited, the stream ended);
- *  · `timeout`           — the handshake's request timed out;
- *  · `protocol`          — the server answered the handshake with an MCP/JSON-RPC error (a version mismatch, a
- *                          rejected capability, …) — `error` carries the named condition;
- *  · `invalid_config`    — the declaration itself could not be dialed (a malformed `url`): a configuration
- *                          fault to fix in the spec, never an outage to wait out;
- *  · `unknown`           — none of the above could be established from the thrown value.
- */
-export declare const MCP_FAILURE_CODES: readonly ["connect_refused", "connection_failed", "network", "not_mcp_response", "spawn_failed", "connection_closed", "timeout", "protocol", "invalid_config", "unknown"];
-export type McpFailureCode = (typeof MCP_FAILURE_CODES)[number] | `http_${number}`;
-/**
- * Classify one connect-time failure into {@link McpFailureCode}. Reads the thrown value's SHAPE
- * (error class, JSON-RPC code, errno on the cause chain, HTTP status) first; only the two
- * message-shaped conditions named on {@link MCP_FAILURE_CODES} (`network`, the non-`McpError`
- * `connection_closed`) are decided by a fixed regex over the message, and no other word can be chosen
- * by message text — a remote's own wording can at most leave a failure at `unknown`.
- * `transport` disambiguates the errno family: on a stdio server an errno is the child
- * process failing to spawn, on an HTTP server it is the socket; a caller that could not establish the
- * kind passes `undefined` and the errno family reads as the transport-neutral `connection_failed`.
- * Total: every input maps to a word, and `unknown` is the honest word for a value this table cannot
- * read (a caller must not receive a guess).
- */
-export declare function mcpFailureCodeOf(err: unknown, transport: "stdio" | "http" | undefined): McpFailureCode;
 export { normalizeNameSegment as normalizeMcpName, clampNameSegment } from "./protocol-naming.js";
 export * from "./image-downsample.js";
 /**
@@ -483,6 +414,19 @@ export interface ProtocolHttpAuth {
  * 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;
+/** `kind` is the dial's ONE read of `spec.transport.kind` (taken by the caller beside the dial and threaded
+ *  here, to the idle bucket and to the failure classifier alike): a nested `transport` object is the
+ *  caller's, and a getter that answered differently to two readers would otherwise connect over one
+ *  transport and be judged under another. An unknown kind takes the non-stdio branch, as it always did. */
+/**
+ * The MCP HTTP transport's `fetch`: every request the transport makes — the POST, the SSE GET (initial and
+ * resumed), the DELETE, the auth flows — goes to the endpoint the declaration NAMED and follows no redirect.
+ * `fetch`'s default follows a 3xx silently and then reports only the last hop, which is the one shape under
+ * which the delivery verdict would lie (a connect refusal on the redirect target reading "never sent" while
+ * the declared endpoint had received the POST); a 3xx now surfaces as the SDK's HTTP-status error, and a
+ * body or a credential never travels to a host the declaration did not name. Exported for its pin only.
+ */
+export declare const declaredEndpointFetch: typeof fetch;
 interface McpContentItem {
     type: string;
     text?: string;