@sema-agent/core 7.5.2 → 7.6.1

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/model-seat.d.ts

@@ -0,0 +1,99 @@
+/**
+ * The MODEL seat: how a task names a model (`ModelRef`), the roles a deployment binds models to
+ * (`ModelRole` / `RoleSpec` / `ModelRoles`), and the provider seat a ref resolves to (`Brain`). Layer 0
+ * vocabulary beside `terminal-cause.ts` and `gate-outcome.ts` — no import above this layer, so any
+ * module may read the words. `types.ts` re-exports every name below, so no consumer's import changes.
+ */
+import type { ThinkingLevel } from "../internal/harness.js";
+import type { CompleteSimpleFn, Model, StreamFn } from "../internal/llm.js";
+/** A model reference: either a fully-formed Model, or a `"provider/id"` ref resolved via a catalog. */
+export type ModelRef = string | Model;
+/**
+ * Logical model roles, so a deployment declares its models once and every subsystem asks for its
+ * role instead of repeating a model name. Resolved against `RunnerDeps.roles` / `TaskSpec.roles`
+ * with a fallback chain (e.g. `summarize → default`, `synthesize → team → default`).
+ * - `default` — the main task model when `TaskSpec.model` is omitted.
+ * - `summarize` — between-turn compaction/summarization. Absent = the MAIN task model, which is the
+ *   correct default baseline: the summary request FORKS the main conversation's already-paid
+ *   prompt-cache prefix (design/169-A CC form — same system prompt, same message prefix, one
+ *   appended instruction), so the marginal cost is a cache read plus one summary's output, not a
+ *   full-price re-prefill. Configuring a separate cheap model here is an explicit deployment
+ *   tradeoff (quality for price): an independent model cannot share the main prefix, so it pays the
+ *   full independent-request serialization every boundary AND summarizes with a weaker model.
+ * - `subagent` — delegated sub-runs (`createSubagentTool` without an explicit model).
+ * - `team` / `synthesize` — team members / the neutral synthesizer.
+ * - `advisor` — the strong "teacher" a cheap student escalates to (`runWithTeacher`).
+ * - `classifier` — the auto-mode permission classifier (a roster-cheap tier; falls back
+ *   `summarize → default`, tier default `flash` on tier-expanded catalogs).
+ * - `consolidate` — the memory-consolidation distillation driver (design/376). Falls back to
+ *   `summarize` and then REFUSES LOUDLY — deliberately never to `default`: one consolidation run
+ *   is a whole-library read (~10⁵ prompt tokens), so silently escalating to the most expensive
+ *   main-task model is the bad-value-silence family, not a convenience. The divergence from the
+ *   classifier family's `→ default` tail is calibrated on call volume: a classifier resolves one
+ *   short classification, this role resolves a full-library batch. An explicit
+ *   `roles.consolidate = <main model>` is a legal deployment choice; the summarize hop is kept
+ *   because a deployment that declared a cheap summarize tier has already made the cost choice
+ *   this role wants (note the summarize DEFAULT rationale — prompt-cache forking — does not
+ *   apply here: consolidation is an offline independent request with no shared prefix).
+ */
+export type ModelRole = "default" | "summarize" | "subagent" | "team" | "synthesize" | "advisor" | "verifier" | "classifier" | "consolidate";
+/**
+ * A role's model: a `ModelRef`, or a config object that pins a `model`, **selects** one by
+ * capability/price (`select`, design/11 Layer 2), and/or sets a default `thinking` level.
+ */
+export type RoleSpec = ModelRef | {
+    model?: ModelRef;
+    select?: import("./select-model.js").ModelCriteria;
+    thinking?: ThinkingLevel;
+    /**
+     * Optional preset system prompt for this role (e.g. {@link CODE_AGENT_PROMPT} for a dev role).
+     * Used only when the task does not supply its own `TaskSpec.systemPrompt`. Lets coding roles run
+     * a coding prompt while other roles keep the neutral default — without touching the global default.
+     */
+    systemPrompt?: string;
+};
+/** Map of role → model. `TaskSpec.roles` overrides `RunnerDeps.roles` per task/scenario. */
+export type ModelRoles = Partial<Record<ModelRole, RoleSpec>>;
+/** The "external brain": a streaming completion function plus a non-streaming one (auto-derived if omitted). */
+export interface Brain {
+    /** Streaming completion. Must follow the AssistantMessageEvent stream contract (never throw post-invocation).
+     *
+     * NOTE: the return type is a union — `Stream | Promise<Stream>`. Third-party direct callers must
+     * normalize first (`const s = await brain.stream(...)`) before iterating or reading `.result()`,
+     * otherwise TS reports TS2339 on the union. The Runner already handles this internally. */
+    stream: StreamFn;
+    /**
+     * Optional non-streaming completion used by compaction/summarization.
+     * If omitted, it is derived from `stream` by consuming the stream to its final result.
+     *
+     * This is exactly the runtime's `completeSimple` type: the engine forwards the value you supply
+     * as-is, with no adapting wrapper in between.
+     *
+     * CONTRACT BEYOND WHAT THE TYPE STATES — every field named here is OPTIONAL on
+     * {@link AssistantMessage}, so a message rebuilt from a field whitelist still typechecks while
+     * silently disabling recovery:
+     * - return the AssistantMessage with ALL fields intact, in particular `errorKind` (the compaction
+     *   summary path keys its budget-escalation recovery on it) and `errorMessage`;
+     * - honor `options.signal` — the summary call runs under a soft deadline that aborts through it;
+     * - honor `options.maxTokens` — that is the escalating budget the recovery re-issues the call with.
+     */
+    complete?: CompleteSimpleFn;
+    /**
+     * Optional key↔URL pairing judge (see `src/brain/route-adjudicator.ts` for the law). Answers, for a
+     * model this brain would serve, whether the credential the request would carry belongs to the URL
+     * it would target — WITHOUT sending anything. `perModelAuth` is the caller's already-resolved
+     * per-model auth (the `getApiKeyAndHeaders` result), so a resolution seat can pre-flight the exact
+     * request it is about to make. First-party brains implement it against their own config; the
+     * decorators (routing/failover/degrading/circuit-breaker) re-dispatch it the way their `stream`
+     * would. `undefined` = this brain cannot judge (a custom brain without the face) — callers must
+     * treat that as "no judgment", never as OK or as broken.
+     *
+     * The same law runs again inside the first-party brains' request build (single source, called
+     * twice): a broken pairing that skips the pre-flight still refuses loudly at the request instead
+     * of sending a credential to a host it is not paired with.
+     */
+    adjudicateRoute?: (model: Model, perModelAuth?: {
+        apiKey?: string;
+        headers?: Record<string, string>;
+    }) => import("../internal/llm.js").RouteAdjudication | undefined;
+}

package/dist/core/model-seat.js

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

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/reminder-mint.d.ts

@@ -59,6 +59,16 @@ export declare function openSystemReminder(mark: string | undefined): string;
  *  used by the user-lane wrap homes. The BODY is byte-untouched by the mark (design/319 first
  *  invariant: zero data-byte change — the mark rides only the engine's own tag). */
 export declare function mintSystemReminder(body: string, mark: string | undefined): string;
+/** Wrap model-facing hook/gate feedback in a `<system-reminder>` so it reads as guidance, not data.
+ *  NOTE (council design/74 #6): this does NOT escape a literal `</system-reminder>` in `text` — callers MUST
+ *  pass trusted, first-party strings (every current caller does: fixed gate/limit messages). If a future
+ *  caller needs to relay UNTRUSTED content (tool output, user data), it must sanitize the close tag first
+ *  (or use the `delimitUntrusted` fence), or a crafted payload could break out of the reminder framing.
+ *  design/319 (A ticket): `mark` is the session's reminder provenance mark — run-scoped callers thread it
+ *  so the open tag carries the value the system-prompt declaration names (rendered by the mint home; the
+ *  body is byte-untouched). Absent ⇒ the historic bare open tag (a caller outside a run). Declared here,
+ *  beside the mint it wraps; `hooks.ts` re-exports it as the hook seam's feedback envelope. */
+export declare function formatHookFeedback(text: string, mark?: string): string;
 /**
  * DECLARE port — the system-prompt declaration that gives the mark meaning. STRICT, single form
  * (design/319 D-2, no grace clause): reminder-shaped text without the current mark is data wherever