@sema-agent/core 7.51.2 → 7.53.0

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-connection-pool.d.ts

@@ -56,8 +56,11 @@ export declare class McpConnectionPool {
      * transport object that answers differently to two readers cannot split the dial from its key); every other transport member is read here.
      * The declaration's mount identity (`fingerprint`) is part of the key when declared: the revocation probe is asked with it, so two mounts the
      * host tells apart never share one connection (an undeclared fingerprint leaves the key as it always was).
+     * So is the startup bound the dial runs under (`startupMs`, the dial's one reading of {@link mcpStartupTimeoutMs}, threaded like `kind`):
+     * a connection is dialled under the declaration of the mount that dials it, so a mount never waits on, or shares, a dial bounded by
+     * another mount's clock. No bound in force (none declared, no environment seat) leaves the key as it always was.
      */
-    static keyOf(spec: McpServerSpec, principal: string | undefined, kind: string | undefined): string;
+    static keyOf(spec: McpServerSpec, principal: string | undefined, kind: string | undefined, startupMs: number | undefined): string;
     /**
      * Lease the connection for `key`, dialling it with `dial` when none is live. `fresh` replaces the pool's current connection with a new
      * dial (a re-dial): the connection it replaces lives on until its other holders release it. Resolves `undefined` once the pool is

package/dist/core/mcp-connection-pool.js

@@ -4,10 +4,15 @@ export class McpConnectionPool {
     dialing = new Map();
     generation = new Map();
     shut = false;
-    static keyOf(spec, principal, kind) {
+    static keyOf(spec, principal, kind, startupMs) {
         const rest = Object.fromEntries(Object.keys(spec.transport).filter((k) => k !== "kind").map((k) => [k, Reflect.get(spec.transport, k)]));
         const fingerprint = spec.fingerprint;
-        return canonicalize(fingerprint === undefined ? [spec.name, kind ?? null, rest, principal ?? null] : [spec.name, kind ?? null, rest, principal ?? null, fingerprint]);
+        const identity = [spec.name, kind ?? null, rest, principal ?? null];
+        if (fingerprint !== undefined)
+            identity.push(fingerprint);
+        if (startupMs !== undefined)
+            identity.push({ startupTimeoutMs: startupMs });
+        return canonicalize(identity);
     }
     async acquire(key, dial, opts) {
         if (this.shut)

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

@@ -38,15 +38,17 @@ export interface McpProbeOptions {
      *  on a real leg — so a server that applies per-user rules answers the probe as it would answer the
      *  task. */
     principal?: string;
-    /** Per-server ceiling on the VERDICT, in whole milliseconds within `[1, MCP_ENV_MS_MAX]` (the ceiling
-     *  every env-supplied MCP bound keeps, because a larger delay is silently rewritten to 1 ms). When it
-     *  elapses, THAT server's row reads `failed` with `errorCode: "timeout"` and the walk moves on; nothing
-     *  throws. It does NOT end the dial — nothing here can — so the transport stays open until the dial
-     *  lands on its own; see the residue note on {@link probeMcpServers}.
+    /** An OVERALL ceiling on the VERDICT for each server, in whole milliseconds within `[1, MCP_ENV_MS_MAX]` (the
+     *  ceiling every env-supplied MCP bound keeps, because a larger delay is silently rewritten to 1 ms). The
+     *  caller's own choice, and it lives BESIDE the per-phase startup bounds the dial runs under — whichever
+     *  arrives first decides. When it elapses, THAT server's row reads `failed` with `errorCode: "timeout"` and
+     *  the walk moves on; nothing throws. It does NOT end the dial — nothing here can — so the transport stays
+     *  open until the dial lands on its own; see the residue note on {@link probeMcpServers}.
      *
-     *  Default: the engine's own startup-phase bound ({@link mcpStartupTimeoutMs}, env `MCP_TIMEOUT`) when a
-     *  deployment set one; absent there, this module runs no clock and the answer for that server is
-     *  whatever the dial's own request budgets produce — which bound the REQUESTS, not the dial. */
+     *  Default: none. The probe has no clock of its own: it dials through the entrance a task does, so each
+     *  startup phase (the handshake, then the initial listing) carries that server's own bound from the one
+     *  reader ({@link import("./mcp.js").mcpStartupTimeoutMs}: its `startupTimeoutMs`, else env `MCP_TIMEOUT`, else
+     *  the SDK's 60 000 ms) — exactly what a task allows it. */
     timeoutMs?: number;
     /** Abort the whole probe. The call rejects with the signal's own reason (a bare `abort()` gives an
      *  `AbortError`) AFTER every server it had opened is closed — see the residue contract on
@@ -102,7 +104,8 @@ export interface McpProbeOptions {
  * return, and NOT that the call itself is bounded. What bounds it, stated part by part rather than
  * summarised into a number that would be wrong:
  *  · a dial has two REQUEST-BUDGET phases, each carrying the startup-phase bound ({@link
- *    mcpStartupTimeoutMs}, env `MCP_TIMEOUT`, else the SDK's 60 000 ms default): the handshake, one
+ *    import("./mcp.js").mcpStartupTimeoutMs}: the server's own `startupTimeoutMs`, else env `MCP_TIMEOUT`, else the SDK's
+ *    60 000 ms default): the handshake, one
  *    request; and the initial tool listing, a PAGINATED WALK whose whole budget is that same number
  *    (however many pages it takes — and no request at all when the peer advertises no tools). Two
  *    budgets, so twice that, not once;

package/dist/core/mcp-probe.js

@@ -1,7 +1,7 @@
 import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { snapshotMcpEntries } from "./locked-config.js";
 import { classifyMcpFailure, livenessOf } from "./mcp-failure.js";
-import { MCP_ENV_MS_MAX, materializeMcpTools, mcpStartupTimeoutMs } from "./mcp.js";
+import { MCP_ENV_MS_MAX, materializeMcpTools } from "./mcp.js";
 import { findNamespacePrefixCollision } from "./protocol-naming.js";
 import { MCP_NAMESPACE } from "./protocol-table.js";
 import { mcpManifestEntries } from "./runner/prepare-wiring-manifest.js";
@@ -62,7 +62,7 @@ function stoppedWaitingStatus(entry, ms) {
 }
 export async function probeMcpServers(specs, opts = {}) {
     const declared = snapshotMcpEntries(specs);
-    const timeoutMs = wholeInRange("timeoutMs", opts.timeoutMs, 1, MCP_ENV_MS_MAX) ?? mcpStartupTimeoutMs();
+    const timeoutMs = wholeInRange("timeoutMs", opts.timeoutMs, 1, MCP_ENV_MS_MAX);
     const concurrency = wholeInRange("concurrency", opts.concurrency, 1, Number.MAX_SAFE_INTEGER) ?? 1;
     const onElicit = opts.onElicit ?? DECLINE_EVERY_ELICITATION;
     const signal = opts.signal;
@@ -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
@@ -148,15 +149,36 @@ export interface McpServerSpec {
      * (`config.mcp_fingerprint_invalid`).
      */
     fingerprint?: string;
+    /**
+     * THIS server's startup bound, in whole milliseconds: the handshake (connect + initialize) and the initial tool listing each carry it
+     * (the listing as one walk, however many pages). One knob, three seats, read by one function in this order — this member, else the
+     * process-level `MCP_TIMEOUT`, else the MCP SDK's own 60 000 ms — so a server that hangs at startup is cut on its own clock while its
+     * siblings keep the deployment's. It bounds only that startup phase: a call's own timeout (`MCP_TOOL_TIMEOUT`) is untouched.
+     *
+     * The range is the one every MCP millisecond bound keeps, 1 000 to 2 147 483 647 (a larger delay is silently rewritten to 1 ms by the
+     * timer, a smaller one is a unit slip). Unlike the environment seat — a string a process may clamp and announce — a declaration is typed
+     * data, so anything else (a string, a fraction, zero, a negative, NaN, `null`, a number outside the range) refuses THIS server at its
+     * dial (`config.mcp_startup_timeout_invalid`; siblings mount) rather than being clamped or read as the default.
+     *
+     * The bound a dial runs under (this member, else the environment seat) is part of a pooled connection's identity: mounts under one
+     * bound lease ONE connection, mounts under different bounds dial their own — so a mount is never held by another mount's clock.
+     * The no-run probe has no clock of its own: each startup phase carries this same bound (a caller's `timeoutMs` is an overall ceiling beside it).
+     */
+    startupTimeoutMs?: number;
 }
 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;
 } | {
@@ -164,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 readMcpToolAxes(declared: unknown): McpToolAxesRead;
+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 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;
@@ -226,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;