@sema-agent/core 7.51.2 → 7.53.0

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

@@ -1,4 +1,23 @@
 import { SAFETY_AXIS_VOCABULARY } from "./safety-axis-vocab.js";
+import { INLINE_TRUNCATION_MARK, inlineUntrusted } from "./untrusted-text.js";
+import { DECLARATION_RECEIPT_MODE } from "./own-property-receipt.js";
+import { isPlainRecord, receive } from "./mods/kernel/receive.js";
+import { MODS_VALUE_DEPTH } from "./mods/kernel/site-rules.js";
+const TOOL_AXES_SURFACES = {
+    mcp: { key: "tool", declarer: "MCP server" },
+    a2a: { key: "skill", declarer: "A2A peer" },
+};
+function invalidArgument(message) {
+    const refusal = new Error(message);
+    refusal.code = "config.invalid_argument";
+    return refusal;
+}
+function toolAxesSurfaceOf(at) {
+    if (typeof at === "string" && Object.hasOwn(TOOL_AXES_SURFACES, at))
+        return TOOL_AXES_SURFACES[at];
+    throw invalidArgument(`toolAxes is read for a surface, and the surfaces are ${Object.keys(TOOL_AXES_SURFACES).map((s) => JSON.stringify(s)).join(" | ")} ` +
+        `(an MCP server's tools, an A2A peer's skills); the surface named is not one of them.`);
+}
 const TOOL_AXIS_MEMBERS = { effect: true, egress: true, irreversibility: true };
 const TOOL_AXIS_MEMBER_NAMES = Object.keys(TOOL_AXIS_MEMBERS);
 const TOOL_EFFECT_WORDS = SAFETY_AXIS_VOCABULARY.toolEffect;
@@ -6,25 +25,135 @@ const ENGINE_DERIVED_IRREVERSIBILITY = "maybe";
 const IRREVERSIBILITY_POLE_WORDS = SAFETY_AXIS_VOCABULARY.irreversibility.filter((word) => word !== ENGINE_DERIVED_IRREVERSIBILITY);
 const irreversibilityPolesLockstep = true;
 void irreversibilityPolesLockstep;
+const toolAxesDeclarationsAreOne = true;
+void toolAxesDeclarationsAreOne;
 function quotedName(name) {
     return JSON.stringify(name.length > 80 ? `${name.slice(0, 80)}…` : name);
 }
-function describeKind(value) {
-    return value === null ? "null" : Array.isArray(value) ? "an array" : typeof value === "object" ? "an object that is not a plain data record (a map, a class instance, or members that are inherited or not enumerable)" : `a ${typeof value}`;
+function memberNames(path) {
+    let rendered = "";
+    for (const [index, name] of path.entries()) {
+        if (rendered.length > 120)
+            return `${rendered}${INLINE_TRUNCATION_MARK}`;
+        rendered += `${index === 0 ? "" : "."}${quotedName(String(name))}`;
+    }
+    return rendered;
 }
-const ROOT_PROTOTYPE_NAMES = Object.getOwnPropertyNames(Object.prototype).sort().join("\n");
-function isRootPrototype(proto) {
-    if (proto === Object.prototype)
-        return true;
-    return Object.getPrototypeOf(proto) === null && Object.getOwnPropertyNames(proto).sort().join("\n") === ROOT_PROTOTYPE_NAMES;
+function dataKind(value) {
+    return value === null ? "null" : value === undefined ? "undefined" : Array.isArray(value) ? "an array" : typeof value === "object" ? "a record" : `a ${typeof value}`;
 }
-function isPlainRecord(value) {
-    if (typeof value !== "object" || value === null)
-        return false;
-    const proto = Object.getPrototypeOf(value);
-    if (proto !== null && !isRootPrototype(proto))
-        return false;
-    return Object.getOwnPropertyNames(value).length === Object.keys(value).length;
+const RECEIPT_FAULT_PROBLEMS = {
+    proxy: "it is a Proxy, whose traps would run as it is read; copy it into plain data (a spread or a JSON round trip)",
+    "not-data": "it is not plain data (a function, a bigint, a symbol, or an object whose prototype is neither Object.prototype nor null: a class instance, " +
+        "a map, `process.env`, a record built on a prototype or in another realm — a `vm` context, a worker); copy it into plain data (a spread " +
+        "or a JSON round trip), writing out any member it inherits",
+    "getter-threw": "its getter threw while it was read",
+    "prototype-moved": "its prototype changed while it was read",
+    cycle: "it contains itself; declare it as plain data",
+    "too-deep": `it is nested past ${MODS_VALUE_DEPTH} levels`,
+    uncopyable: "it could not be copied whole",
+    accessor: "it is an accessor",
+    hidden: "it is a member that is not an enumerable data property",
+};
+export function declarationFaultOf(fault) {
+    return { path: fault.path.map((key) => (/^(?:0|[1-9]\d*)$/.test(key) ? Number(key) : key)), problem: RECEIPT_FAULT_PROBLEMS[fault.kind] };
+}
+export const DECLARATION_PATH_RULES = Object.freeze({
+    mcp: Object.freeze([
+        { path: ["name"], holds: "a string", required: true },
+        { path: ["transport", "env"], holds: "names to strings" },
+        { path: ["transport", "headers"], holds: "names to strings" },
+    ]),
+    a2a: Object.freeze([
+        { path: ["name"], holds: "a string", required: true },
+        { path: ["headers"], holds: "names to strings" },
+    ]),
+});
+const PROTO_MEMBER = `it is a member named "__proto__", which a copy by assignment would turn into a prototype — not a name a declaration can carry`;
+function declarationVocabularyFault(root, rules) {
+    const asked = new Set();
+    const path = [];
+    const stack = [];
+    const ruleAt = () => rules.find((rule) => rule.path.length === path.length && rule.path.every((key, i) => key === path[i]));
+    const onRuleRoute = () => rules.some((rule) => rule.path.length > path.length && path.every((key, i) => key === rule.path[i]));
+    const ruleProblem = (rule, value) => {
+        if (rule.holds === "a string")
+            return typeof value === "string" ? undefined : `it is ${dataKind(value)}, not a string`;
+        if (!isPlainRecord(value))
+            return `it is ${dataKind(value)}, not a record of names to strings`;
+        for (const [key, member] of Object.entries(value)) {
+            path.push(key);
+            if (key === "__proto__")
+                return PROTO_MEMBER;
+            if (member !== undefined && typeof member !== "string")
+                return `it is ${dataKind(member)}, not a string: this record maps names to strings`;
+            path.pop();
+        }
+        return undefined;
+    };
+    const meet = (value) => {
+        if (typeof value !== "object" || value === null || (asked.has(value) && !onRuleRoute()))
+            return undefined;
+        asked.add(value);
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index++) {
+                const own = Object.hasOwn(value, index);
+                if (own && typeof value[index] === "string")
+                    continue;
+                path.push(index);
+                return `it is ${own ? dataKind(value[index]) : "a hole"}, not a string: every list a declaration carries is a list of names`;
+            }
+            const named = Object.keys(value).find((key) => !(/^(?:0|[1-9]\d*)$/.test(key) && Number(key) < value.length));
+            if (named === undefined)
+                return undefined;
+            path.push(named);
+            return "it is a list member that is not an index: a list declares its names at its indices only";
+        }
+        stack.push({ members: Object.entries(value), next: 0 });
+        return undefined;
+    };
+    for (const rule of rules) {
+        if (rule.required !== true)
+            continue;
+        let at = root;
+        for (const key of rule.path)
+            at = isPlainRecord(at) && Object.hasOwn(at, key) ? at[key] : undefined;
+        if (at === undefined)
+            return { path: [...rule.path], problem: `it is missing: a declaration carries ${rule.holds} here` };
+    }
+    let problem = meet(root);
+    while (problem === undefined && stack.length > 0) {
+        const frame = stack[stack.length - 1];
+        if (frame.next === frame.members.length) {
+            stack.pop();
+            if (stack.length > 0)
+                path.pop();
+            continue;
+        }
+        const [key, member] = frame.members[frame.next++];
+        path.push(key);
+        const rule = key === "__proto__" || member === undefined ? undefined : ruleAt();
+        if (key === "__proto__")
+            problem = PROTO_MEMBER;
+        else if (rule !== undefined)
+            problem = ruleProblem(rule, member);
+        else {
+            const depth = stack.length;
+            problem = meet(member);
+            if (problem === undefined && stack.length > depth)
+                continue;
+        }
+        if (problem === undefined)
+            path.pop();
+    }
+    return problem === undefined ? undefined : { path, problem };
+}
+export function receiveDeclaration(declared, rules = []) {
+    const received = receive(declared, DECLARATION_RECEIPT_MODE);
+    if (!received.ok)
+        return { ok: false, fault: declarationFaultOf(received.fault) };
+    const fault = isPlainRecord(received.value) ? declarationVocabularyFault(received.value, rules) : undefined;
+    return fault === undefined ? { ok: true, value: received.value } : { ok: false, fault };
 }
 function isToolEffectWord(value) {
     return typeof value === "string" && TOOL_EFFECT_WORDS.includes(value);
@@ -34,12 +163,19 @@ function isIrreversibilityPoleWord(value) {
 }
 function readToolAxisEntry(raw) {
     if (!isPlainRecord(raw))
-        return `the declaration is ${describeKind(raw)}, not an object of axes`;
-    for (const member of Object.keys(raw)) {
-        if (!TOOL_AXIS_MEMBER_NAMES.includes(member))
-            return `unknown member ${quotedName(member)} (the members are ${TOOL_AXIS_MEMBER_NAMES.join(", ")})`;
+        return `the declaration is ${dataKind(raw)}, not an object of axes`;
+    const listed = Object.keys(raw);
+    const unknown = listed.find((member) => !TOOL_AXIS_MEMBER_NAMES.includes(member));
+    if (unknown !== undefined)
+        return `unknown member ${quotedName(unknown)} (the members are ${TOOL_AXIS_MEMBER_NAMES.join(", ")})`;
+    const declared = Object.create(null);
+    for (const member of TOOL_AXIS_MEMBER_NAMES) {
+        const value = raw[member];
+        if (value !== undefined && !listed.includes(member))
+            return `member ${quotedName(member)} is a hidden member: its name answers a value the declaration does not list as its own`;
+        declared[member] = value;
     }
-    const { effect, egress, irreversibility } = raw;
+    const { effect, egress, irreversibility } = declared;
     if (effect !== undefined && !isToolEffectWord(effect))
         return `member "effect" is not one of ${TOOL_EFFECT_WORDS.join(" | ")}`;
     if (egress !== undefined && typeof egress !== "boolean")
@@ -52,22 +188,25 @@ function readToolAxisEntry(raw) {
         ...(irreversibility !== undefined ? { irreversibility } : {}),
     };
 }
-export function readMcpToolAxes(declared) {
+export function readToolAxes(declared, at) {
+    const unit = toolAxesSurfaceOf(at).key;
     if (declared === undefined)
         return { ok: true };
-    let perTool;
-    try {
-        if (!isPlainRecord(declared))
-            return { ok: false, problem: `toolAxes is ${describeKind(declared)}, not an object of per-tool axis declarations` };
-        perTool = Object.entries(declared);
-    }
-    catch {
-        return { ok: false, problem: "toolAxes could not be read: a property threw while it was read" };
+    const received = receiveDeclaration(declared);
+    if (!received.ok) {
+        const [key, ...member] = received.fault.path;
+        if (key === undefined)
+            return { ok: false, problem: `toolAxes cannot be read: ${received.fault.problem}` };
+        const where = member.length > 0 ? `member ${memberNames(member)}: ` : "";
+        return { ok: false, problem: `the axes declared for ${unit} ${quotedName(String(key))} do not fit: ${where}${received.fault.problem}` };
     }
+    const perTool = received.value;
+    if (!isPlainRecord(perTool))
+        return { ok: false, problem: `toolAxes is ${dataKind(perTool)}, not an object of per-${unit} axis declarations` };
     const entries = [];
-    for (const [tool, raw] of perTool) {
-        if (tool.length === 0)
-            return { ok: false, problem: "toolAxes has an empty tool name" };
+    for (const [key, raw] of Object.entries(perTool)) {
+        if (key.length === 0)
+            return { ok: false, problem: `toolAxes has an empty ${unit} name` };
         let entry;
         try {
             entry = readToolAxisEntry(raw);
@@ -76,9 +215,20 @@ export function readMcpToolAxes(declared) {
             entry = "a member threw while it was read";
         }
         if (typeof entry === "string")
-            return { ok: false, problem: `the axes declared for tool ${quotedName(tool)} do not fit: ${entry}` };
+            return { ok: false, problem: `the axes declared for ${unit} ${quotedName(key)} do not fit: ${entry}` };
         if (Object.keys(entry).length > 0)
-            entries.push([tool, entry]);
+            entries.push([key, entry]);
     }
     return entries.length > 0 ? { ok: true, toolAxes: Object.fromEntries(entries) } : { ok: true };
 }
+export function readMcpToolAxes(declared) {
+    return readToolAxes(declared, "mcp");
+}
+export function declarerWord(at) {
+    return toolAxesSurfaceOf(at).declarer;
+}
+export function toolAxesRefusal(at, name, problem) {
+    return invalidArgument(`${toolAxesSurfaceOf(at).declarer} ${name} declares toolAxes the engine cannot read: ${inlineUntrusted(problem, 240)}. A per-tool safety-axis declaration is the ` +
+        `caller's trust root for the approval gate, so it is refused rather than partly applied — dropping one key or defaulting one word ` +
+        `would leave a declaration that reads as in force while it is not.`);
+}

package/dist/core/mcp.d.ts

@@ -1,4 +1,4 @@
-import { type McpInstructionsEntry, type PromptSectionSeat } from "./prompt-section-seat.js";
+import { type McpInstructionsEntry, type PromptSectionDisposer } from "./prompt-section-seat.js";
 import { McpConnectionPool } from "./mcp-connection-pool.js";
 import { type McpDelivered, type McpFailureKind, type McpServerLiveness } from "./mcp-failure.js";
 import type { AgentTool } from "../internal/harness-types.js";
@@ -101,7 +101,7 @@ export interface MaterializedMcp {
     toolAxes: McpToolAxis[];
     /**
      * MCP server `instructions` (design/64 §17.3, CC `# MCP Server Instructions`): the optional guidance a
-     * connected server returns from `initialize`, after the host's disposition (`PromptProvider.section`,
+     * connected server returns from `initialize`, after the host's disposition (the `prompt.section` station,
      * applied once at the dial: a dropped entry is absent, a replaced one carries `author: "host"`). The
      * Runner injects these into the (stable) system prompt. One entry per server whose entry survived.
      */
@@ -110,14 +110,15 @@ export interface MaterializedMcp {
      * G1 通告层续批 (CC `mcp_instructions_delta` parity) — the run-scoped instruction-delta ref the run
      * loop drains at turn boundaries (`spec.attachments.mcpInstructions` opt-in; `newTools` consumption
      * discipline: drained only when the announcement survived the byte cap intact).
-     * - `pendingRemovals`: an INSTRUCTION-BEARING server whose transport closed mid-task (the CC
-     *   "servers have disconnected — their instructions above no longer apply" copy is instruction-scoped,
-     *   so instruction-less servers are not tracked). `dispose()` disarms first: task teardown is not a
-     *   disconnect.
-     * - `pendingAdds`: the CC add lane ("# MCP Server Instructions" reminder). Structurally present for a
-     *   dynamic mid-task connect face; TODAY nothing populates it — sema connects all servers at prepare
-     *   and carries their initial instructions in the stable system prompt (design/64 §17.3, deliberate
-     *   CC deviation: prefix-cache-correct).
+     * - `pendingRemovals`: a server whose instructions are in the model's context and whose transport closed
+     *   mid-task, or whose re-dial failed (the CC "servers have disconnected — their instructions above no
+     *   longer apply" copy names only what the model holds — the lane's ledger, `instructionsTold`).
+     *   `dispose()` disarms first: task teardown is not a disconnect.
+     * - `pendingAdds`: the CC add lane ("# MCP Server Instructions" reminder). A server's INITIAL
+     *   instructions ride the stable system prompt instead (design/64 §17.3, deliberate CC deviation:
+     *   prefix-cache-correct); this lane carries what comes later — a re-dial queues its new
+     *   connection's text here, and a run adds the text of a server it is to teach and has not told.
+     * A materialization alone takes every entry of `serverInstructions` as taught; a run states its block.
      */
     instructionsDelta: {
         pendingAdds: McpInstructionsEntry[];
@@ -163,7 +164,7 @@ export interface MaterializedMcp {
     droppedTools: McpDroppedTool[];
     /**
      * design/99 §E9 — per-server status, a PURE PROJECTION of THIS materialization (no new connection logic).
-     * One entry per declared server. **Semantics = the moment of this task leg's materialize** — core never
+     * One entry per declared server DIALED (none for one `dialable` kept from the dial). **Semantics = the moment of this task leg's materialize** — core never
      * persists MCP connections, so it is "did this leg connect", NOT a live session-health signal between tasks.
      * A consumer (service) surfacing it as session status must understand that. `toolNames` are the namespaced
      * (`<server>__<tool>`) names exposed.
@@ -178,7 +179,7 @@ export interface MaterializedMcp {
     /**
      * RefreshMcpTools (CC 2.1.218 parity, anchored to the CLI form) — re-read the tool list of one server (or
      * every CONNECTED server when `server` is omitted) over the EXISTING connection. NEVER dials or
-     * re-dials: a dead/never-connected server reports `not_connected`; a live listTools failure
+     * re-dials: a dead/never-connected server reports `not_connected` (so does one whose connection closed while the walk was reading); a live listTools failure
      * reports `failed` (the connection is left as-is). A refreshed entry carries the NEW intake
      * result (tools/axes/dropped — the same schema-gate/namespacing/axis pipeline as connect) plus
      * the added/removed namespaced tool names relative to the previous listing; the caller (the
@@ -229,6 +230,7 @@ export interface McpRefreshResult {
      *  contact it (no tools/list round trip; the engine must not hand a severed server a request
      *  channel or splice its post-revocation text into the model catalog). */
     status: "refreshed" | "not_connected" | "failed" | "revoked";
+    /** The same reading as {@link McpReconnectResult.toolCount}: the server's tools the producer holds after the call. */
     toolCount: number;
     added: string[];
     /**
@@ -243,6 +245,9 @@ export interface McpRefreshResult {
     tools?: AgentTool[];
     axes?: McpToolAxis[];
     dropped?: McpDroppedTool[];
+    /** On a `"refreshed"` entry whose connection carries instructions: that connection's entry as its dial disposed of it (`author: "host"` when replaced) —
+     *  a refresh re-reads tools, never instructions; a run whose roster change first leaves something of the server teaches it. */
+    instructions?: McpInstructionsEntry;
     /**
      * Set on `not_connected` / `failed` / `revoked`; ALSO set on a `"refreshed"` entry whose listing walk
      * did not finish (see {@link listingIncomplete}) — a refresh that produced usable tools is not a
@@ -287,12 +292,14 @@ export interface McpReconnectResult {
     /** Why, on every non-`reconnected` outcome (neutralized + bounded when it embeds remote text).
      *  Never the only machine-readable fact: see {@link status}. */
     reason?: string;
+    /** How many of the server's tools the producer holds after the call — its roster: the run's (the valve and the deployment's
+     *  overlay applied) for the run handle's `reconnectMcpServer`, this materialization's own handles for `MaterializedMcp.reconnect`
+     *  (no run). A name no server is declared under holds nothing. Equal to `tools.length` whenever `tools` is present. */
     toolCount: number;
-    /** Namespaced names this re-dial added / took away relative to what the server had mounted a moment
-     *  ago — a first successful dial adds its whole roster, a failed dial removes it. */
+    /** The namespaced names that came onto / left that roster (a first dial adds its whole roster, a failed dial removes it). */
     added: string[];
     removed: string[];
-    /** See the type docstring: present iff this result asserts a roster for `prefix`. */
+    /** See the type docstring: present iff this result asserts a roster for `prefix` — and then it is that roster's tools of the server. */
     tools?: AgentTool[];
     axes?: McpToolAxis[];
     dropped?: McpDroppedTool[];
@@ -443,11 +450,15 @@ export declare const MCP_IDLE_TIMEOUT_HTTP_DEFAULT_MS: number;
  *  `MCP_IDLE_TIMEOUT_HTTP`, else the CC-matched default). Exported for tests. */
 export declare function mcpIdleTimeoutMs(kind: "stdio" | "http"): number;
 /**
- * Startup-phase (connect + initial listTools) timeout override in ms (env `MCP_TIMEOUT`); undefined keeps
- * the SDK default. Startup deliberately stays bounded: a hung server at materialize time should fail open
- * into a skipped-server warning quickly, not stall task preparation indefinitely.
+ * Startup-phase (connect + initial listTools) timeout override in ms; undefined keeps the SDK default. Startup
+ * deliberately stays bounded: a hung server at materialize time should fail open into a skipped-server warning
+ * quickly, not stall task preparation indefinitely. THE one reader of the knob: with a `server`, that
+ * declaration's own `startupTimeoutMs` wins over env `MCP_TIMEOUT` (typed data held to the env knob's range
+ * [{@link MCP_ENV_MS_MIN}, {@link MCP_ENV_MS_MAX}], but REFUSED outside it — `config.mcp_startup_timeout_invalid`
+ * — where a process string is clamped and announced); without one, the process-level bound alone. The env value
+ * is resolved either way, so a bad one is announced even when a declaration shadows it.
  */
-export declare function mcpStartupTimeoutMs(): number | undefined;
+export declare function mcpStartupTimeoutMs(server?: Pick<McpServerSpec, "name" | "startupTimeoutMs">): number | undefined;
 /** The protocol-range condition name for a JSON-RPC error code, or `undefined` for every other code
  *  (see {@link MCP_SPEC_ERROR_CODE_NAMES}). */
 export declare function describeMcpSpecErrorCode(code: unknown): string | undefined;
@@ -605,7 +616,7 @@ reminderDisclosure?: {
 }, poolOpts?: {
     pool: McpConnectionPool;
     ownsPool?: boolean;
-}, promptSections?: PromptSectionSeat): Promise<MaterializedMcp>;
+}, promptSections?: PromptSectionDisposer, dialable?: (spec: McpServerSpec) => boolean): Promise<MaterializedMcp>;
 /**
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.
  * Unlike server hints, the caller may RAISE or LOWER any axis: `effect` sets the repeat-safety class (lower to

package/dist/core/mcp.js

@@ -7,7 +7,7 @@ import { disposeSectionEntry, sectionAnswerWarning } from "./prompt-section-seat
 import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName, normalizeNameSegment } from "./protocol-naming.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { McpConnectionPool } from "./mcp-connection-pool.js";
-import { MCP_RESOURCE_LIST_ALLOW, MCP_RESOURCE_READ_ALLOW } from "./mounted-mcp.js";
+import { LIST_MCP_RESOURCES, MCP_RESOURCE_LIST_ALLOW, MCP_RESOURCE_READ_ALLOW, READ_MCP_RESOURCE, READ_MCP_RESOURCE_DIR, retractInstructions, tellInstructions, toldOnDial, unretractInstructions, withdrawInstructionAdds } from "./mounted-mcp.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import { classifyMcpFailure, describeHttpTransportFailure, livenessOf } from "./mcp-failure.js";
@@ -154,8 +154,14 @@ function armMcpIdleWatchdog(health, idleMs, outerSignal) {
         },
     };
 }
-export function mcpStartupTimeoutMs() {
-    return parseEnvMs("MCP_TIMEOUT");
+export function mcpStartupTimeoutMs(server) {
+    const fromEnv = parseEnvMs("MCP_TIMEOUT");
+    const own = server?.startupTimeoutMs;
+    if (server === undefined || own === undefined)
+        return fromEnv;
+    if (typeof own === "number" && Number.isSafeInteger(own) && own >= MCP_ENV_MS_MIN && own <= MCP_ENV_MS_MAX)
+        return own;
+    throw Object.assign(new Error(`MCP server "${inlineUntrusted(server.name, 160)}": startupTimeoutMs must be a whole number of milliseconds from ${MCP_ENV_MS_MIN} to ${MCP_ENV_MS_MAX} (got ${typeof own === "number" ? String(own) : own === null ? "null" : typeof own}) — not dialed`), { code: "config.mcp_startup_timeout_invalid" });
 }
 function markMcpFailure(e, details) {
     e.details = details;
@@ -656,11 +662,11 @@ export function mcpToolSchemaProblem(schema) {
     }
     return undefined;
 }
-export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections) {
+export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations, poolOpts, promptSections, dialable) {
     const snapshot = snapshotMcpEntries(specs);
     const axesRefused = new WeakMap();
     const entries = snapshot.map((spec) => {
-        const judged = judgeEntryToolAxes(spec);
+        const judged = judgeEntryToolAxes(spec, "mcp");
         if (judged.ok)
             return judged.entry;
         axesRefused.set(spec, judged.error);
@@ -725,7 +731,6 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             serverHandles.push(handle);
         else
             serverHandles[hIdx] = handle;
-        const hasInstructions = s.instructions !== undefined;
         const observe = (outcome) => {
             if (disposing)
                 return;
@@ -739,8 +744,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 return;
             s.status.transportClosed = true;
             observe("connection_closed");
-            if (hasInstructions)
-                instructionsDelta.pendingRemovals.push(spec.name);
+            retractInstructions(instructionsDelta, spec.name);
         };
         s.announce.fn = announceClose;
         if (s.health.dead)
@@ -786,41 +790,32 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
         return refusal !== undefined ? Promise.reject(refusal) : connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked, dialKind, poolOpts?.pool, dialOpts);
     };
     const prefixOf = (name) => mintNamespacePrefix(MCP_NAMESPACE, name);
-    const reconcileInstructions = (name, before, after, connected) => {
-        let owedRemoval = false;
-        for (let i = instructionsDelta.pendingRemovals.length - 1; i >= 0; i--) {
-            if (instructionsDelta.pendingRemovals[i] !== name)
-                continue;
-            instructionsDelta.pendingRemovals.splice(i, 1);
-            owedRemoval = true;
-        }
-        let hadPendingAdd = false;
-        for (let i = instructionsDelta.pendingAdds.length - 1; i >= 0; i--) {
-            if (instructionsDelta.pendingAdds[i].server !== name)
-                continue;
-            instructionsDelta.pendingAdds.splice(i, 1);
-            hadPendingAdd = true;
-        }
-        if (after !== undefined) {
-            instructionsDelta.pendingAdds.push(after);
-            return;
-        }
-        if (connected)
-            return;
-        if (before !== undefined || owedRemoval || hadPendingAdd)
-            instructionsDelta.pendingRemovals.push(name);
+    const heldCount = (name) => serverHandles.find((h) => h.name === name)?.tools.length ?? 0;
+    const reconcileInstructions = (name, after, connected) => {
+        if (!connected)
+            return retractInstructions(instructionsDelta, name);
+        unretractInstructions(instructionsDelta, name);
+        if (after !== undefined)
+            tellInstructions(instructionsDelta, after);
+        else
+            withdrawInstructionAdds(instructionsDelta, name);
     };
-    const settled = await Promise.allSettled(entries.map((spec, i) => dialServer(spec, dialKinds[i], { sections: promptSections })));
+    const dialed = entries.map((spec) => dialDecision(dialable, spec));
+    const settled = await Promise.allSettled(entries.map((spec, i) => (dialed[i] ? dialServer(spec, dialKinds[i], { sections: promptSections }) : Promise.resolve(null))));
     try {
         for (let i = 0; i < entries.length; i++) {
             const r = settled[i];
             const spec = entries[i];
             if (r.status === "fulfilled") {
                 const s = r.value;
+                if (s === null)
+                    continue;
                 tools.push(...s.tools);
                 toolAxes.push(...s.axes);
-                if (s.instructions)
+                if (s.instructions) {
                     serverInstructions.push(s.instructions);
+                    toldOnDial(instructionsDelta, spec.name);
+                }
                 commitConnectedServer(spec, s, dialKinds[i]);
             }
             else {
@@ -835,12 +830,12 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
         toolAxes.push(...resourceTools.axes);
     }
     catch (mergeErr) {
-        await Promise.allSettled(settled.map((r) => (r.status === "fulfilled" ? r.value.close() : Promise.resolve())));
+        await Promise.allSettled(settled.map((r) => (r.status === "fulfilled" && r.value !== null ? r.value.close() : Promise.resolve())));
         throw mergeErr;
     }
     const redialOnce = async (server) => {
         const prefix = prefixOf(server);
-        const declined = (outcome, reason) => ({ server, prefix, outcome, reason, toolCount: 0, added: [], removed: [] });
+        const declined = (outcome, reason) => ({ server, prefix, outcome, reason, toolCount: heldCount(server), added: [], removed: [] });
         if (disposing)
             return declined("refused", "this materialization is being disposed — the task is tearing down");
         const spec = entries.find((e) => e.name === server);
@@ -855,7 +850,6 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             const hIdx = serverHandles.findIndex((h) => h.name === server);
             const prior = hIdx === -1 ? undefined : serverHandles[hIdx];
             const priorNames = prior ? prior.tools.map((t) => t.name) : [];
-            const priorInstructions = prior?.instructions;
             if (prior) {
                 prior.announce.fn = undefined;
                 prior.health.observe = undefined;
@@ -880,7 +874,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     statuses[sIdx] = status;
                 const raised = asServerWarning(spec, err);
                 warnings.push(raised);
-                reconcileInstructions(server, priorInstructions, undefined, false);
+                reconcileInstructions(server, undefined, false);
                 return {
                     server,
                     prefix,
@@ -901,7 +895,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 return declined("refused", "this materialization was disposed while the re-dial was in flight — the new connection was closed");
             }
             const raised = commitConnectedServer(spec, connected, dialKind);
-            reconcileInstructions(server, priorInstructions, connected.instructions, true);
+            reconcileInstructions(server, connected.instructions, true);
             const newNames = connected.tools.map((t) => t.name);
             return {
                 server,
@@ -938,11 +932,11 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
             }
             for (const h of targets) {
                 if (disposing || h.health.dead) {
-                    results.push({ server: h.name, prefix: prefixOf(h.name), status: "not_connected", toolCount: 0, added: [], removed: [] });
+                    results.push({ server: h.name, prefix: prefixOf(h.name), status: "not_connected", toolCount: h.tools.length, added: [], removed: [] });
                     continue;
                 }
                 if (isServerRevoked(h.name)) {
-                    results.push({ server: h.name, prefix: prefixOf(h.name), status: "revoked", toolCount: 0, added: [], removed: [], error: "server revoked by the operator — the refresh did not contact it" });
+                    results.push({ server: h.name, prefix: prefixOf(h.name), status: "revoked", toolCount: h.tools.length, added: [], removed: [], error: "server revoked by the operator — the refresh did not contact it" });
                     continue;
                 }
                 try {
@@ -969,6 +963,7 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                         tools: serverTools,
                         axes: serverAxes,
                         dropped: dropped.map((d) => ({ server: inlineUntrusted(h.name, 160), ...d })),
+                        ...(h.instructions !== undefined ? { instructions: h.instructions } : {}),
                         ...(listed.incomplete !== undefined
                             ? { listingIncomplete: listed.incomplete, error: `tool listing incomplete — ${listingIncompleteNote(listed.incomplete)}` }
                             : {}),
@@ -991,17 +986,14 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                 const entry = results[i];
                 if (entry.status !== "refreshed")
                     continue;
-                if (serverHandles.find((h) => h.name === entry.server)?.tools === entry.tools)
+                const live = serverHandles.find((h) => h.name === entry.server);
+                if (live !== undefined && live.tools === entry.tools && !live.health.dead)
                     continue;
-                results[i] = {
-                    server: entry.server,
-                    prefix: entry.prefix,
-                    status: "failed",
-                    toolCount: 0,
-                    added: [],
-                    removed: [],
-                    error: "this server was re-dialed while the refresh was reading another server — the listing is from the connection that re-dial replaced, so it was discarded",
-                };
+                const kept = { server: entry.server, prefix: entry.prefix, toolCount: heldCount(entry.server), added: [], removed: [] };
+                results[i] =
+                    live?.tools === entry.tools
+                        ? { ...kept, status: "not_connected" }
+                        : { ...kept, status: "failed", error: "this server was re-dialed while the refresh was reading another server — the listing is from the connection that re-dial replaced, so it was discarded" };
             }
             return results;
         },
@@ -1050,9 +1042,6 @@ export function applyCallerAxisOverride(name, hint, override) {
         axis.irreversibility = irrev;
     return axis.effect !== undefined || axis.egress !== undefined || axis.irreversibility !== undefined ? axis : undefined;
 }
-const LIST_MCP_RESOURCES = "ListMcpResourcesTool";
-const READ_MCP_RESOURCE = "ReadMcpResourceTool";
-const READ_MCP_RESOURCE_DIR = "ReadMcpResourceDirTool";
 const MCP_SKILLS_EXTENSION = "io.modelcontextprotocol/skills";
 const MAX_DIR_READ_PAGES = 20;
 const DIR_READ_NOT_A_DIRECTORY_RE = /not a directory|isn'?t a directory|not a folder/i;
@@ -1540,7 +1529,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
     const elicitOn = spec.elicitation === true && onElicit !== undefined;
     const health = { dead: false, pendingElicitations: 0, lastElicitationClosedAt: 0 };
     const announce = {};
-    const startupMs = mcpStartupTimeoutMs();
+    const startupMs = mcpStartupTimeoutMs(spec);
     const startupOpts = startupMs !== undefined ? { timeout: startupMs } : undefined;
     const dialClient = async () => {
         const client = new Client({ name: `sema-core/${spec.name}`, version: "0.1.0" }, { capabilities: elicitOn ? { elicitation: { form: {} } } : {} });
@@ -1574,7 +1563,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         }
         return client;
     };
-    const lease = pool !== undefined && !elicitOn ? await pool.acquire(McpConnectionPool.keyOf(spec, principal, transportKind), dialClient, dialOpts) : undefined;
+    const lease = pool !== undefined && !elicitOn ? await pool.acquire(McpConnectionPool.keyOf(spec, principal, transportKind, startupMs), dialClient, dialOpts) : undefined;
     const client = lease !== undefined ? lease.client : await dialClient();
     const close = () => (lease !== undefined ? lease.release() : client.close());
     const openListing = () => {
@@ -1603,7 +1592,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             : undefined;
         const rawInstructions = client.getInstructions();
         const sanitized = rawInstructions && rawInstructions.trim() ? sanitizeUntrustedText(rawInstructions.trim()) : undefined;
-        const disposed = sanitized === undefined ? undefined : disposeSectionEntry(dialOpts?.sections, { section: "core/discovery.mcp-instructions", server: spec.name, text: sanitized, mountedTools: serverTools.map((t) => t.name) });
+        const disposed = sanitized === undefined ? undefined : await disposeSectionEntry(dialOpts?.sections, { section: "core/discovery.mcp-instructions", server: spec.name, text: sanitized, mountedTools: serverTools.map((t) => t.name) });
         const instructions = disposed?.kept === undefined ? undefined : { server: spec.name, ...disposed.kept };
         const info = client.getServerVersion();
         const status = {
@@ -1832,6 +1821,27 @@ function asServerWarning(spec, err) {
     warning.code = "mcp.server_unavailable";
     return warning;
 }
+function dialDecision(dialable, spec) {
+    if (dialable === undefined)
+        return true;
+    let why;
+    let cause;
+    try {
+        const answer = dialable(spec);
+        if (typeof answer === "boolean")
+            return answer;
+        const thenable = typeof answer?.then === "function";
+        if (thenable)
+            Promise.resolve(answer).catch(() => undefined);
+        const kind = typeof answer;
+        why = `it answered ${thenable ? "a promise (the seat is synchronous)" : answer === null || answer === undefined ? String(answer) : `${/^[aeiou]/.test(kind) ? "an" : "a"} ${kind}`}, not a boolean`;
+    }
+    catch (e) {
+        why = thrownText(e);
+        cause = { cause: e };
+    }
+    throw Object.assign(new Error(`MCP materialization refused: the dialable seat could not decide whether to dial server "${inlineUntrusted(spec.name, 120)}" — ${inlineUntrusted(why, 240)}. No server was dialed.`, cause), { code: "config.mcp_dialable_failed" });
+}
 function sanitizedCause(err) {
     const copy = new Error(namedMcpFailureText(err));
     const name = thrownName(err);