@sema-agent/core 7.52.0 → 7.53.0

package/dist/core/locked-config.d.ts

@@ -1,4 +1,5 @@
-import type { McpServerSpec, RunnerDeps, TaskSpec } from "./types.js";
+import type { A2aServerSpec, McpServerSpec, RunnerDeps, TaskSpec } from "./types.js";
+import { type ToolAxesSurface } from "./mcp-server-spec.js";
 import type { ToolPolicy } from "./tool-policy.js";
 /** The closed set of administratively lockable configuration keys. Adding a member is a deliberate
  *  edit HERE (tsc forces the registry row), never a free-form string. */
@@ -34,7 +35,7 @@ export interface LockedConfig {
     keys: readonly LockedKey[];
 }
 /** The preflight's resolved snapshot — the ONLY thing downstream task assembly reads for the
- *  guarded slots (never the raw `spec.mcp` / `spec.toolPolicy` fields). */
+ *  guarded slots (never the raw `spec.mcp` / `spec.a2a` / `spec.toolPolicy` fields). */
 export interface LockedPreflight {
     /** The validated lock set (empty when the deployment declares none). */
     lockedKeys: ReadonlySet<LockedKey>;
@@ -45,6 +46,10 @@ export interface LockedPreflight {
      *  `undefined` (core has no deployment-level MCP seat — a locked deployment mounts no
      *  task-supplied servers). */
     mcp: TaskSpec["mcp"];
+    /** The task's A2A peers: a frozen SNAPSHOT of `spec.a2a` whose `toolAxes` were judged here by the same reader and with the same
+     *  disposition as an MCP server's (a declaration that does not fit refused the whole prepare), each peer carrying the reader's plain
+     *  copy; `undefined` when the spec declares no peer (absent or empty). Read once, here: the peers dialed are the peers judged. */
+    a2a: TaskSpec["a2a"];
     /** Effective caller tool policy: the same `spec.toolPolicy ?? deps.toolPolicy` slot the gate has
      *  always enforced, resolved ONCE here. With `toolPolicy` locked, the deployment's own
      *  `deps.toolPolicy` is the whole answer (a spec-supplied policy has already been refused). */
@@ -56,12 +61,27 @@ export interface LockedPreflight {
      *  site). Unlocked: `spec.basePolicyForResumeEdit ?? deps.basePolicyForResumeEdit`. */
     basePolicyForResumeEdit: ToolPolicy | undefined;
 }
+/**
+ * How one configuration door is entered: `seat` names the input that carries the value the door judges — the task's configuration or the
+ * deployment's deps. A prepare enters each door as it stands ({@link ENTER_AS_IS}: the door's own coded throw); a resume's screen before the
+ * claim enters the same door through the resume's refusal channel, which names the seat (`asResumeConfigRefusal`). One door, one function,
+ * two entrances: the seat is written once, where the door is called.
+ */
+export type ConfigDoorEntry = <T>(seat: "taskConfig" | "deps", door: () => T) => T;
+export declare const ENTER_AS_IS: ConfigDoorEntry;
 /**
  * Validate a deployment's lock declaration against the closed registry. Fail-loud on any unknown
  * key (`config.locked_registry`): a security control that doesn't parse must refuse to arm, not
  * degrade to "that key silently unlocked". Exported for deployments that want the check at their
  * own startup; the task-preparation preflight runs it on every leg regardless (a mis-declared lock
- * then fails the first prepare instead of silently guarding nothing).
+ * then fails the first prepare instead of silently guarding nothing — and, on a resume, the screen before
+ * the claim, which calls the same preflight).
+ *
+ * Total over the declaration: anything but `undefined` (no locks) or plain data whose `keys` is a list of registry names — `null`, a
+ * list, a primitive, a `keys` that is absent or not a list, a declaration that is not plain data (a Proxy, a `Set` of keys, a class
+ * instance, a getter that throws), an element that is not a string, a string that is not a registry name — is the same coded refusal
+ * naming `RunnerDeps.lockedConfig` and the member (an element by its index), never a TypeError and never "no locks". The declaration is
+ * read once, by the one declaration reading.
  */
 export declare function resolveLockedKeys(config: LockedConfig | undefined): ReadonlySet<LockedKey>;
 /**
@@ -74,23 +94,33 @@ export declare function resolveLockedKeys(config: LockedConfig | undefined): Rea
  * read off a LIVE object is only true for as long as the object holds still, and the fail-open
  * direction is the reachable one — so both boundaries consume data instead.
  *
- * The read discipline is the load-bearing part, and it is why this is a spread rather than
- * "read the property, then copy the object": a getter answering ALTERNATING LEGAL values would
+ * The read discipline is the load-bearing part, and it is why the copy is made in the pass that reads
+ * rather than "read the property, then copy the object": a getter answering ALTERNATING LEGAL values would
  * satisfy any number of re-reads (`"external"` to a validator, `"local"` to a mint site), and no
- * vocabulary guard anywhere has purchase on a legal value. One spread evaluates every own property
- * EXACTLY ONCE and materializes the result as plain data; every later reader — validator, connect,
- * refresh — then sees the same byte. Frozen so nothing downstream rewrites it.
+ * vocabulary guard anywhere has purchase on a legal value. One pass evaluates every member EXACTLY ONCE
+ * and materializes the result as plain data; every later reader — validator, connect, refresh — then sees
+ * the same byte. Frozen so nothing downstream rewrites it.
  *
- * Boundary, stated: the copy is one level deep — nested option objects (transport, headers, env,
- * toolAxes) stay shared with the caller's entry exactly as before, because the axis this owns is the
- * content class; readers of the nested shapes normalize their own values (the transport DISCRIMINATOR
- * is derived, never echoed raw). `toolAxes` is the one nested shape both entrances replace with its
- * reader's plain copy ({@link judgeEntryToolAxes}), and the one member this snapshot reads BY NAME rather
- * than by spread, once: a declaration an entry carries as a non-enumerable or inherited property would
- * otherwise vanish before any reader sees it, and an absent caller axis is a tightening lost, not a
- * fail-closed absence. Every other member is taken as own ENUMERABLE properties only: an entry whose
- * fields live on a prototype was never the plain configuration record this type describes, and its
- * absent class reads fail-closed like any other absence.
+ * Plain data, stated: an entry IS plain data, to its whole depth, or it is refused whole. The entry is read
+ * by the one declaration reading ({@link receiveDeclaration} — the engine's one receipt of a caller's object,
+ * in its declaration mode): every own member read once off its captured descriptor, every level copied, every
+ * copied container frozen; an object the entry reaches through two members is read once, and both hold the one
+ * copy. So a server's `transport` with its `args` / `env` / `headers`, `allowTools`, `toolFaces`, `toolAxes`
+ * and a peer's `headers` and `allowSkills` are the copy's own, and a host that edits its own nested object after
+ * the door (a header value, an `allowSkills.push`) reaches nothing the engine holds: the dial, a refresh and a
+ * re-dial all work from this copy, on both surfaces. The axes are then judged on that copy by their own reader
+ * ({@link judgeEntryToolAxes}).
+ *
+ * There is no third outcome between "copied whole" and "refused": a value the copy cannot carry whole is a
+ * declaration the engine cannot read — a Proxy at any level, 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, whose members a copy would drop or could not tell from its own), a function, a structure that contains
+ * itself, a getter that throws (whatever it throws), a nesting too deep to read, a list element that is not a
+ * string, a member named `__proto__`, an entry that is not an object. Each is refused as `config.invalid_argument`
+ * naming the declarer and the member where reading stopped (`toolFaces.write_file`, `allowTools[2]`), never as the
+ * raw error the host's code threw, and never by handing the host's object on: a member some of whose getters have
+ * already run would be read again downstream, and could answer differently. The door refuses the whole prepare and
+ * a library entrance the whole call, with this one sentence either way.
  *
  * Exported because the SECOND boundary needs the identical guarantee: `materializeMcpTools` is public
  * and a library caller reaches it without passing any door, so it snapshots its own input through
@@ -98,16 +128,39 @@ export declare function resolveLockedKeys(config: LockedConfig | undefined): Rea
  */
 export declare function snapshotMcpEntries(entries: readonly McpServerSpec[]): McpServerSpec[];
 /**
- * The `toolAxes` question for ONE snapshot entry — asked by the preparation door (a refusal ends the prepare) and by the materialization
- * entrance (a refusal fails that server's dial), so there is one reading, one copy and one sentence whichever time it is asked.
- * `ok: true` carries the entry with the reader's PLAIN COPY of the axes in place of the caller's object: what was judged is the very value
- * the connect and every refresh read, not a live object that could answer differently later. The copy is frozen with the entry — a tool
- * that shallow-copies a server (`mountedMcp()`) to customise its axes must not rewrite what the parent reads. `ok: false` carries the
- * coded refusal (`config.invalid_argument`) naming the server, the tool and the member, never a value.
+ * The refusal of a declaration the engine cannot read (`config.invalid_argument`). `declarer` is the entry's own name as the engine captured
+ * it ({@link capturedName}) — absent when there was none to capture — so a consumer that holds the refused entry by a name (the A2A
+ * entrance's warning, its collision check) takes it from here and never reads the caller's object again.
+ */
+export type DeclarationRefusal = Error & {
+    code: "config.invalid_argument";
+    declarer?: string;
+};
+/**
+ * The name a refused entry is held under by a consumer that holds it by a name (the A2A entrance): the refusal's own `declarer`, read as
+ * own data — never through anything the refusal's prototype carries — or `undefined` (the consumer names the entry by its place).
+ */
+export declare function refusedDeclarer(refusal: unknown): string | undefined;
+/**
+ * One entry of EITHER surface that declares `toolAxes` (an MCP server, an A2A peer) as frozen plain data, read by the discipline
+ * {@link snapshotMcpEntries} states: the entry and everything in it read once by the one declaration reading and copied to its whole
+ * depth, or the entry refused ({@link DeclarationRefusal}), naming the member where reading stopped. The A2A peer's door and its
+ * materialization snapshot through this same function, so the two surfaces' declarations reach the one judge ({@link judgeEntryToolAxes})
+ * read the same way; `at` is the surface the entry sits on, which only decides what the refusal calls the declarer.
+ */
+export declare function snapshotDeclaredEntry<E extends McpServerSpec | A2aServerSpec>(entry: E, at: ToolAxesSurface): E;
+/**
+ * The `toolAxes` question for ONE snapshot entry of either surface (`at`: an MCP server, an A2A peer) — asked by the preparation door (a
+ * refusal ends the prepare) and by each materialization entrance (a refusal fails that server's or that peer's dial), so there is one
+ * reading, one copy and one sentence whichever surface and whichever time it is asked. `ok: true` carries the entry with the reader's
+ * PLAIN COPY of the axes in place of the caller's object: what was judged is the very value the connect and every refresh read, not a
+ * live object that could answer differently later. The copy is frozen with the entry — a tool that shallow-copies a server
+ * (`mountedMcp()`) to customise its axes must not rewrite what the parent reads. `ok: false` carries the coded refusal
+ * (`config.invalid_argument`) naming the declarer, the tool (or skill) and the member, never a value.
  */
-export declare function judgeEntryToolAxes(copy: McpServerSpec): {
+export declare function judgeEntryToolAxes<E extends McpServerSpec | A2aServerSpec>(copy: E, at: ToolAxesSurface): {
     ok: true;
-    entry: McpServerSpec;
+    entry: E;
 } | {
     ok: false;
     error: Error & {
@@ -118,14 +171,13 @@ export declare function judgeEntryToolAxes(copy: McpServerSpec): {
  * The single preflight resolver: validate the lock declaration, refuse a spec that tries to occupy
  * a locked slot (`config.locked_key`, two-state — the whole prepare is rejected, nothing is
  * silently dropped or merged), and produce the resolved snapshot downstream assembly consumes.
- * Runs BEFORE any side effect of task preparation.
+ * Runs BEFORE any side effect of task preparation — and, on a resume, before the claim: the resume's
+ * screen calls this same function (`enter` naming each refusal's seat) and hands the leg the frozen
+ * entries it judged, so the leg's prepare judges engine-owned plain data and dials what was judged.
  */
-export declare function preflightLockedConfig(spec: TaskSpec, deps: RunnerDeps): LockedPreflight;
+export declare function preflightLockedConfig(spec: Pick<TaskSpec, "mcp" | "a2a" | "toolPolicy" | "basePolicyForResumeEdit">, deps: RunnerDeps, enter?: ConfigDoorEntry): LockedPreflight;
 /**
  * The two caller policies a prepare resolves to: the task's own seat over the deployment's, or the deployment's alone
- * under a `toolPolicy` lock. One resolution for the preflight above and for the resume ladder's pre-claim door.
+ * under a `toolPolicy` lock — one resolution, read by the preflight above (which a resume enters before its claim).
  */
 export declare function callerPolicySeats(spec: Pick<TaskSpec, "toolPolicy" | "basePolicyForResumeEdit">, deps: Pick<RunnerDeps, "toolPolicy" | "basePolicyForResumeEdit">, toolPolicyLocked: boolean): Pick<LockedPreflight, "toolPolicy" | "basePolicyForResumeEdit">;
-/** The retired-member door over the resolved caller policies: a member the engine no longer reads is refused by name
- *  (`config.deps_retired_key`), never dropped in silence. */
-export declare function assertCallerPoliciesCurrent(policies: Pick<LockedPreflight, "toolPolicy" | "basePolicyForResumeEdit">): void;

package/dist/core/locked-config.js

@@ -1,4 +1,7 @@
-import { readMcpToolAxes } from "./mcp-server-spec.js";
+import { types } from "node:util";
+import { DECLARATION_PATH_RULES, declarationFaultOf, declarerWord, readToolAxes, receiveDeclaration, toolAxesRefusal } from "./mcp-server-spec.js";
+import { isPlainRecord, receive } from "./mods/kernel/receive.js";
+import { CONFIG_RECEIPT_MODE } from "./own-property-receipt.js";
 import { isToolContentOrigin, TOOL_CONTENT_ORIGINS } from "./memory-engine/content-origin.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { assertNoRetiredToolPolicyKeys } from "./retired-keys.js";
@@ -8,6 +11,7 @@ export const LOCKED_KEY_REGISTRY = {
     compliancePosture: { specFields: [] },
     retentionPolicy: { specFields: [] },
 };
+export const ENTER_AS_IS = (_seat, door) => door();
 function codedError(code, message) {
     const e = new Error(message);
     e.code = code;
@@ -17,21 +21,74 @@ export function resolveLockedKeys(config) {
     if (config === undefined)
         return new Set();
     const keys = new Set();
-    for (const key of config.keys) {
-        if (!Object.prototype.hasOwnProperty.call(LOCKED_KEY_REGISTRY, key)) {
-            throw codedError("config.locked_registry", `lockedConfig.keys contains "${String(key)}", which is not a member of the locked-key registry ` +
-                `(${Object.keys(LOCKED_KEY_REGISTRY).join(", ")}). A lock that does not parse must not half-arm — ` +
-                `fix the deployment's lock declaration.`);
+    const listed = declaredLockKeys(config);
+    for (let index = 0; index < listed.length; index++) {
+        const key = listed[index];
+        if (!Object.hasOwn(LOCKED_KEY_REGISTRY, key)) {
+            throw lockDeclarationRefusal(`RunnerDeps.lockedConfig.keys[${index}]`, `is ${inlineUntrusted(JSON.stringify(key), 80)}, which is not a member of the locked-key registry (${Object.keys(LOCKED_KEY_REGISTRY).join(", ")})`);
         }
         keys.add(key);
     }
     return keys;
 }
+function declaredLockKeys(config) {
+    const received = receiveDeclaration(config);
+    if (!received.ok)
+        throw lockDeclarationRefusal(memberPath(received.fault.path, "RunnerDeps.lockedConfig"), `cannot be read: ${received.fault.problem}`);
+    const copy = received.value;
+    if (!isPlainRecord(copy))
+        throw lockDeclarationRefusal("RunnerDeps.lockedConfig", `is ${inlineUntrusted(describeDeclared(copy), 80)}, not an object with a \`keys\` list`);
+    const keys = Object.hasOwn(copy, "keys") ? copy["keys"] : undefined;
+    if (!Array.isArray(keys))
+        throw lockDeclarationRefusal("RunnerDeps.lockedConfig.keys", `is ${inlineUntrusted(describeDeclared(keys), 80)}, not a list of locked keys`);
+    return keys;
+}
+function lockDeclarationRefusal(member, problem) {
+    return codedError("config.locked_registry", `${member} ${problem}. A lock that does not parse must not half-arm — fix the deployment's lock declaration.`);
+}
 export function snapshotMcpEntries(entries) {
-    return entries.map((entry) => {
-        const { toolAxes, ...rest } = entry;
-        return Object.freeze((toolAxes === undefined ? rest : { ...rest, toolAxes }));
-    });
+    return entries.map((entry) => snapshotDeclaredEntry(entry, "mcp"));
+}
+function memberPath(path, base = "") {
+    let rendered = base;
+    for (const key of path) {
+        const name = typeof key === "string" && /^\d+$/.test(key) ? JSON.stringify(key) : String(key);
+        rendered += typeof key === "number" ? `[${key}]` : rendered === "" ? name : `.${name}`;
+        if (rendered.length > 120 + base.length)
+            break;
+    }
+    return rendered;
+}
+function unreadableDeclaration(at, declarer, member, problem) {
+    const refusal = codedError("config.invalid_argument", `${declarerWord(at)}${declarer === undefined ? "" : ` ${declarerNameOf(declarer)}`} declares ${inlineUntrusted(member, 80)} the engine cannot read: ${problem}. A declaration the engine cannot read is refused ` +
+        `rather than partly applied — what the caller wrote and what the engine runs on would otherwise differ without anyone being told.`);
+    if (declarer !== undefined)
+        Object.defineProperty(refusal, "declarer", { value: declarer, enumerable: true, writable: false, configurable: false });
+    return refusal;
+}
+function ownDataString(holder, key) {
+    const slot = Object.getOwnPropertyDescriptor(holder, key);
+    const value = slot !== undefined && Object.hasOwn(slot, "value") ? slot.value : undefined;
+    return typeof value === "string" ? value : undefined;
+}
+export function refusedDeclarer(refusal) {
+    return typeof refusal === "object" && refusal !== null && !types.isProxy(refusal) ? ownDataString(refusal, "declarer") : undefined;
+}
+function capturedName(entry) {
+    return typeof entry === "object" && entry !== null && !types.isProxy(entry) ? ownDataString(entry, "name") : undefined;
+}
+function entryFaultRefusal(at, declarer, path, problem) {
+    return unreadableDeclaration(at, declarer, path.length === 0 ? "an entry" : memberPath(path), problem);
+}
+export function snapshotDeclaredEntry(entry, at) {
+    const declared = entry;
+    const declarer = capturedName(declared);
+    const received = receiveDeclaration(declared, DECLARATION_PATH_RULES[at]);
+    if (!received.ok)
+        throw entryFaultRefusal(at, declarer, received.fault.path, received.fault.problem);
+    if (!isPlainRecord(received.value))
+        throw unreadableDeclaration(at, declarer, "an entry", `it is ${inlineUntrusted(describeDeclared(received.value), 80)}, not an object`);
+    return received.value;
 }
 function describeDeclared(value) {
     try {
@@ -46,58 +103,91 @@ function describeDeclared(value) {
         }
     }
 }
-const serverNameOf = (copy) => inlineUntrusted(typeof copy.name === "string" ? JSON.stringify(copy.name) : describeDeclared(copy.name), 80);
-export function judgeEntryToolAxes(copy) {
+const declarerNameOf = (name) => inlineUntrusted(typeof name === "string" ? JSON.stringify(name) : describeDeclared(name), 80);
+export function judgeEntryToolAxes(copy, at) {
     const { toolAxes: declaredAxes, ...rest } = copy;
-    const axes = readMcpToolAxes(declaredAxes);
-    if (!axes.ok) {
-        return {
-            ok: false,
-            error: codedError("config.invalid_argument", `MCP server ${serverNameOf(copy)} declares toolAxes the engine cannot read: ${inlineUntrusted(axes.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.`),
-        };
-    }
+    const axes = readToolAxes(declaredAxes, at);
+    if (!axes.ok)
+        return { ok: false, error: toolAxesRefusal(at, declarerNameOf(copy.name), axes.problem) };
     if (axes.toolAxes !== undefined) {
         for (const perTool of Object.values(axes.toolAxes))
             Object.freeze(perTool);
         Object.freeze(axes.toolAxes);
     }
-    return { ok: true, entry: Object.freeze(axes.toolAxes === undefined ? rest : { ...rest, toolAxes: axes.toolAxes }) };
+    return { ok: true, entry: Object.freeze((axes.toolAxes === undefined ? rest : { ...rest, toolAxes: axes.toolAxes })) };
+}
+function declaredEntriesOf(declared, at) {
+    const field = at;
+    const received = receive(declared, CONFIG_RECEIPT_MODE);
+    let problem;
+    if (received.ok) {
+        const list = received.value;
+        if (Array.isArray(list) && list !== declared)
+            return Array.from({ length: list.length }, (_, index) => list[index]);
+        problem = typeof list === "object" && list !== null ? "it is not an array" : `it is ${inlineUntrusted(describeDeclared(list), 80)}`;
+    }
+    else {
+        const fault = declarationFaultOf(received.fault);
+        if (fault.path.length > 0)
+            throw unreadableDeclaration(at, undefined, "an entry", fault.problem);
+        problem = fault.problem;
+    }
+    throw codedError("config.invalid_argument", `TaskSpec.${field} must be a readable array of ${declarerWord(at)} declarations; ${problem}. A list the engine cannot read ` +
+        `is refused rather than read as "no entries" — the declared ${declarerWord(at)}s would otherwise be dropped without anyone being told.`);
 }
-function snapshotAndValidateMcpEntries(entries) {
-    return snapshotMcpEntries(entries).map((copy) => {
+function snapshotAndValidateA2aEntries(declared) {
+    const entries = declaredEntriesOf(declared, "a2a");
+    if (entries.length === 0)
+        return undefined;
+    return entries.map((entry) => {
+        const judged = judgeEntryToolAxes(snapshotDeclaredEntry(entry, "a2a"), "a2a");
+        if (!judged.ok)
+            throw judged.error;
+        return judged.entry;
+    });
+}
+function snapshotAndValidateMcpEntries(declared) {
+    return snapshotMcpEntries(declaredEntriesOf(declared, "mcp")).map((copy) => {
         const declared = copy.contentOrigin;
         if (declared !== undefined && !isToolContentOrigin(declared)) {
-            throw codedError("config.mcp_content_class", `MCP server ${serverNameOf(copy)} declares contentOrigin ` +
+            throw codedError("config.mcp_content_class", `MCP server ${declarerNameOf(copy.name)} declares contentOrigin ` +
                 `${inlineUntrusted(describeDeclared(declared), 80)}, which is not one of ` +
                 `${TOOL_CONTENT_ORIGINS.map((v) => `"${v}"`).join(" | ")}. The declaration decides whether this server's tools ` +
                 `mark the session's memory externally exposed — a value this engine cannot read is refused at the door rather ` +
                 `than folded to a class, because folding it would let a deployment believe a declaration is in force while every ` +
                 `call keeps writing a one-way durable mark.`);
         }
-        const judged = judgeEntryToolAxes(copy);
+        const judged = judgeEntryToolAxes(copy, "mcp");
         if (!judged.ok)
             throw judged.error;
         return judged.entry;
     });
 }
-export function preflightLockedConfig(spec, deps) {
-    const lockedKeys = resolveLockedKeys(deps.lockedConfig);
-    for (const key of lockedKeys) {
-        for (const field of LOCKED_KEY_REGISTRY[key].specFields) {
-            if (spec[field] !== undefined) {
-                throw codedError("config.locked_key", `TaskSpec.${field} is administratively locked by this deployment (locked key "${key}") — ` +
-                    `the task-supplied value is refused wholesale (locks are config-time; there is no request-time ` +
-                    `unlock). Remove the field from the task, or change the deployment's lock configuration.`);
+export function preflightLockedConfig(spec, deps, enter = ENTER_AS_IS) {
+    const lockedKeys = enter("deps", () => resolveLockedKeys(deps.lockedConfig));
+    enter("taskConfig", () => {
+        for (const key of lockedKeys) {
+            for (const field of LOCKED_KEY_REGISTRY[key].specFields) {
+                if (spec[field] !== undefined) {
+                    throw codedError("config.locked_key", `TaskSpec.${field} is administratively locked by this deployment (locked key "${key}") — ` +
+                        `the task-supplied value is refused wholesale (locks are config-time; there is no request-time ` +
+                        `unlock). Remove the field from the task, or change the deployment's lock configuration.`);
+                }
             }
         }
-    }
-    const policies = callerPolicySeats(spec, deps, lockedKeys.has("toolPolicy"));
-    assertCallerPoliciesCurrent(policies);
+    });
+    const toolPolicyLocked = lockedKeys.has("toolPolicy");
+    const task = toolPolicyLocked ? {} : { toolPolicy: spec.toolPolicy, basePolicyForResumeEdit: spec.basePolicyForResumeEdit };
+    const policies = callerPolicySeats(task, deps, toolPolicyLocked);
+    enter(!toolPolicyLocked && task.toolPolicy != null ? "taskConfig" : "deps", () => assertNoRetiredToolPolicyKeys(policies.toolPolicy));
+    enter(!toolPolicyLocked && task.basePolicyForResumeEdit != null ? "taskConfig" : "deps", () => assertNoRetiredToolPolicyKeys(policies.basePolicyForResumeEdit));
+    const declaredServers = lockedKeys.has("mcp") ? undefined : spec.mcp;
+    const mcp = declaredServers === undefined ? undefined : enter("taskConfig", () => snapshotAndValidateMcpEntries(declaredServers));
+    const declaredPeers = spec.a2a;
     return {
         lockedKeys,
-        mcp: lockedKeys.has("mcp") || spec.mcp === undefined ? undefined : snapshotAndValidateMcpEntries(spec.mcp),
+        mcp,
+        a2a: declaredPeers === undefined ? undefined : enter("taskConfig", () => snapshotAndValidateA2aEntries(declaredPeers)),
         ...policies,
     };
 }
@@ -107,7 +197,3 @@ export function callerPolicySeats(spec, deps, toolPolicyLocked) {
         basePolicyForResumeEdit: toolPolicyLocked ? deps.basePolicyForResumeEdit : (spec.basePolicyForResumeEdit ?? deps.basePolicyForResumeEdit),
     };
 }
-export function assertCallerPoliciesCurrent(policies) {
-    assertNoRetiredToolPolicyKeys(policies.toolPolicy);
-    assertNoRetiredToolPolicyKeys(policies.basePolicyForResumeEdit);
-}

package/dist/core/mcp-probe.js

@@ -128,5 +128,5 @@ export async function probeMcpServers(specs, opts = {}) {
         fatal = { cause: abortCause(signal) };
     if (fatal !== undefined)
         throw fatal.cause;
-    return { entries: mcpManifestEntries(declared, statuses), servers };
+    return { entries: mcpManifestEntries(declared, statuses, servers.flatMap((s) => s?.tools ?? [])), servers };
 }

package/dist/core/mcp-server-spec.d.ts

@@ -1,3 +1,4 @@
+import { type ReceiptFault } from "./mods/kernel/receive.js";
 import type { ToolContentOrigin, ToolEffect } from "./tool-spec.js";
 import type { ToolFamily, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
 /** Definition of an MCP server to connect to for the duration of one task, then discard. */
@@ -61,7 +62,7 @@ export interface McpServerSpec {
      * a read-only tool can return third-party text, and a deployment's own writer brings back nothing
      * external — so vouching on one axis never quietly vouches on the other.
      *
-     * THE SHAPE IS JUDGED, NOT TRUSTED: {@link readMcpToolAxes} is the one reader of this declaration. The
+     * THE SHAPE IS JUDGED, NOT TRUSTED: {@link readToolAxes} is the one reader of this declaration (an A2A peer's `toolAxes` is read by it too). The
      * preparation door runs it on every entry, and a declaration it cannot read refuses the whole prepare
      * (`config.invalid_argument`) — one bad tool refuses the entry, a bad key is never dropped and a bad word
      * never defaults, because a caller's safety axis that silently reads as absent is a trust root that is not
@@ -167,12 +168,17 @@ export interface McpServerSpec {
 }
 type ToolAxes = NonNullable<McpServerSpec["toolAxes"]>;
 /**
- * {@link readMcpToolAxes}'s answer. `ok: true` carries the declaration as a PLAIN COPY the reader built from
+ * The surfaces that declare `toolAxes`, which {@link readToolAxes} names its reading by: an MCP server's keys are the server's
+ * remote TOOL names, an A2A peer's keys are the peer's remote SKILL ids.
+ */
+export type ToolAxesSurface = "mcp" | "a2a";
+/**
+ * {@link readToolAxes}'s answer. `ok: true` carries the declaration as a PLAIN COPY the reader built from
  * what it judged (never the caller's own object); `toolAxes` is absent when the entry declares nothing — no
  * key at all, or only empty per-tool objects (which the engine reads the same as no declaration). `ok: false`
- * carries one sentence naming the tool and the member that did not fit, never a value.
+ * carries one sentence naming the tool (or skill) and the member that did not fit, never a value.
  */
-export type McpToolAxesRead = {
+export type ToolAxesRead = {
     ok: true;
     toolAxes?: ToolAxes;
 } | {
@@ -180,18 +186,82 @@ export type McpToolAxesRead = {
     problem: string;
 };
 /**
- * The one reader of a raw {@link McpServerSpec.toolAxes} declaration — the engine's preparation door and
- * every host that assembles the field from JSON ask this same function. Absent ⇒ `{ ok: true }` (nothing
- * declared). Anything else must be an object of per-tool objects whose members are exactly `effect` /
+ * Where a declaration stops being one: the path from the declaration's root — a list index as a number, a member name as a string — and
+ * the clause that says what is there ("it contains itself; …"): a kind and a remedy, never a value the declarer wrote.
+ */
+export interface DeclarationFault {
+    readonly path: readonly (string | number)[];
+    readonly problem: string;
+}
+/** {@link receiveDeclaration}'s answer: the engine's own frozen copy, or where and why the declaration could not be received. */
+export type DeclarationRead = {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly fault: DeclarationFault;
+};
+/**
+ * A receipt's refusal of a declaration (or of the list that carries declarations), said as a declaration refusal says it. The receipt's
+ * path does not say which kind of container each name came from, so a segment of digits alone is read as a list index.
+ */
+export declare function declarationFaultOf(fault: ReceiptFault): DeclarationFault;
+/** What a declaration's own type fixes at one path, beyond being plain data: a string there, or a record of names to strings. */
+export interface DeclarationPathRule {
+    readonly path: readonly string[];
+    readonly holds: "a string" | "names to strings";
+    /** The member must be there (a declaration with no value at the path is refused, as one with a value of another kind is). */
+    readonly required?: true;
+}
+/**
+ * Per surface, every path its declaration's type fixes beyond plain data — the declarer's `name` (a string, always there) and every record
+ * the type writes as `Record<string, string>`: an MCP server's `transport.env` (a stdio server's environment) and `transport.headers` (an
+ * HTTP server's headers); an A2A peer's `headers`. A path that is not its surface's (an A2A peer's `transport`) is not judged by another
+ * surface's row: it is a member the surface does not read.
+ */
+export declare const DECLARATION_PATH_RULES: Readonly<Record<ToolAxesSurface, readonly DeclarationPathRule[]>>;
+/**
+ * The one reading of a declaration a caller hands the engine — an MCP server's or an A2A peer's entry (the snapshot), a `toolAxes`
+ * record ({@link readToolAxes}), a lock declaration: the engine's one receipt of a caller's object in its declaration mode, so the
+ * value is plain data held to the engine's one depth ({@link MODS_VALUE_DEPTH} levels below it) and every own member is read once, then, when the copy is a record, the declaration's own
+ * vocabulary over the copy (a list holds names; no member is named `__proto__`; each path `rules` names holds what its rule says — an
+ * entry's rules are its surface's {@link DECLARATION_PATH_RULES}). The copy is the answer — the caller's object is never handed on and
+ * never read again. A copy that is not a record is answered as it is, for the reader that expected a record to word.
+ */
+export declare function receiveDeclaration(declared: unknown, rules?: readonly DeclarationPathRule[]): DeclarationRead;
+/**
+ * The one reader of a raw `toolAxes` declaration — {@link McpServerSpec.toolAxes} and {@link A2aServerSpec.toolAxes} are the same
+ * declaration, and the engine's preparation door, its materialization of an MCP server and of an A2A peer, and every host that
+ * assembles the field from JSON ask this same function. `at` names the surface the declaration sits on, because that decides what its
+ * keys are called in the sentence: `"mcp"` — the server's remote tools; `"a2a"` — the peer's remote skills. Absent ⇒ `{ ok: true }`
+ * (nothing declared). Anything else must be an object of per-tool objects whose members are exactly `effect` /
  * `egress` / `irreversibility` with legal values; a declaration of any other shape, an empty tool name, an
  * unknown member, a word outside the vocabulary or a non-boolean `egress` on ANY one tool refuses the whole
  * declaration (`ok: false`) — the good tools are not kept and nothing is defaulted, since a caller axis is
  * two-way (it can vouch a tool down as well as mark it up) and a silently lost half is a trust root that is
  * not in force. The reader judges SHAPE only; whether the axes contradict each other (`egress` over a
- * non-write effect) is the ingestion's own arithmetic. The reader is total: a getter, a proxy trap or a tag
- * that throws while the declaration is read is a refusal that says so (never the thrown text), not a throw.
+ * non-write effect) is the ingestion's own arithmetic. The declaration is read once, as plain data, by {@link receiveDeclaration} — a
+ * Proxy, a map, a class instance, a record built on a prototype or in another realm, a getter that throws, a structure that contains
+ * itself, a tool named `__proto__` are refusals that say where they sit (never the thrown text), not a throw — and judged on that copy.
+ * `at` is the caller's own word, not the declarer's: one outside {@link ToolAxesSurface} throws `config.invalid_argument` naming the
+ * surfaces, whatever is declared.
+ */
+export declare function readToolAxes(declared: unknown, at: ToolAxesSurface): ToolAxesRead;
+/** {@link readToolAxes} for an MCP server's declaration — the entry a host that mounts MCP servers asks. */
+export declare function readMcpToolAxes(declared: unknown): ToolAxesRead;
+/**
+ * The word a sentence about one declaration of the surface `at` names the declarer by — `MCP server`, `A2A peer`. The same row the
+ * `toolAxes` refusal below reads, so every sentence the engine writes about a declaration it cannot read calls the declarer one thing.
+ */
+export declare function declarerWord(at: ToolAxesSurface): string;
+/**
+ * The refusal an entry's unreadable `toolAxes` becomes (`config.invalid_argument`), ONE sentence for every surface that declares them:
+ * the subject is the surface's declarer word and `name` (already quoted and bounded by the caller: `MCP server "db"`, `A2A peer "agent"`),
+ * `problem` is {@link readToolAxes}'s own sentence.
  */
-export declare function readMcpToolAxes(declared: unknown): McpToolAxesRead;
+export declare function toolAxesRefusal(at: ToolAxesSurface, name: string, problem: string): Error & {
+    code: "config.invalid_argument";
+};
 /** The identity of one mount of a declared server, as the host minted it ({@link McpServerSpec.fingerprint}). */
 export interface McpMountIdentity {
     readonly fingerprint: string;
@@ -242,6 +312,14 @@ export interface A2aServerSpec {
      * raise it — e.g. `{ egress: false, effect: "read" }` vouches that a skill only reads. Note that
      * lowering `effect` WITHOUT clearing `egress` is a contradiction prepare-task refuses by design (an
      * external write must be repeat-unsafe).
+     *
+     * THE SHAPE IS JUDGED, NOT TRUSTED, by the same reader as {@link McpServerSpec.toolAxes} ({@link readToolAxes} with `at: "a2a"`) and
+     * with the same disposition: a task's preparation door runs it on every peer of `TaskSpec.a2a`, and a declaration it cannot read
+     * refuses the whole prepare (`config.invalid_argument`, subject `A2A peer "<name>"`) before any peer is dialed — one bad skill refuses
+     * the task, a bad key is never dropped and a bad word never defaults. The materialization entrance (`materializeA2aTools`, the library
+     * entrance) asks it once per peer, when it reads that peer's declaration: there a declaration it cannot read fails THAT peer's dial
+     * (never dialed, a warning whose cause is the same refusal), its siblings unaffected; a refresh does not ask again, it dials the copy
+     * that was judged (a peer refused at the entrance is refused again by every refresh, from the stored refusal).
      */
     toolAxes?: Record<string, {
         effect?: ToolEffect;