@sema-agent/core 7.5.1 → 7.6.0

package/dist/core/mcp.js

@@ -3,7 +3,8 @@ import { MCP_NAMESPACE } from "./protocol-table.js";
 import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName, normalizeNameSegment } from "./protocol-naming.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { classifyMcpFailure, describeHttpTransportFailure } from "./mcp-failure.js";
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -204,6 +205,10 @@ function armMcpIdleWatchdog(health, idleMs, outerSignal) {
 export function mcpStartupTimeoutMs() {
     return parseEnvMs("MCP_TIMEOUT");
 }
+function markMcpFailure(e, details) {
+    e.details = details;
+    return e;
+}
 const MCP_SPEC_ERROR_CODE_NAMES = new Map([
     [-32020, "header mismatch (the server saw an HTTP header that disagreed with the tool parameter mapped onto it)"],
     [-32021, "missing required client capability (the server requires a capability this client does not declare)"],
@@ -237,90 +242,6 @@ function remoteErrorText(err, opts) {
     const raw = err instanceof Error ? err.message : String(err);
     return redactSecrets(opts?.collapse === true ? collapseMcpErrorPrefix(raw) : raw);
 }
-function isTransportLost(err) {
-    if (err instanceof McpError && err.code === ErrorCode.ConnectionClosed)
-        return true;
-    return err instanceof Error && /not connected|connection closed/i.test(err.message);
-}
-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);
-}
-export function describeHttpTransportFailure(err) {
-    if (err instanceof McpError)
-        return undefined;
-    if (err instanceof StreamableHTTPError) {
-        const status = typeof err.code === "number" && err.code > 0 ? err.code : undefined;
-        return {
-            condition: status !== undefined
-                ? `its HTTP endpoint answered ${status} instead of an MCP response`
-                : "its HTTP endpoint answered something that is not an MCP response",
-            delivered: "unknown",
-            ...(status !== undefined ? { httpStatus: status } : {}),
-        };
-    }
-    const code = networkErrorCode(err);
-    if (code !== undefined) {
-        return NETWORK_CODES_NEVER_DELIVERED.has(code)
-            ? { condition: `its HTTP endpoint could not be reached (${code})`, delivered: "no" }
-            : { condition: `the connection to its HTTP endpoint failed (${code})`, delivered: "unknown" };
-    }
-    if (err instanceof TypeError && /fetch failed|terminated|network/i.test(err.message)) {
-        return { condition: "the HTTP request to its endpoint failed at the network layer", delivered: "unknown" };
-    }
-    return undefined;
-}
-export const MCP_FAILURE_CODES = ["connect_refused", "connection_failed", "network", "not_mcp_response", "spawn_failed", "connection_closed", "timeout", "protocol", "invalid_config", "unknown"];
-export function mcpFailureCodeOf(err, transport) {
-    if (err instanceof McpError) {
-        if (err.code === ErrorCode.ConnectionClosed)
-            return "connection_closed";
-        if (err.code === ErrorCode.RequestTimeout)
-            return "timeout";
-        return "protocol";
-    }
-    const http = describeHttpTransportFailure(err);
-    if (http !== undefined) {
-        if (http.httpStatus !== undefined)
-            return `http_${http.httpStatus}`;
-        if (err instanceof StreamableHTTPError)
-            return "not_mcp_response";
-        const code = networkErrorCode(err);
-        if (code === undefined)
-            return "network";
-        if (code === "ERR_INVALID_URL")
-            return "invalid_config";
-        if (code.startsWith("ERR_"))
-            return "unknown";
-        if (transport === "stdio")
-            return "spawn_failed";
-        if (transport === undefined)
-            return "connection_failed";
-        return http.delivered === "no" ? "connect_refused" : "connection_failed";
-    }
-    if (isTransportLost(err))
-        return "connection_closed";
-    return "unknown";
-}
 function writeEffectWarning(writeEffect) {
     return writeEffect
         ? " This tool is write-capable: treat its side effects as POSSIBLY APPLIED and verify the actual state before retrying."
@@ -341,72 +262,63 @@ function rethrowHonestMcpError(err, ctx) {
     sanitizeMcpErrorTextInPlace(err);
     if (ctx.idle?.signal.reason === IDLE_WATCHDOG_ABORT_REASON) {
         const serverLabel = inlineUntrusted(ctx.server);
-        const e = new Error(`${ctx.what} on MCP server "${serverLabel}" received no response for ${ctx.idle.idleMs}ms (idle watchdog — ` +
+        finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" received no response for ${ctx.idle.idleMs}ms (idle watchdog — ` +
             `distinct from the ${ctx.timeoutMs}ms total ceiling above). The server may still be alive but is not ` +
             `responding; the client stopped waiting.${writeEffectWarning(ctx.writeEffect)} (Set MCP_IDLE_TIMEOUT_STDIO ` +
-            `/ MCP_IDLE_TIMEOUT_HTTP (ms) to change this bound.)`, { cause: err });
-        e.errorKind = "timeout";
-        e.details = { timedOut: true, timeoutMs: ctx.idle.idleMs, idleTimeout: true, server: ctx.server };
-        finish(e);
+            `/ MCP_IDLE_TIMEOUT_HTTP (ms) to change this bound.)`, { cause: err }), { code: "timeout", delivered: "unknown", server: ctx.server, timeoutMs: ctx.idle.idleMs, idleTimeout: true }));
     }
     if (ctx.signal?.aborted)
         finish(err);
     const serverLabel = inlineUntrusted(ctx.server);
     const fenceServerText = (label, raw) => delimitUntrusted(label, truncateMcpErrorText(raw));
-    if (err instanceof McpError && err.code === ErrorCode.RequestTimeout) {
-        const data = err.data;
-        const totalMs = typeof data?.maxTotalTimeout === "number" ? data.maxTotalTimeout : undefined;
-        const e = new Error(totalMs !== undefined
-            ? `${ctx.what} on MCP server "${serverLabel}" exceeded its total time ceiling of ${totalMs}ms (the call stayed alive — e.g. via progress notifications — but ran past the total wall-clock budget). The client stopped waiting, but the server may still be executing the request — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)} (Set the MCP_TOOL_TIMEOUT_TOTAL environment variable (ms) to change this ceiling; MCP_TOOL_TIMEOUT only tunes the per-call timer, currently ${ctx.timeoutMs}ms.)`
-            : `${ctx.what} on MCP server "${serverLabel}" timed out after ${ctx.timeoutMs}ms. The client stopped waiting, but the server may still be executing the request — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)} (Set the MCP_TOOL_TIMEOUT environment variable (ms) to change this limit.)`, { cause: err });
-        e.errorKind = "timeout";
-        e.details =
-            totalMs !== undefined
-                ? { timedOut: true, timeoutMs: totalMs, totalTimeout: true, server: ctx.server }
-                : { timedOut: true, timeoutMs: ctx.timeoutMs, server: ctx.server };
-        finish(e);
-    }
-    if (isTransportLost(err)) {
-        const e = new Error(`The connection to MCP server "${serverLabel}" was lost while ${ctx.what} was in flight. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}`, { cause: err });
-        e.errorKind = "transport_lost";
-        e.details = { transportLost: true, server: ctx.server };
-        finish(e);
-    }
-    const httpFailure = describeHttpTransportFailure(err);
-    if (httpFailure !== undefined) {
-        const detail = remoteErrorText(err);
-        const fenced = `\nThe transport error follows as external/untrusted data:\n${fenceServerText(`${ctx.server} transport error`, detail)}`;
-        const e = new Error(httpFailure.delivered === "no"
-            ? `${ctx.what} could not reach MCP server "${serverLabel}": ${httpFailure.condition}. The request was not delivered, so the server did not execute it. This server's tools and resources will keep failing until its endpoint is reachable again — do not retry them; use an alternative if one exists.${fenced}`
-            : `${ctx.what} failed at the transport layer of MCP server "${serverLabel}": ${httpFailure.condition}. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}${fenced}`, { cause: err });
-        e.errorKind = httpFailure.delivered === "no" ? "server_disconnected" : "transport_lost";
-        e.details = {
-            server: ctx.server,
-            ...(httpFailure.delivered === "no" ? {} : { transportLost: true }),
-            ...(httpFailure.httpStatus !== undefined ? { httpStatus: httpFailure.httpStatus } : {}),
-        };
-        finish(e);
-    }
-    if (err instanceof McpError) {
-        const condition = describeMcpSpecErrorCode(err.code);
-        if (condition !== undefined) {
-            const e = new Error(`${ctx.what} on MCP server "${serverLabel}" was rejected with MCP protocol error ${err.code} — ${condition}. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, err.message)}`, { cause: err });
-            e.errorKind = "protocol_error";
-            e.details = { server: ctx.server, specErrorCode: err.code };
-            finish(e);
+    const failure = classifyMcpFailure(err, { phase: "request" });
+    const details = (extra) => ({ code: failure.kind, delivered: failure.delivered, server: ctx.server, ...extra });
+    switch (failure.kind) {
+        case "timeout": {
+            const data = err.data;
+            const totalMs = typeof data?.maxTotalTimeout === "number" ? data.maxTotalTimeout : undefined;
+            finish(markMcpFailure(new Error(totalMs !== undefined
+                ? `${ctx.what} on MCP server "${serverLabel}" exceeded its total time ceiling of ${totalMs}ms (the call stayed alive — e.g. via progress notifications — but ran past the total wall-clock budget). The client stopped waiting, but the server may still be executing the request — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)} (Set the MCP_TOOL_TIMEOUT_TOTAL environment variable (ms) to change this ceiling; MCP_TOOL_TIMEOUT only tunes the per-call timer, currently ${ctx.timeoutMs}ms.)`
+                : `${ctx.what} on MCP server "${serverLabel}" timed out after ${ctx.timeoutMs}ms. The client stopped waiting, but the server may still be executing the request — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)} (Set the MCP_TOOL_TIMEOUT environment variable (ms) to change this limit.)`, { cause: err }), totalMs !== undefined ? details({ timeoutMs: totalMs, totalTimeout: true }) : details({ timeoutMs: ctx.timeoutMs })));
+        }
+        case "connection_closed":
+            finish(markMcpFailure(new Error(`The connection to MCP server "${serverLabel}" was lost while ${ctx.what} was in flight. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}`, { cause: err }), details()));
+        case "http_status":
+        case "not_mcp_response":
+        case "connect_refused":
+        case "connection_failed": {
+            const httpFailure = describeHttpTransportFailure(err);
+            const detail = remoteErrorText(err);
+            const fenced = `\nThe transport error follows as external/untrusted data:\n${fenceServerText(`${ctx.server} transport error`, detail)}`;
+            finish(markMcpFailure(new Error(failure.delivered === "no"
+                ? `${ctx.what} could not reach MCP server "${serverLabel}": ${httpFailure.condition}. The request was not delivered, so the server did not execute it. This server's tools and resources will keep failing until its endpoint is reachable again — do not retry them; use an alternative if one exists.${fenced}`
+                : `${ctx.what} failed at the transport layer of MCP server "${serverLabel}": ${httpFailure.condition}. The request may or may not have executed on the server — the outcome is unknown.${writeEffectWarning(ctx.writeEffect)}${fenced}`, { cause: err }), details(failure.httpStatus !== undefined ? { httpStatus: failure.httpStatus } : undefined)));
+        }
+        case "protocol": {
+            const code = err.code;
+            const condition = describeMcpSpecErrorCode(code);
+            if (condition !== undefined) {
+                finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" was rejected with MCP protocol error ${code} — ${condition}. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, err.message)}`, { cause: err }), details({ specErrorCode: code })));
+            }
+            if (ctx.attributeServer) {
+                finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, remoteErrorText(err))}`, { cause: err }), details()));
+            }
+            finish(markMcpFailure(err, details()));
+        }
+        case "spawn_failed":
+        case "invalid_config":
+        case "unknown": {
+            if (ctx.attributeServer) {
+                finish(markMcpFailure(new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, remoteErrorText(err))}`, { cause: err }), details()));
+            }
+            if (err instanceof Error)
+                finish(markMcpFailure(err, details()));
+            finish(err);
         }
     }
-    if (ctx.attributeServer) {
-        const msg = remoteErrorText(err);
-        finish(new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${fenceServerText(`${ctx.server} error`, msg)}`, { cause: err }));
-    }
-    finish(err);
 }
 function throwDeadServer(server, what) {
-    const e = new Error(`MCP server "${inlineUntrusted(server)}" is disconnected (its transport closed earlier in this task). ${what} was not attempted. This server's tools and resources will keep failing until the server is available again — do not retry them; use an alternative if one exists.`);
-    e.errorKind = "server_disconnected";
-    e.details = { server };
-    throw e;
+    throw markMcpFailure(new Error(`MCP server "${inlineUntrusted(server)}" is disconnected (its transport closed earlier in this task). ${what} was not attempted. This server's tools and resources will keep failing until the server is available again — do not retry them; use an alternative if one exists.`), { code: "connection_closed", delivered: "no", server });
 }
 export { normalizeNameSegment as normalizeMcpName, clampNameSegment } from "./protocol-naming.js";
 export * from "./image-downsample.js";
@@ -516,6 +428,7 @@ export function resolveProtocolHttpHeaders(protocol, t, principal) {
     }
     return t.headers;
 }
+export const declaredEndpointFetch = (url, init) => fetch(url, { ...init, redirect: "manual" });
 function buildTransport(spec, principal, kind) {
     const t = spec.transport;
     if (kind === "stdio") {
@@ -532,6 +445,7 @@ function buildTransport(spec, principal, kind) {
     const headers = resolveProtocolHttpHeaders(MCP_NAMESPACE.id, t, principal);
     return new StreamableHTTPClientTransport(new URL(t.url), {
         requestInit: headers ? { headers } : undefined,
+        fetch: declaredEndpointFetch,
     });
 }
 let autoResizer;
@@ -893,7 +807,8 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             }
             else {
                 warnings.push(asServerWarning(spec, r.reason));
-                statuses.push({ name: spec.name, status: "failed", errorCode: mcpFailureCodeOf(r.reason, dialKinds[i]), error: namedMcpFailureText(r.reason) });
+                const { kind, delivered, httpStatus } = classifyMcpFailure(r.reason, { phase: "connect", transport: dialKinds[i] });
+                statuses.push({ name: spec.name, status: "failed", errorCode: kind, delivered, ...(httpStatus !== undefined ? { httpStatus } : {}), error: namedMcpFailureText(r.reason) });
             }
         }
         const resourceTools = buildResourceTools(resourceServers, isServerRevoked);
@@ -933,8 +848,8 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     const advertised = new Set(listed.tools.map((t) => t.name));
                     const retainedRaw = listed.incomplete !== undefined ? h.listedRaw.filter((t) => !advertised.has(t.name)) : [];
                     const mergedRaw = retainedRaw.length > 0 ? [...listed.tools, ...retainedRaw] : listed.tools;
-                    cacheMcpToolMetadata(h.client, retainedRaw.length > 0 ? [...retainedRaw, ...listed.tools] : listed.tools);
-                    const { serverTools, serverAxes, dropped } = intakeListedTools({ tools: mergedRaw }, h.spec, h.client, h.health, imageResizer, mcpDisclosure, isServerRevoked, h.transportKind);
+                    const { serverTools, serverAxes, dropped, accepted } = intakeListedTools({ tools: mergedRaw }, h.spec, h.client, h.health, imageResizer, mcpDisclosure, isServerRevoked, h.transportKind);
+                    cacheMcpToolMetadata(h.client, accepted);
                     const priorNames = h.tools.map((t) => t.name);
                     const newNames = serverTools.map((t) => t.name);
                     const added = newNames.filter((n) => !priorNames.includes(n));
@@ -1305,7 +1220,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 if (isServerRevoked(server)) {
                     return {
                         content: [{ type: "text", text: `${what} was refused: MCP server "${server}" was revoked by the operator mid-session. The request was NOT sent. This server stays on this run's tool roster — every call to it is refused the same way, so don't retry it.` }],
-                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", server },
+                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", delivered: "no", server },
                         terminate: false,
                         isError: true,
                     };
@@ -1364,7 +1279,7 @@ function buildResourceTools(resourceServers, isServerRevoked = () => false) {
                 if (isServerRevoked(server)) {
                     return {
                         content: [{ type: "text", text: `${what} was refused: MCP server "${server}" was revoked by the operator mid-session. The request was NOT sent. This server stays on this run's tool roster — every call to it is refused the same way, so don't retry it.` }],
-                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", server },
+                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", delivered: "no", server },
                         terminate: false,
                         isError: true,
                     };
@@ -1524,8 +1439,8 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             announce.fn?.();
         };
         const listed = await listToolsLenient(client, startupOpts);
-        cacheMcpToolMetadata(client, listed.tools);
-        const { serverTools, serverAxes, dropped, advisories } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked, transportKind);
+        const { serverTools, serverAxes, dropped, advisories, accepted } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked, transportKind);
+        cacheMcpToolMetadata(client, accepted);
         const caps = client.getServerCapabilities();
         const resourceInfo = caps?.resources
             ? {
@@ -1567,6 +1482,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
+    const accepted = [];
     const advisories = [];
     const mintedNames = new Map();
     for (const t of listed.tools) {
@@ -1607,6 +1523,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             advisories.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(schemaAdvisory, 240) });
         }
         const remoteName = t.name;
+        const taskRequired = t.execution !== null && typeof t.execution === "object" && t.execution.taskSupport === "required";
         const namespacedName = mintNamespacedToolName(MCP_NAMESPACE, spec.name, remoteName);
         const mintedBy = mintedNames.get(namespacedName);
         if (mintedBy !== undefined) {
@@ -1639,7 +1556,15 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
                 if (isServerRevoked?.(spec.name) === true) {
                     return {
                         content: [{ type: "text", text: `The call to MCP server "${spec.name}" was refused: the server was revoked by the operator mid-session. The call was NOT sent, so the server did not execute it. This server stays on this run's tool roster — every call to it is refused the same way, so don't retry it.` }],
-                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", server: spec.name },
+                        details: { error: "mcp.server_revoked", code: "mcp.server_revoked", delivered: "no", server: spec.name },
+                        terminate: false,
+                        isError: true,
+                    };
+                }
+                if (taskRequired) {
+                    return {
+                        content: [{ type: "text", text: "The call was refused: this tool requires task-based execution (MCP tasks), which this client does not drive. The call was NOT sent, so the server did not execute it. Every call to this tool is refused the same way, so don't retry it." }],
+                        details: { error: "mcp.task_required", code: "mcp.task_required", delivered: "no", server: spec.name },
                         terminate: false,
                         isError: true,
                     };
@@ -1693,7 +1618,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
                     if (reminderDisclosure !== undefined) {
                         observeReminderMarkEcho({ text: msg, mark: reminderDisclosure.mark, outlet: "mcp", counts: reminderDisclosure.counts });
                     }
-                    throw new Error(msg);
+                    throw Object.assign(new Error(msg), { details: { code: "mcp.tool_error", delivered: "yes", server: spec.name } });
                 }
                 const content = gateMcpOutput(mapped);
                 const sc = res.structuredContent;
@@ -1731,8 +1656,9 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             },
         };
         serverTools.push(declaredContentOrigin !== undefined ? withContentOrigin(mounted, declaredContentOrigin) : mounted);
+        accepted.push(t);
     }
-    return { serverTools, serverAxes, dropped, advisories };
+    return { serverTools, serverAxes, dropped, advisories, accepted };
 }
 function asServerWarning(spec, err) {
     const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${namedMcpFailureText(err)})`, { cause: sanitizedCause(err) });

package/dist/core/pause-registry.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The pause registry — ONE table for the three faces of a durable pause (why it stopped / what it left
+ * hanging / what brings it back), the three word types and the resume match DERIVED from it, and the
+ * registry-bound `gate` × `pendingAction` pair with its checked constructor. A vocabulary module on the
+ * floor: it types against `checkpoint-store.ts` (type-only, no runtime edge) and `checkpoint-store.ts`
+ * reaches down for the pair type.
+ */
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+import type { Checkpoint, CheckpointGate, CheckpointRow, PendingAction, ResumeOutcome } from "./checkpoint-store.js";
+/**
+ * THE registry of pauses — one row per way a run can stop and wait, and the ONE place the three faces
+ * of that pause are declared together: WHY it stopped (`CheckpointGate.kind`, the row key), WHAT it left
+ * hanging (`pending` — the {@link PendingAction} kind the row carries), and WHAT BRINGS IT BACK (`resume`
+ * — the {@link ResumeOutcome} gate word a caller must answer with). The three vocabularies used to be
+ * three independent `as const` lists whose correspondence lived in a six-arm disjunction in the resume
+ * entry and two FACET comments; adding a kind of pause meant three declarations, one disjunction arm and
+ * two comments, and missing any of them was silent. Now the three word types, the resume match and the
+ * facet are DERIVED from this table: adding a pause = adding a row, and the fences below red the build
+ * until every declaration agrees with it.
+ *
+ *  - `facet` — the deadline semantic a deployment's reaper applies (see {@link Checkpoint.deadline}):
+ *    `A` = approval gates, whose `deadline` is an SLA resolve-deny; `B` = unattended-TTL gates, whose
+ *    `deadline` is an abandonment TTL (`expire`/`reap` only — never a resolve-deny; these pauses produce
+ *    no `tool_end` and therefore no settlement); `-` = the non-gate park (`task_done`).
+ *  - `taskStatus` — the `TaskResult.status` word a run assembles when it stops at this gate (approvals and
+ *    resource slices read `suspended`; the two review pauses read `needs_review`).
+ *  - `terminal` — `task_done` is the 1C handle / deployment-park convention, not a run pause core mints.
+ */
+export declare const PAUSE_REGISTRY: {
+    readonly human: {
+        readonly pending: "tool_approval";
+        readonly resume: "policy_ask";
+        readonly facet: "A";
+        readonly taskStatus: "suspended";
+        readonly terminal: false;
+    };
+    readonly irreversible_ask: {
+        readonly pending: "tool_approval";
+        readonly resume: "policy_ask";
+        readonly facet: "A";
+        readonly taskStatus: "suspended";
+        readonly terminal: false;
+    };
+    readonly resource_limit: {
+        readonly pending: "resource_limit";
+        readonly resume: "resource_limit";
+        readonly facet: "B";
+        readonly taskStatus: "suspended";
+        readonly terminal: false;
+    };
+    readonly needs_review: {
+        readonly pending: "review";
+        readonly resume: "dry_run_review";
+        readonly facet: "B";
+        readonly taskStatus: "needs_review";
+        readonly terminal: false;
+    };
+    readonly plan_review: {
+        readonly pending: "plan_review";
+        readonly resume: "plan_review";
+        readonly facet: "B";
+        readonly taskStatus: "needs_review";
+        readonly terminal: false;
+    };
+    readonly task_done: {
+        readonly pending: "task_done";
+        readonly resume: "task_done";
+        readonly facet: "-";
+        readonly taskStatus: "suspended";
+        readonly terminal: true;
+    };
+};
+/** The pause kinds — the row keys of {@link PAUSE_REGISTRY}; `CheckpointGate.kind` is fenced to equal it. */
+export type GateKind = keyof typeof PAUSE_REGISTRY;
+/** The pending-action kinds — the `pending` column; `PendingAction.kind` is fenced to equal it. */
+export type PendingKind = (typeof PAUSE_REGISTRY)[GateKind]["pending"];
+/** The resume gate words — the `resume` column plus `wake` (the un-park verb, which is not a gate decision
+ *  and so has no registry row); `ResumeOutcome.gate` is fenced to equal it. */
+export type ResumeGate = (typeof PAUSE_REGISTRY)[GateKind]["resume"] | "wake";
+/** Runtime twin of {@link GateKind}. */
+export declare function isGateKind(v: unknown): v is GateKind;
+/** The one resume-match predicate: does this outcome gate word answer a checkpoint of this kind? `wake`
+ *  answers any (it passed its own, stricter, non-gate validation upstream); every other word must be the
+ *  row's `resume` column. Replaces a six-arm hand-written disjunction. */
+export declare function resumeGateMatches(gateKind: GateKind, outcomeGate: ResumeGate): boolean;
+/**
+ * The one CONSTRUCTOR of a registry-bound pause pair from a gate and a pending action that arrive
+ * separately typed (a mint site that chooses its gate in a ternary, a store deserializing a row, a test
+ * fixture taking overrides). The generic binds the pending action's kind to the gate's registry row at
+ * the call site; the runtime check is the belt for the wide call (`CheckpointGate` × `PendingAction`) and
+ * for a deserialized row, where the type says nothing about the bytes. A pair the registry does not pair
+ * is refused loudly here rather than persisted and discovered at resume.
+ */
+export declare function pauseOf<K extends GateKind>(gate: Extract<CheckpointGate, {
+    kind: K;
+}>, pendingAction: Extract<PendingAction, {
+    kind: (typeof PAUSE_REGISTRY)[K]["pending"];
+}>): CheckpointPause<K>;
+/** The loose input shape of {@link checkpointFrom}: a row's fields with its gate and pending action typed
+ *  independently (as a deserializer or a fixture holds them). */
+export type CheckpointFields = CheckpointRow & {
+    gate: CheckpointGate;
+    pendingAction: PendingAction;
+};
+/** Build a {@link Checkpoint} from independently typed fields — {@link pauseOf} binds (and checks) the pair. */
+export declare function checkpointFrom(fields: CheckpointFields): Checkpoint;
+/** Compile-time fences (each `never` while the declaration and the registry agree, in BOTH directions). */
+export type GateDeclarationCoversEveryRegistryRow = AssertAllKeysHandled<Exclude<GateKind, CheckpointGate["kind"]>>;
+export type RegistryCoversEveryGateDeclaration = AssertAllKeysHandled<Exclude<CheckpointGate["kind"], GateKind>>;
+export type PendingDeclarationCoversEveryRegistryColumn = AssertAllKeysHandled<Exclude<PendingKind, PendingAction["kind"]>>;
+export type RegistryCoversEveryPendingDeclaration = AssertAllKeysHandled<Exclude<PendingAction["kind"], PendingKind>>;
+export type ResumeDeclarationCoversEveryRegistryColumn = AssertAllKeysHandled<Exclude<ResumeGate, ResumeOutcome["gate"]>>;
+export type RegistryCoversEveryResumeDeclaration = AssertAllKeysHandled<Exclude<ResumeOutcome["gate"], ResumeGate>>;
+/**
+ * One row's `gate` × `pendingAction` pair, BOUND by {@link PAUSE_REGISTRY}: a `needs_review` gate carries a
+ * `review` pending action and nothing else, an approval gate a `tool_approval`, and so on. Distributed over
+ * the registry rows so that a row literal pairing a gate with another kind's pending action does not
+ * type-check — the invariant that used to be a sentence in a comment is now the shape of the type.
+ */
+type PairOf<K extends GateKind> = {
+    gate: Extract<CheckpointGate, {
+        kind: K;
+    }>;
+    pendingAction: Extract<PendingAction, {
+        kind: (typeof PAUSE_REGISTRY)[K]["pending"];
+    }>;
+};
+export type CheckpointPause<K extends GateKind = GateKind> = {
+    [P in K]: PairOf<P>;
+}[K];
+export {};

package/dist/core/pause-registry.js

@@ -0,0 +1,27 @@
+export const PAUSE_REGISTRY = {
+    human: { pending: "tool_approval", resume: "policy_ask", facet: "A", taskStatus: "suspended", terminal: false },
+    irreversible_ask: { pending: "tool_approval", resume: "policy_ask", facet: "A", taskStatus: "suspended", terminal: false },
+    resource_limit: { pending: "resource_limit", resume: "resource_limit", facet: "B", taskStatus: "suspended", terminal: false },
+    needs_review: { pending: "review", resume: "dry_run_review", facet: "B", taskStatus: "needs_review", terminal: false },
+    plan_review: { pending: "plan_review", resume: "plan_review", facet: "B", taskStatus: "needs_review", terminal: false },
+    task_done: { pending: "task_done", resume: "task_done", facet: "-", taskStatus: "suspended", terminal: true },
+};
+export function isGateKind(v) {
+    return typeof v === "string" && Object.prototype.hasOwnProperty.call(PAUSE_REGISTRY, v);
+}
+export function resumeGateMatches(gateKind, outcomeGate) {
+    return outcomeGate === "wake" || PAUSE_REGISTRY[gateKind].resume === outcomeGate;
+}
+export function pauseOf(gate, pendingAction) {
+    if (!isGateKind(gate.kind))
+        throw new Error(`checkpoint gate kind "${String(gate.kind)}" is not a registered pause`);
+    const expected = PAUSE_REGISTRY[gate.kind].pending;
+    if (pendingAction.kind !== expected) {
+        throw new Error(`a "${gate.kind}" checkpoint carries a "${String(pendingAction.kind)}" pending action — the pause registry pairs it with "${expected}"`);
+    }
+    return { gate, pendingAction };
+}
+export function checkpointFrom(fields) {
+    const { gate, pendingAction, ...row } = fields;
+    return { ...row, ...pauseOf(gate, pendingAction) };
+}

package/dist/core/protocol-table.d.ts

@@ -75,6 +75,11 @@ export declare const A2A_NAMESPACE: ProtocolNamespace<typeof A2A_PREFIX_NAME>;
 /** Every protocol namespace the engine knows. APPEND-ONLY: adding a protocol must not change how any
  *  existing name resolves — prefixes must stay pairwise non-overlapping (pinned in the table test). */
 export declare const PROTOCOL_TABLE: readonly ProtocolNamespace[];
+/** The namespaced-name shapes the protocol table currently owns, rendered for the two messages that have
+ *  to name them (the caller-name reservation and the policy audit's unprefixed-name arm). Read from the
+ *  table rather than written out: a message that hard-codes ONE protocol becomes wrong — while staying
+ *  green — the moment a second one is appended, and both messages tell a deployment what to write. */
+export declare const NAMESPACED_NAME_SHAPES: string;
 /** The namespace owning `name`, or `undefined` for a caller/first-party tool. */
 export declare function protocolOf(name: string): ProtocolNamespace | undefined;
 export {};

package/dist/core/protocol-table.js

@@ -37,6 +37,7 @@ const A2A_PREFIX_NAME = `a2a${NAME_SEP}`;
 export const MCP_NAMESPACE = makeProtocolNamespace("mcp", MCP_PREFIX_NAME);
 export const A2A_NAMESPACE = makeProtocolNamespace("a2a", A2A_PREFIX_NAME);
 export const PROTOCOL_TABLE = [MCP_NAMESPACE, A2A_NAMESPACE];
+export const NAMESPACED_NAME_SHAPES = PROTOCOL_TABLE.map((ns) => `${ns.prefix}<peer>__<tool>`).join(", ");
 export function protocolOf(name) {
     return PROTOCOL_TABLE.find((ns) => name.startsWith(ns.prefix));
 }

package/dist/core/runner/abort-race.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The abort-signal RACING vocabulary the park lane's synchronous-wait seats stand on — the per-call signal
+ * composition, the value-mapping race and the tagged three-state race — moved whole out of the orchestrator so
+ * the ask-lane phase (adjudicate / resolveAsk), the suspend-saga phase (the paused-VM compensation) and the
+ * park-ask phase (the content-ask delivery race, the projection re-adjudication, the fence) reach DOWN for the
+ * same three helpers instead of each carrying a copy. Pure: no engine state, no clock.
+ */
+/**
+ * design/384 slice 1 — the per-call signal composition all three synchronous-wait seats share
+ * (adjudicate / resolveAsk / resolveContentAsk): `AbortSignal.any([run, call])` when the gate
+ * threaded a per-call signal, the bare run signal otherwise (host-driven gates and unthreaded emits
+ * keep the historical binding byte for byte). The run signal is ALSO composed into the loop's turn
+ * controller, so the double source is a belt, not a dependency — this layer must not assume the
+ * loop's internal wiring. The composed product lives exactly as long as the one wait it bounds
+ * (both sources outlive it), so nothing here retains across calls.
+ */
+export declare function composeCallSignal(runSignal: AbortSignal, callSignal: AbortSignal | undefined): AbortSignal;
+/** design/384 slice 2 — how a raced await ended. The generalized sibling of the ask-side
+ *  `raceAskWaitAgainstSignal` (tool-policy.ts): same three-state form over any value domain.
+ *  `aborted` means the SIGNAL settled the race — the promise may still be pending and stays the
+ *  caller's to detach. `threw` reports the rejection AS a rejection, never folded into the abort
+ *  arm: the value-mapping `raceAbort` below resolves `onAbort()` for a rejection too, which at a
+ *  DECISION seat would disguise a real failure as a concession (and feed the concession value into
+ *  whatever door consumes the raced result) — a decision seat must race with THIS form. */
+export type RacedSettlement<T> = {
+    tag: "value";
+    value: T;
+} | {
+    tag: "threw";
+    error: unknown;
+} | {
+    tag: "aborted";
+};
+/** design/384 slice 2 — settle a raced await the moment `signal` aborts, WITHOUT waiting for the
+ *  promise to notice. Pre-aborted entry answers at once; the listener is removed on settle
+ *  whichever side wins (the `raceAbort` hygiene: `{once}` alone leaks a closure on the signal when
+ *  the promise settles first). The mapped promise attaches BOTH handlers up front, so an abort-arm
+ *  return never leaves an unhandled rejection behind. */
+export declare function raceSettlementAgainstSignal<T>(p: Promise<T>, signal: AbortSignal): Promise<RacedSettlement<T>>;
+/** Race a promise against an abort signal; on abort, resolve with `onAbort()`. Cleans up its listener. */
+export declare function raceAbort<T>(p: Promise<T>, signal: AbortSignal, onAbort: () => T): Promise<T>;

package/dist/core/runner/abort-race.js

@@ -0,0 +1,38 @@
+export function composeCallSignal(runSignal, callSignal) {
+    return callSignal !== undefined ? AbortSignal.any([runSignal, callSignal]) : runSignal;
+}
+export function raceSettlementAgainstSignal(p, signal) {
+    const settled = p.then((value) => ({ tag: "value", value }), (error) => ({ tag: "threw", error }));
+    if (signal.aborted)
+        return Promise.resolve({ tag: "aborted" });
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (r) => {
+            if (done)
+                return;
+            done = true;
+            signal.removeEventListener("abort", onAbortEvent);
+            resolve(r);
+        };
+        const onAbortEvent = () => finish({ tag: "aborted" });
+        signal.addEventListener("abort", onAbortEvent, { once: true });
+        void settled.then(finish);
+    });
+}
+export function raceAbort(p, signal, onAbort) {
+    if (signal.aborted)
+        return Promise.resolve(onAbort());
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (v) => {
+            if (settled)
+                return;
+            settled = true;
+            signal.removeEventListener("abort", onAbortEvent);
+            resolve(v);
+        };
+        const onAbortEvent = () => finish(onAbort());
+        signal.addEventListener("abort", onAbortEvent, { once: true });
+        p.then(finish, () => finish(onAbort()));
+    });
+}