@sema-agent/core 7.52.0 → 7.53.0

package/dist/core/mods/kernel/site-rules.d.ts

@@ -7,6 +7,19 @@ import { type ModSeat, type ModTier } from "./events.js";
 /** The host's Proxy probe (this folder cannot recognise a Proxy on its own): with one, a handler's Proxy is refused
  *  before any of its traps runs; without one, it is read like any object. */
 export type ProxyProbe = (value: object) => boolean;
+/**
+ * The one depth the bus holds a handler's values to: how many container levels a value may have below a payload member
+ * or an answer's top (1 = the member itself). Every value a handler gives the bus — what it hands to `next`, a `$`
+ * call's arguments, its answer — is received in a mode bounded by it (a shared reference measured again where it sits
+ * each time it is met), so a value nested deeper is refused by the first walk that meets it before that
+ * walk goes any deeper. Every walk keeps its own stack, so neither the platform nor the caller's stack depth decides.
+ * The pinned-key comparison is held to the same depth. A container is one level wherever it is met, so the verdict
+ * does not depend on member order for a value without a cycle; through a cycle, depth is measured on the walk's way (a
+ * container still being walked counts as one level where it is met again). The engine's own event is received at any
+ * depth, and its objects — handed back anywhere in what a handler hands on, answers or passes to a `$` call — are taken
+ * as themselves, never walked: one of its containers is one level where it sits, whatever it holds.
+ */
+export declare const MODS_VALUE_DEPTH = 1000;
 /** Why a handler did not answer for itself: it threw, it ran past its budget, it broke the site's contract, or it was
  *  not run because the dispatch re-entered a frame it is part of (its `.catch` answers for it — CC 296 form, (cli296.js:242947) "hasCatch"). */
 export declare const MOD_FAILURE_CAUSES: readonly ["threw", "timeout", "violation", "reentry"];
@@ -35,8 +48,50 @@ export declare const NEXT_IN_FLIGHT: Readonly<{
 export type ModAnswerCheck = (answer: unknown, e: ModEventPayload, by: ModAnswerer, below: readonly unknown[]) => string | undefined;
 /** A matcher: top-level fields of `e` that must equal these values exactly. */
 export type ModMatcher = Readonly<Record<string, string | number | boolean>>;
-/** The first pinned key `next` changed, or undefined. Identity comparison: a pinned value is handed on as is. */
-export declare function pinnedKeyChanged(pinned: readonly string[], received: ModEventPayload, passed: ModEventPayload): string | undefined;
+/** Why a pinned key of what a handler handed on is not taken: it holds another value, or it is a copy the comparison
+ *  could not walk to the end (`unproven` says why) — refused all the same, since only a copy proven the same is taken. */
+export interface PinnedKeyBreak {
+    readonly key: string;
+    readonly unproven?: string;
+}
+/**
+ * The first pinned key `next` did not hand on as the engine's fact, or undefined. A pinned value is compared by value
+ * ({@link sameModValue}): the engine's own fact handed on as is, or a copy of it, is not a change.
+ */
+export declare function pinnedKeyChanged(pinned: readonly string[], received: ModEventPayload, passed: ModEventPayload): PinnedKeyBreak | undefined;
+/** {@link engineObjects} of a dispatch's own event, found the first time it is asked and the same set every time after:
+ *  the event is frozen, so one finding serves every receipt of the dispatch. */
+export declare function engineObjectsOnce(held: ModEventPayload): () => ReadonlySet<object>;
+/**
+ * What the next handler reads when a handler hands `passed` to `next` (not the dispatch's own e): `passed` received
+ * whole in the mode held to {@link MODS_VALUE_DEPTH} (every object of the dispatch's own e in it — `engines`, found once
+ * per dispatch by {@link engineObjectsOnce} — kept as itself), then {@link pinnedHandOn}. A value nested past the depth
+ * is refused by the receipt, before any deeper walk — under a pinned key in the comparison's own words (too deep to
+ * compare), under any other member as the payload holding it.
+ */
+export declare function handedOn(pinned: readonly string[], held: ModEventPayload, passed: unknown, engines: ReadonlySet<object>, isProxy?: ProxyProbe): {
+    readonly payload: ModEventPayload;
+} | {
+    readonly violation: string;
+};
+/**
+ * What the next handler reads when a handler hands on `passed` (already received whole): the payload with every
+ * pinned key the engine's own member — the same object `held` carries, or no member where `held` has none — so a
+ * handler below a copy-forwarder reads the engine's fact, not the copy's shape (a member that is `undefined`, a
+ * member order, a −0 the comparison does not count). A pinned key the copy did not hand on as the engine's fact
+ * ({@link pinnedKeyChanged}) breaks the site instead. The comparison decides only whether to refuse; what travels down
+ * for a pinned key is the engine's member, always. The payload keeps the shape it was received in: a reference inside
+ * it to the payload itself is a reference to what is handed on (a cycle stays a cycle), and one to any object inside
+ * what the handler handed on under a pinned key — the copy itself, a member of it, an element of one of its lists, at
+ * any depth — is a reference to the engine's object it was proven the same as (a shared reference stays shared; an
+ * object of the copy standing for two of the engine's goes to the one the comparison met first). `engines`: every
+ * object of `held` (found here when not given).
+ */
+export declare function pinnedHandOn(pinned: readonly string[], held: ModEventPayload, passed: ModEventPayload, engines?: ReadonlySet<object>): {
+    readonly payload: ModEventPayload;
+} | {
+    readonly violation: string;
+};
 /** Why a handler's answer breaks the site, or undefined. No answer at all is never an answer. */
 export declare function answerViolation(answer: unknown, check: ModAnswerCheck | undefined, e: ModEventPayload, by: ModAnswerer, below: readonly unknown[]): string | undefined;
 /**
@@ -52,14 +107,18 @@ export declare function methodAnswerViolation(answer: unknown, _e?: ModEventPayl
 export declare function matcherViolation(m: unknown): string | undefined;
 /** Whether every matcher field equals `e`'s own top-level field exactly. */
 export declare function matcherMatches(m: ModMatcher | undefined, e: ModEventPayload): boolean;
-/**
- * What a payload hands on, received by the one receipt in the mods mode: a plain record, copied whole at every depth
- * (cycles and shared references kept, a function or a class instance handed as it is), its top level frozen. A member
- * the reader already holds (`held`: the dispatch's own members) is kept as itself, so a pinned value handed back
- * unchanged is the same value. An accessor anywhere is refused (a getter is never run), and a payload that cannot be
- * copied whole is refused — never handed on shorter than it was given.
- */
-export declare function receivePayload(v: unknown, held?: ModEventPayload, isProxy?: ProxyProbe): {
+/** A record a handler gives the bus other than through `next` — a `$` call's arguments, and a method's `enter` shaping
+ *  of them — received held to {@link MODS_VALUE_DEPTH}; an object of `held` ({@link engineObjectsOnce} of what the bus
+ *  already holds: the dispatch the handler runs in, or the call's received arguments) is kept as itself, never walked. */
+export declare function receivePayload(v: unknown, isProxy?: ProxyProbe, held?: ReadonlySet<object>): {
+    readonly payload: ModEventPayload;
+} | {
+    readonly refusal: string;
+};
+/** The engine's own event at a dispatch's entry, received whole at any depth (one the receipt cannot copy whole —
+ *  reading it threw where none of its getters runs, or it holds more objects than one receipt can index — is refused,
+ *  never handed on shorter). */
+export declare function receiveEvent(e: unknown): {
     readonly payload: ModEventPayload;
 } | {
     readonly refusal: string;
@@ -70,15 +129,21 @@ export declare function receivePayload(v: unknown, held?: ModEventPayload, isPro
  * copied once and frozen; an answer already frozen (an engine sentinel) or not a plain container is itself.
  */
 export declare function answerUpward(v: unknown): unknown;
-/** A handler's answer, received by the same receipt and mode (an answer need not be a record; a primitive is itself). */
-export declare function receiveAnswer(answer: unknown, isProxy?: ProxyProbe): {
+/** A handler's answer, received by the same receipt held to {@link MODS_VALUE_DEPTH} (an answer need not be a record; a
+ *  primitive is itself); an object of the dispatch's own event in it (`engines`, {@link engineObjectsOnce}) is kept as
+ *  itself, never walked. */
+export declare function receiveAnswer(answer: unknown, engines: ReadonlySet<object>, isProxy?: ProxyProbe): {
     readonly answer: unknown;
 } | {
     readonly refusal: string;
 };
 /**
- * A copy for an observe handler: every data container (a plain object, an array) detached at whatever depth, a
- * leaf the structured clone refuses (a function, a handle, a class instance holding one) handed as is. An
- * uncloneable leaf therefore never leaves the data beside it — at the top or nested — aliased.
+ * A copy for an observe handler, made by the one receipt (its own stack, so no depth of the event decides whether an
+ * observer runs — the event it observes was received at any depth too): every data container (a plain object, an
+ * ordinary array) detached at any depth; then every other object the copy holds — a tool result's `Map`, `Date` or
+ * typed array — detached by a structured clone of that object alone (one clone per object, so a shared one stays shared),
+ * and one the clone refuses (a function, a handle, a class instance holding one) handed as is. The engine's own event
+ * holds data properties only, so the copy is whole; a receipt that could not make it (a Proxy whose trap throws, on a bus
+ * given no probe) is the observer's failure, reported like any other.
  */
 export declare function detachedCopy(e: ModEventPayload): Record<string, unknown>;

package/dist/core/mods/kernel/site-rules.js

@@ -1,12 +1,194 @@
 import { describe } from "./events.js";
 import { describeFault, isPlainRecord, MODS_PAYLOAD_MODE, receive } from "./receive.js";
+export const MODS_VALUE_DEPTH = 1_000;
+const HANDED_MODE = Object.freeze({ ...MODS_PAYLOAD_MODE, depth: MODS_VALUE_DEPTH + 1, past: "refuse" });
 function payloadMode(isProxy) {
-    return isProxy === undefined ? MODS_PAYLOAD_MODE : Object.freeze({ ...MODS_PAYLOAD_MODE, isProxy });
+    return isProxy === undefined ? HANDED_MODE : Object.freeze({ ...HANDED_MODE, isProxy });
+}
+const TOO_DEEP_TO_COMPARE = `too deep to compare (nested past ${MODS_VALUE_DEPTH} levels)`;
+function faultClause(fault) {
+    if (fault.kind !== "too-deep")
+        return describeFault(fault);
+    return `a value nested past ${MODS_VALUE_DEPTH} levels${fault.path.length > 0 ? ` under "${fault.path[0]}"` : ""}`;
 }
 export const MOD_FAILURE_CAUSES = Object.freeze(["threw", "timeout", "violation", "reentry"]);
 export const NEXT_IN_FLIGHT = Object.freeze({ inFlight: true });
+const TOO_DEEP = Object.freeze({ tooDeep: true });
+const OPEN = "open";
+function sameModValue(a0, b0, paired, depth0, homes) {
+    const stack = [];
+    const named = (r) => Object.keys(r).filter((k) => r[k] !== undefined);
+    const meet = (a, b, depth) => {
+        if (a === b || (Number.isNaN(a) && Number.isNaN(b)))
+            return 0;
+        if (typeof a !== "object" || typeof b !== "object" || a === null || b === null)
+            return false;
+        let row = paired.get(a);
+        const met = row?.get(b);
+        if (met !== undefined) {
+            const height = met === OPEN ? 1 : met;
+            if (depth + height - 1 > MODS_VALUE_DEPTH)
+                throw TOO_DEEP;
+            return height;
+        }
+        if (depth > MODS_VALUE_DEPTH)
+            throw TOO_DEEP;
+        if (row === undefined)
+            paired.set(a, (row = new Map()));
+        row.set(b, OPEN);
+        if (!homes.has(b))
+            homes.set(b, a);
+        if (Array.isArray(a) || Array.isArray(b)) {
+            if (!Array.isArray(a) || !Array.isArray(b) || Object.getPrototypeOf(a) !== Array.prototype || Object.getPrototypeOf(b) !== Array.prototype || a.length !== b.length)
+                return false;
+        }
+        else if (!isPlainRecord(a) || !isPlainRecord(b))
+            return false;
+        const ra = a;
+        const rb = b;
+        const names = named(ra);
+        if (names.length !== named(rb).length)
+            return false;
+        stack.push({ a: ra, b: rb, row, names, depth, next: 0, height: 1 });
+        return undefined;
+    };
+    const top = meet(a0, b0, depth0);
+    if (top !== undefined)
+        return top;
+    for (;;) {
+        const f = stack[stack.length - 1];
+        if (f.next < f.names.length) {
+            const k = f.names[f.next++];
+            if (!Object.hasOwn(f.b, k))
+                return false;
+            const below = meet(f.a[k], f.b[k], f.depth + 1);
+            if (below === false)
+                return false;
+            if (below !== undefined)
+                f.height = Math.max(f.height, below + 1);
+            continue;
+        }
+        f.row.set(f.b, f.height);
+        stack.pop();
+        const holder = stack[stack.length - 1];
+        if (holder === undefined)
+            return f.height;
+        holder.height = Math.max(holder.height, f.height + 1);
+    }
+}
 export function pinnedKeyChanged(pinned, received, passed) {
-    return pinned.find((k) => !Object.is(received[k], passed[k]));
+    const compared = comparePinned(pinned, received, passed);
+    return "broke" in compared ? compared.broke : undefined;
+}
+function comparePinned(pinned, received, passed) {
+    const paired = new Map();
+    const homes = new Map();
+    for (const key of pinned) {
+        try {
+            if (sameModValue(received[key], passed[key], paired, 1, homes) === false)
+                return { broke: { key } };
+        }
+        catch (err) {
+            return { broke: { key, unproven: err === TOO_DEEP ? TOO_DEEP_TO_COMPARE : "the comparison could not walk it to the end" } };
+        }
+    }
+    return { homes };
+}
+function engineObjects(held) {
+    const found = new Set();
+    const stack = Object.values(held);
+    while (stack.length > 0) {
+        const v = stack.pop();
+        if (typeof v !== "object" || v === null || found.has(v) || !Object.isFrozen(v))
+            continue;
+        if (!isPlainRecord(v) && !(Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype))
+            continue;
+        found.add(v);
+        for (const k of Object.keys(v))
+            stack.push(v[k]);
+    }
+    return found;
+}
+export function engineObjectsOnce(held) {
+    let found;
+    return () => (found ??= engineObjects(held));
+}
+const unprovenCopy = (key, why) => `next() handed on a copy of the pinned key "${key}" that is ${why}; a copy is taken only when proven the same`;
+export function handedOn(pinned, held, passed, engines, isProxy) {
+    const received = receiveRecord(passed, payloadMode(isProxy), engines);
+    if ("refusal" in received) {
+        const key = received.fault?.kind === "too-deep" ? received.fault.path[0] : undefined;
+        return { violation: key !== undefined && pinned.includes(key) ? unprovenCopy(key, TOO_DEEP_TO_COMPARE) : `next() takes the event object: ${received.refusal}` };
+    }
+    return pinnedHandOn(pinned, held, received.payload, engines);
+}
+export function pinnedHandOn(pinned, held, passed, engines) {
+    const compared = comparePinned(pinned, held, passed);
+    if ("broke" in compared) {
+        return { violation: compared.broke.unproven === undefined ? `next() changed the pinned key "${compared.broke.key}"` : unprovenCopy(compared.broke.key, compared.broke.unproven) };
+    }
+    if (pinned.every((k) => Object.hasOwn(passed, k) === Object.hasOwn(held, k) && Object.is(passed[k], held[k])))
+        return { payload: passed };
+    return { payload: rehomed(pinned, held, passed, compared.homes, engines ?? engineObjects(held)) };
+}
+function rehomed(pinned, held, passed, homes, engines) {
+    const swap = new Map();
+    for (const [copy, home] of homes)
+        if (copy !== passed && !engines.has(copy))
+            swap.set(copy, home);
+    const isContainer = (v) => typeof v === "object" && v !== null && !engines.has(v) && !swap.has(v) && (isPlainRecord(v) || (Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype));
+    const holders = new Map();
+    const walked = new Set([passed]);
+    const stack = [passed];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        for (const k of Object.keys(node)) {
+            if (node === passed && pinned.includes(k))
+                continue;
+            const v = node[k];
+            if (v !== passed && !swap.has(v) && !isContainer(v))
+                continue;
+            const by = holders.get(v);
+            if (by === undefined)
+                holders.set(v, [node]);
+            else
+                by.push(node);
+            if (isContainer(v) && !walked.has(v)) {
+                walked.add(v);
+                stack.push(v);
+            }
+        }
+    }
+    const twins = new Map([[passed, {}]]);
+    const reach = [passed, ...swap.keys()];
+    while (reach.length > 0) {
+        for (const h of holders.get(reach.pop()) ?? []) {
+            if (twins.has(h))
+                continue;
+            twins.set(h, Array.isArray(h) ? [] : {});
+            reach.push(h);
+        }
+    }
+    const put = (to, k, v) => void Object.defineProperty(to, k, { value: v, enumerable: true, writable: true, configurable: true });
+    const moved = (v) => (typeof v !== "object" || v === null ? v : swap.has(v) ? swap.get(v) : (twins.get(v) ?? v));
+    for (const [from, to] of twins) {
+        const r = from;
+        for (const k of Object.keys(r)) {
+            if (from !== passed || !pinned.includes(k))
+                put(to, k, moved(r[k]));
+            else if (Object.hasOwn(held, k))
+                put(to, k, held[k]);
+        }
+        if (from === passed)
+            for (const k of pinned)
+                if (Object.hasOwn(held, k) && !Object.hasOwn(to, k))
+                    put(to, k, held[k]);
+        if (Array.isArray(from) && Array.isArray(to))
+            to.length = from.length;
+    }
+    for (const to of twins.values())
+        Object.freeze(to);
+    return twins.get(passed);
 }
 export function answerViolation(answer, check, e, by, below) {
     if (answer === undefined)
@@ -49,13 +231,21 @@ export function matcherMatches(m, e) {
         return true;
     return Object.entries(m).every(([k, v]) => Object.prototype.hasOwnProperty.call(e, k) && e[k] === v);
 }
-export function receivePayload(v, held, isProxy) {
-    if (isProxy !== undefined && typeof v === "object" && v !== null && isProxy(v))
+function receiveRecord(v, mode, held) {
+    if (mode.isProxy !== undefined && typeof v === "object" && v !== null && mode.isProxy(v))
         return { refusal: "the payload is a Proxy (refused before any of its traps runs)" };
     if (!isPlainRecord(v))
         return { refusal: `an event payload is a plain object, not ${describe(v)}` };
-    const r = receive(v, payloadMode(isProxy), held === undefined ? undefined : Object.values(held));
-    return r.ok ? { payload: Object.freeze(r.value) } : { refusal: `the payload holds ${describeFault(r.fault)}` };
+    const r = receive(v, mode, held);
+    return r.ok ? { payload: Object.freeze(r.value) } : { refusal: `the payload holds ${faultClause(r.fault)}`, fault: r.fault };
+}
+export function receivePayload(v, isProxy, held) {
+    const r = receiveRecord(v, payloadMode(isProxy), held);
+    return "refusal" in r ? { refusal: r.refusal } : r;
+}
+export function receiveEvent(e) {
+    const r = receiveRecord(e, MODS_PAYLOAD_MODE);
+    return "refusal" in r ? { refusal: r.refusal } : r;
 }
 export function answerUpward(v) {
     if (typeof v !== "object" || v === null || Object.isFrozen(v))
@@ -64,41 +254,43 @@ export function answerUpward(v) {
         return Object.freeze([...v]);
     return isPlainRecord(v) ? Object.freeze({ ...v }) : v;
 }
-export function receiveAnswer(answer, isProxy) {
-    const r = receive(answer, payloadMode(isProxy));
-    return r.ok ? { answer: r.value } : { refusal: `answered ${describeFault(r.fault)}` };
+export function receiveAnswer(answer, engines, isProxy) {
+    const r = receive(answer, payloadMode(isProxy), engines);
+    return r.ok ? { answer: r.value } : { refusal: `answered ${faultClause(r.fault)}` };
 }
+const DETACHED_MODE = Object.freeze({ accessors: "refuse", depth: Infinity, others: "as-is" });
 export function detachedCopy(e) {
-    const seen = new Map();
-    const out = {};
-    for (const [k, v] of Object.entries(e))
-        Object.defineProperty(out, k, { value: detachedValue(v, seen), enumerable: true, writable: true, configurable: true });
-    return out;
-}
-function detachedValue(v, seen) {
-    if (typeof v !== "object" || v === null)
-        return v;
-    const done = seen.get(v);
-    if (done !== undefined)
-        return done;
-    try {
-        return structuredClone(v);
-    }
-    catch {
-    }
-    const proto = Object.getPrototypeOf(v);
-    if (Array.isArray(v)) {
-        const arr = [];
-        seen.set(v, arr);
-        for (const x of v)
-            arr.push(detachedValue(x, seen));
-        return arr;
+    const r = receive(e, DETACHED_MODE);
+    if (!r.ok)
+        throw new Error(`the observer's copy of the event could not be made: ${describeFault(r.fault)}`);
+    const copy = r.value;
+    const clones = new Map();
+    const walked = new Set([copy]);
+    const stack = [copy];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        for (const k of Object.keys(node)) {
+            const v = node[k];
+            if (typeof v !== "object" || v === null)
+                continue;
+            if (isPlainRecord(v) || (Array.isArray(v) && Object.getPrototypeOf(v) === Array.prototype)) {
+                if (!walked.has(v)) {
+                    walked.add(v);
+                    stack.push(v);
+                }
+                continue;
+            }
+            if (!clones.has(v)) {
+                let own = v;
+                try {
+                    own = structuredClone(v);
+                }
+                catch {
+                }
+                clones.set(v, own);
+            }
+            Object.defineProperty(node, k, { value: clones.get(v), enumerable: true, writable: true, configurable: true });
+        }
     }
-    if (proto !== Object.prototype && proto !== null)
-        return v;
-    const obj = {};
-    seen.set(v, obj);
-    for (const [k, x] of Object.entries(v))
-        Object.defineProperty(obj, k, { value: detachedValue(x, seen), enumerable: true, writable: true, configurable: true });
-    return obj;
+    return copy;
 }

package/dist/core/mods/stations.d.ts

@@ -32,12 +32,6 @@ export declare function agentIdOf(identity: HookInvocationIdentity | undefined):
  * leg's kind reads `"resume"` whoever it runs as.
  */
 export declare function stopEventOf(identity: Pick<HookInvocationIdentity, "isDelegatedChild"> | undefined): "classic.Stop" | "classic.SubagentStop";
-/**
- * The args as an observation carries them: the kernel's detached copy (a structured clone, or a shallow copy for a
- * graph the clone refuses), so an observer editing what it was handed cannot move the live args later frames and audit
- * records share. A non-object value (immutable) is handed as is.
- */
-export declare function detachedArgsOf(args: unknown): unknown;
 /**
  * The args as a judging handler receives them: the gate pass's own immutable value ({@link ownArgs} — the value itself when
  * the gate already took it, which is every call the gate raises an event over), so the bytes a handler judges are the bytes

package/dist/core/mods/stations.js

@@ -8,7 +8,6 @@ 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 { detachedCopy } from "./kernel/site-rules.js";
 import { isPlainRecord } from "./kernel/receive.js";
 import { engineMethodBottoms } from "./dollar.js";
 import { modSeatsOf, modsReportToOnError, registrationRefusedNotice } from "./host.js";
@@ -22,12 +21,6 @@ export function agentIdOf(identity) {
 export function stopEventOf(identity) {
     return identity?.isDelegatedChild === true ? "classic.SubagentStop" : "classic.Stop";
 }
-export function detachedArgsOf(args) {
-    return isRecord(args) ? detachedCopy(args) : args;
-}
-function isRecord(v) {
-    return typeof v === "object" && v !== null && !Array.isArray(v);
-}
 export function judgedInputOf(args) {
     const owned = ownArgs(args);
     return owned.ok ? owned.value : args;

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;