@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/mods/stations.js

@@ -0,0 +1,437 @@
+import { types } from "node:util";
+import { resolveModel } from "../roles.js";
+import { brainToRuntime } from "../runtime.js";
+import { deliverEngineNotice } from "../engine-notice.js";
+import { inlineUntrusted } from "../untrusted-text.js";
+import { extensionWords } from "../untrusted-egress.js";
+import { askApproverIdentity, describeThrown, ownArgs } from "../tool-policy.js";
+import { admitMods, expandModPattern } from "./kernel/index.js";
+import { validateOverlay } from "../../prompt-assembly/overlay.js";
+import { modsInvalid } from "./kernel/registration.js";
+import { isPlainRecord } from "./kernel/receive.js";
+import { engineMethodBottoms } from "./dollar.js";
+import { modSeatsOf, modsReportToOnError, registrationRefusedNotice } from "./host.js";
+export const ENGINE_CORE_ANSWER = Object.freeze({});
+export function engineCore() {
+    return ENGINE_CORE_ANSWER;
+}
+export function agentIdOf(identity) {
+    return identity?.isDelegatedChild === true ? identity.taskId : undefined;
+}
+export function stopEventOf(identity) {
+    return identity?.isDelegatedChild === true ? "classic.SubagentStop" : "classic.Stop";
+}
+export function judgedInputOf(args) {
+    const owned = ownArgs(args);
+    return owned.ok ? owned.value : args;
+}
+export function admittedChainOf(bus, spec, deps) {
+    const offered = new Map();
+    for (const r of [...(deps.mods ?? []), ...(spec.mods ?? [])])
+        offered.set(r.name, r);
+    const hung = bus.mounted();
+    const links = [];
+    for (const rec of bus.records) {
+        if ("refusedBy" in rec)
+            continue;
+        const registration = offered.get(rec.name);
+        if (registration !== undefined)
+            links.push(Object.freeze({ registration, handlers: Object.freeze(hung.filter((h) => h.plugin === rec.name)) }));
+    }
+    return Object.freeze(links);
+}
+const ADMITTED_CHAINS = new WeakMap();
+function recordAdmittedChain(bus, seats) {
+    const chain = admittedChainOf(bus, { ...(seats.task !== undefined ? { mods: [...seats.task] } : {}) }, { ...(seats.deployment !== undefined ? { mods: [...seats.deployment] } : {}) });
+    ADMITTED_CHAINS.set(bus, chain);
+    return chain;
+}
+export function chainOfBus(bus) {
+    return ADMITTED_CHAINS.get(bus);
+}
+const sameMatcher = (a, b) => {
+    if (a === undefined || b === undefined)
+        return a === b;
+    const ka = Object.keys(a).sort();
+    const kb = Object.keys(b).sort();
+    return ka.length === kb.length && ka.every((k, i) => k === kb[i] && a[k] === b[k]);
+};
+const sameHandler = (a, b) => a.seat === b.seat && a.pattern === b.pattern && a.observe === b.observe && a.caught === b.caught && sameMatcher(a.matcher, b.matcher);
+function sameModLink(a, b) {
+    return a.registration === b.registration && a.handlers.length === b.handlers.length && a.handlers.every((h, j) => sameHandler(h, b.handlers[j]));
+}
+export function sameModChain(a, b) {
+    return a.length === b.length && a.every((l, i) => sameModLink(l, b[i]));
+}
+const judgesCall = (p) => !p.observe;
+export function chainJudges(bus) {
+    return bus.hasHandlers("classic.PreToolUse", judgesCall) || bus.hasHandlers("tool.check", judgesCall);
+}
+const SCREENING_CHAINS = new WeakMap();
+export function recordScreeningChain(policy, chain) {
+    SCREENING_CHAINS.set(policy, chain);
+}
+export function screeningChainOf(policy) {
+    return SCREENING_CHAINS.get(policy);
+}
+export function sameInstallation(pc, leg) {
+    const bus = screeningChainOf(pc.policy);
+    const chain = bus !== undefined ? chainOfBus(bus) : undefined;
+    return (chain !== undefined &&
+        sameModChain(chain, leg.chain) &&
+        askApproverIdentity(pc.onAsk) === askApproverIdentity(leg.onAsk) &&
+        (pc.durableMandate === true) === leg.durableMandate &&
+        (pc.contentMandate === true) === leg.contentMandate &&
+        pc.hookEnv === leg.hookEnv &&
+        pc.autoMode?.decider === leg.decider);
+}
+export function standsInFor(pc, leg, legChainJudges) {
+    return legChainJudges && sameInstallation(pc, { ...leg, durableMandate: false, contentMandate: false });
+}
+const judgesToolCheck = (h) => {
+    const selected = expandModPattern(h.pattern);
+    return !h.observe && "names" in selected && selected.names.includes("tool.check");
+};
+export function screeningInstallationsOf(entries) {
+    return entries.flatMap((pc) => {
+        const bus = screeningChainOf(pc.policy);
+        return bus !== undefined || pc.mods !== undefined ? [{ bus, chain: pc.mods }] : [];
+    });
+}
+export function unraisableGuardsOf(installations) {
+    const guards = installations.flatMap((i) => (i.bus !== undefined ? [] : (i.chain ?? []).filter((l) => l.handlers.some(judgesToolCheck)).map((l) => `"${inlineUntrusted(l.registration.name, 80)}"`)));
+    return guards.length === 0 ? undefined : `an inherited screening entry names the tool.check guard of ${guards.join(", ")}, but its policy is not one createPreToolUseConstraintPolicy minted, so the guard has no chain to judge this leg's calls on — hand the minted policy back as it is`;
+}
+const judges = (p) => judgesCall(p);
+export function inheritedToolChecks(entries, standsIn, settleOf) {
+    const unraisable = unraisableGuardsOf(screeningInstallationsOf(entries));
+    if (unraisable !== undefined)
+        throw modsInvalid(unraisable);
+    const checks = [];
+    for (const pc of entries) {
+        const bus = screeningChainOf(pc.policy);
+        if (bus === undefined || standsIn(pc) || !bus.hasHandlers("tool.check", judges))
+            continue;
+        checks.push(Object.freeze({ bus, judges, settle: settleOf(pc) }));
+    }
+    return Object.freeze(checks);
+}
+export function classicEventBase(identity, permissionMode) {
+    const agentId = agentIdOf(identity);
+    return {
+        ...(identity !== undefined ? { identity } : {}),
+        ...(agentId !== undefined ? { agentId } : {}),
+        ...(permissionMode !== undefined ? { permissionMode } : {}),
+    };
+}
+export async function observeClassic(bus, event, e, signal) {
+    if (!bus.hasHandlers(event))
+        return;
+    try {
+        await bus.dispatch(event, e, { bottom: engineCore, ...(signal !== undefined ? { signal } : {}) });
+    }
+    catch {
+    }
+}
+export async function dispatchClassic(bus, event, e, options) {
+    if (!bus.hasHandlers(event))
+        return undefined;
+    const check = options.checkAnswer;
+    return await bus.dispatch(event, e, {
+        bottom: engineCore,
+        ...(options.signal !== undefined ? { signal: options.signal } : {}),
+        ...(check !== undefined ? { checkAnswer: (a) => (a === ENGINE_CORE_ANSWER ? undefined : check(a)) } : {}),
+    });
+}
+export function stringMembersAnswer(event, members) {
+    return (answer) => {
+        if (answer === null || answer === false)
+            return undefined;
+        if (typeof answer !== "object")
+            return `answered ${typeof answer}; ${event} takes { ${members.map((m) => `${m}?`).join(", ")} }`;
+        for (const m of members) {
+            const v = Reflect.get(answer, m);
+            if (v !== undefined && typeof v !== "string")
+                return `answered a ${typeof v} "${m}"; it is a string`;
+        }
+        return undefined;
+    };
+}
+export function stringMembersOf(answer, members) {
+    const out = {};
+    if (typeof answer !== "object" || answer === null)
+        return out;
+    for (const m of members) {
+        const v = Reflect.get(answer, m);
+        if (typeof v === "string")
+            out[m] = v;
+    }
+    return out;
+}
+const FAILURE_CLAUSE = Object.freeze({
+    threw: (who, why) => `crashed (extension "${who}" ${why})`,
+    timeout: (who, why) => `did not answer (extension "${who}" ${why})`,
+    violation: (who, why) => `gave an answer the station cannot take (extension "${who}" ${why})`,
+    reentry: (who, why) => `was skipped on re-entry and its .catch did not answer (extension "${who}" ${why})`,
+});
+export function failedHandlerClause(f) {
+    return FAILURE_CLAUSE[f.cause](extensionWords(f.registration, 80), extensionWords(f.reason, 200));
+}
+export async function observePermissionDenied(input) {
+    const { payload, hostObserver } = input;
+    const e = { ...payload, ...classicEventBase(payload.identity, payload.permissionMode) };
+    if (input.legBus?.hasHandlers("classic.PermissionDenied") === true)
+        await observeClassic(input.legBus, "classic.PermissionDenied", e, input.signal);
+    if (hostObserver === undefined)
+        return;
+    const own = await admitModChain({
+        deployment: [
+            {
+                name: "toolGate.permissionDenied",
+                tier: "user",
+                uses: { events: ["classic.PermissionDenied"], calls: [] },
+                register: (on) => on("classic.PermissionDenied", async () => void (await hostObserver(payload)), { observe: true }),
+            },
+        ],
+    }, input.onHostObserverFailure);
+    await observeClassic(own, "classic.PermissionDenied", e, input.signal);
+}
+export async function screenUserPrompt(bus, e, signal) {
+    let outcome;
+    try {
+        outcome = await dispatchClassic(bus, "classic.UserPromptSubmit", e, {
+            ...(signal !== undefined ? { signal } : {}),
+            checkAnswer: stringMembersAnswer("classic.UserPromptSubmit", ["block", "additionalContext"]),
+        });
+    }
+    catch (err) {
+        return { kind: "failed", registration: "engine", cause: "threw", reason: `could not raise the screen: ${describeThrown(err)}`, skipped: [] };
+    }
+    if (outcome === undefined)
+        return undefined;
+    if (outcome.kind !== "answered")
+        return outcome;
+    return { kind: "answered", ...stringMembersOf(outcome.answer, ["block", "additionalContext"]) };
+}
+export const TOOL_CHECK_DECISIONS = Object.freeze(["allow", "ask", "deny"]);
+const isToolCheckDecision = (v) => TOOL_CHECK_DECISIONS.some((d) => d === v);
+function readToolCheckAnswer(answer) {
+    if (typeof answer !== "object" || answer === null)
+        return `answered ${answer === null ? "null" : typeof answer}; tool.check takes { decision, reason? }`;
+    const decision = Reflect.get(answer, "decision");
+    const reason = Reflect.get(answer, "reason");
+    if (!isToolCheckDecision(decision))
+        return `no { decision } (one of ${TOOL_CHECK_DECISIONS.join(", ")})`;
+    if (reason !== undefined && typeof reason !== "string")
+        return `answered a ${typeof reason} "reason"; it is a string`;
+    return { decision, ...(reason !== undefined ? { reason } : {}) };
+}
+export async function raiseToolCheck(bus, e, projection, signal, judges) {
+    if (!bus.hasHandlers("tool.check", judges))
+        return undefined;
+    let outcome;
+    try {
+        outcome = await bus.dispatch("tool.check", e, {
+            bottom: () => projection,
+            ...(judges !== undefined ? { participant: judges } : {}),
+            ...(signal !== undefined ? { signal } : {}),
+            checkAnswer: (a) => {
+                const read = readToolCheckAnswer(a);
+                return typeof read === "string" ? read : undefined;
+            },
+        });
+    }
+    catch (err) {
+        return { kind: "failed", registration: "engine", cause: "threw", reason: `could not raise the check: ${describeThrown(err)}`, skipped: [] };
+    }
+    if (outcome.kind !== "answered")
+        return outcome;
+    const read = readToolCheckAnswer(outcome.answer);
+    if (typeof read === "string")
+        return { kind: "failed", registration: outcome.answeredBy ?? "engine", cause: "violation", reason: read, skipped: outcome.skipped };
+    return { kind: "answered", ...read, ...(outcome.answeredBy !== undefined ? { by: outcome.answeredBy } : {}) };
+}
+const NO_COMPOSE = Object.freeze({ deploy: Object.freeze([]), task: Object.freeze([]), warnings: Object.freeze([]) });
+function composeOverlaysOf(answer) {
+    if (!isPlainRecord(answer)) {
+        return `answered ${answer === null ? "null" : Array.isArray(answer) ? "an array" : typeof answer === "object" ? "an object that is not a plain record" : typeof answer}; prompt.compose takes a plain { overlays }`;
+    }
+    const stray = Object.keys(answer).filter((k) => k !== "overlays");
+    if (stray.length > 0)
+        return `the answer carries ${stray.slice(0, 5).map((k) => JSON.stringify(extensionWords(k, 40))).join(", ")} (overlays only)`;
+    const overlays = answer["overlays"];
+    return Array.isArray(overlays) && Object.getPrototypeOf(overlays) === Array.prototype ? overlays : "the answer's overlays is not an ordinary array";
+}
+export async function raisePromptCompose(bus, e, options) {
+    if (!bus.hasHandlers("prompt.compose"))
+        return NO_COMPOSE;
+    const sourceOf = (seat) => (seat === "deployment" ? "deploy" : "task");
+    const bottom = Object.freeze({ overlays: Object.freeze([]) });
+    const taken = new WeakMap([[bottom, Object.freeze([])]]);
+    const HEAD = "the answer does not carry what next() returned unchanged at its head (a handler adds overlays; it never rewrites or removes another's)";
+    let outcome;
+    try {
+        outcome = await bus.dispatch("prompt.compose", e, {
+            bottom: () => bottom,
+            ...(options.signal !== undefined ? { signal: options.signal } : {}),
+            checkAnswer: (answer, _e, by, below) => {
+                if (typeof answer === "object" && answer !== null && taken.has(answer))
+                    return undefined;
+                const mine = composeOverlaysOf(answer);
+                if (typeof mine === "string")
+                    return mine;
+                const returned = below[below.length - 1];
+                const lower = typeof returned === "object" && returned !== null ? taken.get(returned) : undefined;
+                if (lower === undefined) {
+                    return below.length === 0
+                        ? "it answered without next(e) — prompt.compose collects: a handler awaits next(e) and adds after what it returned"
+                        : "next() is still running; prompt.compose answers after it";
+                }
+                if (mine.length < lower.length)
+                    return HEAD;
+                const out = [...lower];
+                for (let i = 0; i < mine.length; i++) {
+                    const under = lower[i];
+                    const v = validateOverlay(mine[i], { source: sourceOf(under?.by.seat ?? by.seat), event: "prompt.compose", lowerAdds: options.lowerAdds });
+                    if (under !== undefined) {
+                        if ("violation" in v || JSON.stringify(v.overlay) !== JSON.stringify(under.overlay))
+                            return HEAD;
+                        continue;
+                    }
+                    if ("violation" in v)
+                        return v.violation;
+                    out.push(Object.freeze({ overlay: v.overlay, by: Object.freeze({ plugin: by.plugin, seat: by.seat }) }));
+                }
+                taken.set(answer, Object.freeze(out));
+                return undefined;
+            },
+        });
+    }
+    catch (err) {
+        return { deploy: [], task: [], warnings: [`prompt.compose could not be raised (${describeThrown(err)}); no mods overlay applies this run`] };
+    }
+    const warnings = (outcome.kind === "aborted" ? [] : outcome.skipped).map((s) => `prompt.compose: extension "${extensionWords(s.registration, 80)}" ${s.cause === "violation" ? "gave an answer the station cannot take" : s.cause}: ${extensionWords(s.reason, 300)} — that answer is skipped; what is below it stands`);
+    if (outcome.kind !== "answered")
+        return { deploy: [], task: [], warnings };
+    const answer = outcome.answer;
+    const contributions = typeof answer === "object" && answer !== null ? taken.get(answer) : undefined;
+    if (contributions === undefined)
+        return { deploy: [], task: [], warnings: [...warnings, "prompt.compose: the chain's answer is not one the station took; no mods overlay applies this run"] };
+    const blocks = [];
+    for (const { overlay, by } of contributions) {
+        const item = { overlay, origin: { source: sourceOf(by.seat), by: by.plugin } };
+        const last = blocks[blocks.length - 1];
+        if (last !== undefined && last.by.plugin === by.plugin && last.by.seat === by.seat)
+            last.items.push(item);
+        else
+            blocks.push({ by, items: [item] });
+    }
+    const inChainOrder = blocks.reverse().flatMap((b) => b.items);
+    return {
+        deploy: Object.freeze(inChainOrder.filter((o) => o.origin.source === "deploy")),
+        task: Object.freeze(inChainOrder.filter((o) => o.origin.source === "task")),
+        warnings,
+    };
+}
+function lateView() {
+    let seats;
+    const need = (method) => {
+        if (seats === undefined)
+            throw new Error(`${method}: the engine facade is not available before the leg is prepared`);
+        return seats;
+    };
+    const view = {
+        env: { exec: (command, options) => need("process.run").exec(command, options) },
+        complete: (request, signal) => need("model.complete").complete(request, signal),
+        book: (reply) => need("model.complete").book(reply),
+        session: {
+            id: () => need("session.id").sessionId,
+            cwd: () => need("session.cwd").cwd(),
+            root: () => need("session.root").root(),
+            model: () => need("session.model").model(),
+            messages: () => need("session.messages").messages(),
+        },
+        now: () => need("clock.now").now(),
+        tools: () => need("tool.list").tools(),
+        agents: () => need("agent.list").agents(),
+    };
+    return {
+        view,
+        bind: (s) => {
+            seats = s;
+        },
+    };
+}
+export async function admitLegMods(input) {
+    const late = lateView();
+    const seats = modSeatsOf(input.spec, input.deps);
+    const bus = await admitMods({
+        side: "engine",
+        seats,
+        bottoms: engineMethodBottoms(late.view),
+        report: modsReportToOnError(input.deps.onError, input.sessionId),
+        describeThrown,
+        isProxy: types.isProxy,
+    });
+    for (const record of bus.records) {
+        if ("refusedBy" in record)
+            deliverEngineNotice(input.deps.onNotice, registrationRefusedNotice(record, input.sessionId));
+    }
+    return { bus, chain: recordAdmittedChain(bus, seats), bindFacade: late.bind };
+}
+function replyText(reply) {
+    return reply.content.flatMap((c) => (c.type === "text" ? [c.text] : [])).join("");
+}
+export function legFacadeSeats(input) {
+    const runtime = brainToRuntime(input.deps.brain);
+    const answeredBy = new Map();
+    const byUsage = new WeakMap();
+    return {
+        exec: (command, options) => input.executionEnv.exec(command, options),
+        complete: async (request, signal) => {
+            const model = request.model !== undefined ? resolveModel(request.model, input.deps.models) : input.model;
+            answeredBy.set(model.id, model);
+            const auth = await input.spec.getApiKeyAndHeaders?.(model);
+            const reply = await runtime.completeSimple(model, { ...request.context, messages: [...request.context.messages] }, { signal, maxTokens: request.maxTokens, ...(auth?.apiKey !== undefined ? { apiKey: auth.apiKey } : {}), ...(auth?.headers !== undefined ? { headers: auth.headers } : {}) });
+            if (reply.stopReason === "error" || reply.stopReason === "aborted")
+                throw new Error(`model.complete: ${reply.errorMessage ?? reply.stopReason}`);
+            if (reply.usage !== undefined)
+                byUsage.set(reply.usage, { model, ...(reply.diagnostics !== undefined ? { diagnostics: reply.diagnostics } : {}) });
+            return Object.freeze({ text: replyText(reply), model: model.id, ...(reply.usage !== undefined ? { usage: reply.usage } : {}) });
+        },
+        sessionId: input.sessionId,
+        book: (reply) => {
+            const seen = reply.usage !== undefined ? byUsage.get(reply.usage) : undefined;
+            const record = seen !== undefined && seen.model.id === reply.model ? seen : undefined;
+            const model = record?.model ?? answeredBy.get(reply.model);
+            if (model === undefined)
+                throw new Error(`model.complete: the reply names model "${reply.model}", which no call of this leg resolved; it is not booked`);
+            input.book(model, { usage: reply.usage, ...(record?.diagnostics !== undefined ? { diagnostics: record.diagnostics } : {}) });
+        },
+        cwd: () => input.cwdRef?.current ?? input.taskRoot,
+        root: () => input.taskRoot,
+        model: () => input.model.id,
+        messages: () => input.lastBrainContext()?.messages ?? [],
+        now: () => (input.deps.now ?? Date.now)(),
+        tools: () => [...input.activeTools],
+        agents: () => (input.agentListing?.entries ?? []).map((e) => e.name),
+    };
+}
+export async function admitModChain(seats, onError) {
+    const bus = await admitMods({
+        side: "engine",
+        seats,
+        bottoms: engineMethodBottoms(lateView().view),
+        report: (err) => {
+            try {
+                onError?.(err);
+            }
+            catch {
+            }
+        },
+        describeThrown,
+        isProxy: types.isProxy,
+    });
+    recordAdmittedChain(bus, seats);
+    return bus;
+}

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

@@ -10,9 +10,58 @@
 import type { McpServerSpec } from "./mcp-server-spec.js";
 import type { ToolContentOrigin } from "./tool-spec.js";
 import type { McpConnectionPool } from "./mcp-connection-pool.js";
+import type { McpInstructionsEntry } from "./prompt-section-seat.js";
 /** The two names a server's `allowTools` carries to let the cross-server resource readers reach its resources (a server whose allowlist omits one is left out of that reader). */
 export declare const MCP_RESOURCE_LIST_ALLOW = "list_resources";
 export declare const MCP_RESOURCE_READ_ALLOW = "read_resource";
+/** The canonical names of the resource tools (the trio: list-all / read-one / list-under-a-directory). They belong to no one server: each aggregates the resources of every connected server that advertises them. */
+export declare const LIST_MCP_RESOURCES = "ListMcpResourcesTool";
+export declare const READ_MCP_RESOURCE = "ReadMcpResourceTool";
+export declare const READ_MCP_RESOURCE_DIR = "ReadMcpResourceDirTool";
+/** Does the valve (`leaves`: its one predicate) leave at least one of the cross-server resource tools? While it does, a connected server may contribute to them whatever it lists. */
+export declare function resourceFacesLeft(leaves: (tool: {
+    readonly name: string;
+}) => boolean): boolean;
+/**
+ * Are a server's instructions about something the run holds? Yes when the run's roster (`held`) holds a tool of the server's prefix
+ * domain the valve leaves, or a cross-server resource tool the valve leaves (the aggregates exist only if some connected server
+ * advertised resources, and which one is not recorded, so a held face keeps the instructions of every server); a server whose own
+ * listing (`listed` — any superset of it) has no tool at all (instructions only) is taught while any resource face is left. Read off
+ * the roster, a tool the deployment's `toolFaces` overlay refused counts as what it is — not held. A server the run holds nothing of
+ * is not taught: its instructions describe tools the model will not hold.
+ *
+ * The one answer to "should the model be taught them": the initial instructions block and the delta lane's adds after a roster change read
+ * it. Whether the model HOLDS them is the ledger's ({@link instructionsTold}), which the disconnect line reads.
+ */
+export declare function instructionsTaught(leaves: (tool: {
+    readonly name: string;
+    readonly aliases?: readonly string[];
+}) => boolean, serverName: string, held: ReadonlyArray<{
+    readonly name: string;
+    readonly aliases?: readonly string[];
+}>, listed: ReadonlyArray<{
+    readonly name: string;
+}>): boolean;
+/** A materialization's instructions delta lane (`MaterializedMcp.instructionsDelta`): what the run drains at its next boundary. */
+export interface InstructionsLane {
+    pendingAdds: McpInstructionsEntry[];
+    pendingRemovals: string[];
+}
+/** Are this server's instructions in the model's context now? */
+export declare function instructionsTold(lane: InstructionsLane, server: string): boolean;
+/** A dial's default: the server's instructions are taught (a materialization alone takes every entry it returns as taught, until a run states its block). */
+export declare function toldOnDial(lane: InstructionsLane, server: string): void;
+/** The run's start: the stable block is what the model is told. A removal already queued for a server outside the block names instructions the model
+ *  never held, so it is withdrawn; a server inside the block with a removal queued is not in context (the frame will retract it). */
+export declare function toldAtStart(lane: InstructionsLane, servers: ReadonlySet<string>): void;
+/** Take this server's unread adds off the lane; a first copy that never reached the model leaves the ledger with it. */
+export declare function withdrawInstructionAdds(lane: InstructionsLane, server: string): void;
+/** Queue this server's current text (superseding an unread copy). In context already ⇒ stays so; otherwise a first copy, queued. */
+export declare function tellInstructions(lane: InstructionsLane, entry: McpInstructionsEntry): void;
+/** The server's connection is gone: unread adds are withdrawn, and the model is told its instructions no longer apply only if it holds them. */
+export declare function retractInstructions(lane: InstructionsLane, server: string): void;
+/** A re-dial that connected: a retraction still unread never reached the model, so it is withdrawn and the text the model holds stands. */
+export declare function unretractInstructions(lane: InstructionsLane, server: string): void;
 /** One declared MCP server and its mounted tools. */
 export interface MountedMcpServer {
     readonly server: McpServerSpec;
@@ -33,6 +82,14 @@ interface RosterEntry {
     readonly name: string;
     readonly mcpRemoteName?: string;
 }
+/**
+ * The names among `names` that belong to the declared server `serverName`: those under its prefix domain (`mcp__<server>__`), which
+ * is the roster's own definition of a server's tools (the live roster swaps a server's tools by it). Handed a roster's names, it is
+ * the ONE answer to "how many tools of this server does the run hold" — the re-dial's receipt and notice, the content-class
+ * declaration line, the wiring manifest's per-server count and {@link mountedMcpOf} all read it, so no two of them can count
+ * differently. Handed a server's own listing it answers what the server offers, which is not a mount count.
+ */
+export declare function toolNamesOfServer(names: Iterable<string>, serverName: string): string[];
 /**
  * Read the run's MCP surface off its roster. `declared` is the run's frozen server declarations; `aggregateNames` the names of the
  * tools its materialization minted that no server owns. A tool is a server's when its wire name sits under the server's prefix

package/dist/core/mounted-mcp.js

@@ -2,10 +2,79 @@ import { mintNamespacePrefix } from "./protocol-naming.js";
 import { MCP_NAMESPACE } from "./protocol-table.js";
 export const MCP_RESOURCE_LIST_ALLOW = "list_resources";
 export const MCP_RESOURCE_READ_ALLOW = "read_resource";
+export const LIST_MCP_RESOURCES = "ListMcpResourcesTool";
+export const READ_MCP_RESOURCE = "ReadMcpResourceTool";
+export const READ_MCP_RESOURCE_DIR = "ReadMcpResourceDirTool";
+const MCP_RESOURCE_FACES = [LIST_MCP_RESOURCES, READ_MCP_RESOURCE, READ_MCP_RESOURCE_DIR];
+export function resourceFacesLeft(leaves) {
+    return MCP_RESOURCE_FACES.some((name) => leaves({ name }));
+}
+export function instructionsTaught(leaves, serverName, held, listed) {
+    const own = new Set(toolNamesOfServer(held.map((t) => t.name), serverName));
+    return held.some((t) => (own.has(t.name) || MCP_RESOURCE_FACES.includes(t.name)) && leaves(t)) || (toolNamesOfServer(listed.map((t) => t.name), serverName).length === 0 && resourceFacesLeft(leaves));
+}
+const ledgers = new WeakMap();
+function ledgerOf(lane) {
+    let ledger = ledgers.get(lane);
+    if (ledger === undefined)
+        ledgers.set(lane, (ledger = new Map()));
+    return ledger;
+}
+const queuedFor = (lane, server) => lane.pendingAdds.some((e) => e.server === server);
+export function instructionsTold(lane, server) {
+    const state = ledgerOf(lane).get(server);
+    return state === "context" || (state === "queued" && !queuedFor(lane, server));
+}
+export function toldOnDial(lane, server) {
+    ledgerOf(lane).set(server, "context");
+}
+export function toldAtStart(lane, servers) {
+    const ledger = ledgerOf(lane);
+    ledger.clear();
+    for (let i = lane.pendingRemovals.length - 1; i >= 0; i--)
+        if (!servers.has(lane.pendingRemovals[i]))
+            lane.pendingRemovals.splice(i, 1);
+    for (const server of servers)
+        if (!lane.pendingRemovals.includes(server))
+            ledger.set(server, "context");
+}
+export function withdrawInstructionAdds(lane, server) {
+    const told = instructionsTold(lane, server);
+    for (let i = lane.pendingAdds.length - 1; i >= 0; i--)
+        if (lane.pendingAdds[i].server === server)
+            lane.pendingAdds.splice(i, 1);
+    if (!told)
+        ledgerOf(lane).delete(server);
+}
+export function tellInstructions(lane, entry) {
+    const told = instructionsTold(lane, entry.server);
+    withdrawInstructionAdds(lane, entry.server);
+    lane.pendingAdds.push(entry);
+    ledgerOf(lane).set(entry.server, told ? "context" : "queued");
+}
+export function retractInstructions(lane, server) {
+    const told = instructionsTold(lane, server);
+    withdrawInstructionAdds(lane, server);
+    if (told && !lane.pendingRemovals.includes(server))
+        lane.pendingRemovals.push(server);
+    ledgerOf(lane).delete(server);
+}
+export function unretractInstructions(lane, server) {
+    if (!lane.pendingRemovals.includes(server))
+        return;
+    for (let i = lane.pendingRemovals.length - 1; i >= 0; i--)
+        if (lane.pendingRemovals[i] === server)
+            lane.pendingRemovals.splice(i, 1);
+    ledgerOf(lane).set(server, "context");
+}
+export function toolNamesOfServer(names, serverName) {
+    const prefix = mintNamespacePrefix(MCP_NAMESPACE, serverName);
+    return [...names].filter((name) => name.startsWith(prefix));
+}
 export function mountedMcpOf(input) {
     const servers = (input.declared ?? []).map((server) => {
-        const prefix = mintNamespacePrefix(MCP_NAMESPACE, server.name);
-        const tools = input.roster.flatMap((t) => (t.name.startsWith(prefix) && typeof t.mcpRemoteName === "string" ? [{ name: t.name, remoteName: t.mcpRemoteName }] : []));
+        const owned = new Set(toolNamesOfServer(input.roster.map((t) => t.name), server.name));
+        const tools = input.roster.flatMap((t) => (owned.has(t.name) && typeof t.mcpRemoteName === "string" ? [{ name: t.name, remoteName: t.mcpRemoteName }] : []));
         return { server, tools };
     });
     const aggregate = input.roster.filter((t) => input.aggregateNames.has(t.name)).map((t) => t.name);

package/dist/core/own-property-receipt.d.ts

@@ -1,3 +1,4 @@
+import { type ReceiptMode } from "./mods/kernel/receive.js";
 /** How a refusal names the object being received. */
 export interface OwnPropertyReceiptWords {
     /** The object, e.g. `RunnerDeps`. */
@@ -14,5 +15,17 @@ export declare function receiptRefusal(message: string): Error & {
 /** The receipt's first look, before ANY reflection on the object (a door that must look at the caller's object before
  *  the receipt — a retired-name door reading its prototype chain — calls this first): a Proxy is refused. */
 export declare function refuseProxy(given: object, words: OwnPropertyReceiptWords): void;
+/** The configuration receipt's mode of the one receipt: the top record read, each getter once, its members as given (a declared list's
+ *  own read too: the list itself, each element once, the elements as given). */
+export declare const CONFIG_RECEIPT_MODE: ReceiptMode;
+/**
+ * The declaration receipt's mode of the one receipt — a declaration the engine judges and then holds (an MCP server's or an A2A peer's
+ * entry, a `toolAxes` record, a lock declaration) received as plain data held to the engine's one depth for a caller's value,
+ * {@link MODS_VALUE_DEPTH} levels of records and lists below the declaration itself (the bound a mods handler's answer is held to): every
+ * own string-keyed member read once off its captured descriptor (a getter called once, enumerable or not), every level copied, anything
+ * that is not data refused (a Proxy at any level, a function, a bigint, an object of another prototype, a structure that contains
+ * itself, a container nested deeper — a shared one measured where it sits each time it is met), every copied container frozen.
+ */
+export declare const DECLARATION_RECEIPT_MODE: ReceiptMode;
 /** Read `given` by the receipt law (module note): the plain copy, every own member taken once from its captured descriptor. */
 export declare function receiveOwnProperties<T extends object>(given: T, words: OwnPropertyReceiptWords): T;