@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/hooks.js

@@ -1,11 +1,10 @@
-import { decisionText, describeThrown, receiveHookResult, isEngineRefusal, unaskedSeatAnswer } from "./tool-policy.js";
-import { asThrownError } from "./thrown-value.js";
-import { createSettlementLedger, engineFailClosedExit, hookDenyExit } from "./runner/gate-exit.js";
-import { traceHookCrash } from "./gate-crash-trace.js";
+import { argsAsTheToolReads, stampArgsReading } from "./effective-path-target.js";
+import { abortedSeatDeny, decisionText, describeThrown, isEngineRefusal, ownArgs, ownedReading, refuseOutOfContractDecision, unaskedSeatAnswer } from "./tool-policy.js";
+import { createSettlementLedger, engineFailClosedExit, hookDenyExit, unownedArgsExit } from "./runner/gate-exit.js";
+import { classicEventBase, dispatchClassic, ENGINE_CORE_ANSWER, engineCore, failedHandlerClause, judgedInputOf, observePermissionDenied, recordScreeningChain } from "./mods/stations.js";
 import { runGateFold } from "./gate-fold.js";
 import { runGateLanes } from "./gate-lanes.js";
 export { normalizeOrgGateVerdict, normalizePersistedRuleHit } from "./rule-lane-reads.js";
-export { cloneObserverInput } from "./runner/gate-exit.js";
 import { brandPolicyAskClass } from "./ask-class.js";
 import { isAskOrigin, screenAskClassMembers } from "./ask-origin.js";
 import { isAutoModeFallbackCause } from "./auto-mode.js";
@@ -13,92 +12,6 @@ import { inlineUntrusted } from "./untrusted-text.js";
 export { formatHookFeedback } from "./reminder-mint.js";
 import { createSafeNotifier } from "./safe-notify.js";
 import { wireOf } from "./tool-name-readings.js";
-export const DEFAULT_HOOK_TIMEOUT_MS = 600_000;
-export const MAX_HOOK_TIMEOUT_MS = 2_147_483_647;
-const POST_ABORT_GRACE_MS = 1_000;
-export function postAbortGraceMs(remainingMs) {
-    return Math.max(0, Math.min(POST_ABORT_GRACE_MS, remainingMs));
-}
-const badHookTimeoutReported = new WeakSet();
-export function resolveHookTimeoutMs(supplied, report, owner) {
-    if (supplied === undefined)
-        return DEFAULT_HOOK_TIMEOUT_MS;
-    if (Number.isFinite(supplied) && supplied >= 0 && supplied <= MAX_HOOK_TIMEOUT_MS)
-        return supplied;
-    if (report !== undefined && !(owner !== undefined && badHookTimeoutReported.has(owner))) {
-        if (owner !== undefined)
-            badHookTimeoutReported.add(owner);
-        try {
-            report(new Error(`Hooks.timeoutMs must be a non-negative finite number no greater than ${MAX_HOOK_TIMEOUT_MS} (got ${String(supplied)}) — ` +
-                `every hook seat falls back to the ${DEFAULT_HOOK_TIMEOUT_MS}ms default`));
-        }
-        catch {
-        }
-    }
-    return DEFAULT_HOOK_TIMEOUT_MS;
-}
-export async function runHookSeat(seat, bound, call) {
-    void seat;
-    const timeoutMs = resolveHookTimeoutMs(bound.timeoutMs, bound.onBadTimeout, bound.owner);
-    const taskSignal = bound.signal;
-    const controller = new AbortController();
-    const pending = Promise.resolve(call(controller.signal));
-    const startedAt = performance.now();
-    return await new Promise((resolve, reject) => {
-        let settled = false;
-        let listening = false;
-        let timer;
-        const clearTimer = () => {
-            if (timer !== undefined)
-                clearTimeout(timer);
-            timer = undefined;
-        };
-        const finish = (act) => {
-            if (settled)
-                return;
-            settled = true;
-            clearTimer();
-            if (listening)
-                taskSignal?.removeEventListener("abort", onAbort);
-            act();
-        };
-        const expire = (cause) => finish(() => {
-            void pending.then(undefined, () => {
-            });
-            resolve({ expired: true, cause });
-            queueMicrotask(() => {
-                try {
-                    controller.abort();
-                }
-                catch {
-                }
-            });
-        });
-        const collapseToGrace = () => {
-            if (settled)
-                return;
-            clearTimer();
-            timer = setTimeout(() => expire("aborted"), postAbortGraceMs(timeoutMs - (performance.now() - startedAt)));
-        };
-        const onAbort = () => (bound.abortEnds === true ? expire("aborted") : collapseToGrace());
-        timer = setTimeout(() => expire("timeout"), timeoutMs);
-        if (taskSignal !== undefined) {
-            if (taskSignal.aborted) {
-                onAbort();
-            }
-            else {
-                taskSignal.addEventListener("abort", onAbort, { once: true });
-                listening = true;
-            }
-        }
-        pending.then((value) => finish(() => resolve({ expired: false, value })), (err) => finish(() => reject(asThrownError(err))));
-    });
-}
-export function hookSeatExpiredError(seat, timeoutMs, cause, consequence) {
-    return new Error(cause === "timeout"
-        ? `the deployment's ${seat} hook did not answer within its ${timeoutMs}ms bound (Hooks.timeoutMs) — ${consequence}`
-        : `the deployment's ${seat} hook had not answered when the task was cancelled — ${consequence}`);
-}
 const reflectApply = Reflect.apply;
 const getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
 const getPrototypeOf = Object.getPrototypeOf;
@@ -174,54 +87,92 @@ export function mintHookInvocationIdentity(facts) {
         ...(facts.parentToolCallId !== undefined ? { parentToolCallId: facts.parentToolCallId } : {}),
     }));
 }
-function preToolUseCrashReason(subject, err) {
-    const cause = inlineUntrusted(describeThrown(err), 200);
-    return (`a PreToolUse hook crashed while screening ${subject}; the call was NOT executed (fail-closed). ` +
-        `This is a failure of the deployment's hook, NOT of the tool itself — an identical retry reaches the ` +
-        `same hook and fails the same way. Hook error: ${cause || "(no message)"}`);
+function screenPreToolUseResult(r) {
+    if (r === undefined || r === null || r === false)
+        return r;
+    return refuseOutOfContractDecision(r, { reasonIsNonInput: true });
 }
-function preToolUseUnansweredReason(subject, timeoutMs, cause) {
-    return cause === "timeout"
-        ? `a PreToolUse hook did not answer within its ${timeoutMs}ms bound while screening ${subject}; the call was ` +
-            `NOT executed (fail-closed). This is a failure of the deployment's hook, NOT of the tool itself — the ` +
-            `screening face never returned a verdict, so nothing was decided about this call either way.`
-        : `the task was cancelled while a PreToolUse hook was still screening ${subject}; the call was NOT executed ` +
-            `(fail-closed). No verdict was reached — this is the run ending, not the tool failing.`;
+function preToolUseAnswerViolation(answer) {
+    const r = screenPreToolUseResult(answer);
+    if (r === undefined || r === null || r === false || !isEngineRefusal(r))
+        return undefined;
+    return typeof r.message === "string" ? r.message : "the PreToolUse answer was refused by the engine";
 }
-function screenPreToolUseResult(r) {
-    if (r === undefined)
+function preToolUseRefusedReason(subject, failed) {
+    if (failed === undefined) {
+        return `the task was cancelled while a PreToolUse hook was still screening ${subject}; the call was NOT executed ` + `(fail-closed). No verdict was reached — this is the run ending, not the tool failing.`;
+    }
+    const tail = failed.cause === "threw"
+        ? ` This is a failure of the deployment's hook, NOT of the tool itself — an identical retry reaches the same hook and fails the same way.`
+        : failed.cause === "timeout"
+            ? ` This is a failure of the deployment's hook, NOT of the tool itself — the screening face never returned a verdict, so nothing was decided about this call either way.`
+            : "";
+    return `a PreToolUse hook ${failedHandlerClause(failed)} while screening ${subject}; the call was NOT executed (fail-closed).${tail}`;
+}
+export function createPreToolUseScreening(input) {
+    const bus = input.modBus;
+    if (bus === undefined || !bus.hasHandlers("classic.PreToolUse"))
         return undefined;
-    return receiveHookResult(r);
+    const { toolCallId, toolName } = input.event;
+    const screenedName = wireOf("gate.preToolUse", input.event);
+    const eventOf = (args) => {
+        const cwd = input.trackedCwd?.();
+        return {
+            ...classicEventBase(input.identity, input.observedPermissionMode?.()),
+            tool: screenedName,
+            tool_use_id: toolCallId,
+            input: judgedInputOf(args),
+            ...(typeof cwd === "string" ? { cwd } : {}),
+            ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}),
+        };
+    };
+    return {
+        screen: async (args, subject) => {
+            let outcome;
+            try {
+                outcome = await dispatchClassic(bus, "classic.PreToolUse", eventOf(args), { ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}), checkAnswer: preToolUseAnswerViolation });
+            }
+            catch (err) {
+                return { kind: "refused", reason: preToolUseRefusedReason(subject, { kind: "failed", registration: "engine", cause: "threw", reason: `could not raise the screening: ${describeThrown(err)}`, skipped: [] }) };
+            }
+            if (outcome === undefined || outcome.kind === "aborted")
+                return { kind: "refused", reason: preToolUseRefusedReason(subject, undefined) };
+            if (outcome.kind === "failed")
+                return { kind: "refused", reason: preToolUseRefusedReason(subject, outcome) };
+            const r = screenPreToolUseResult(outcome.answer);
+            return { kind: "answered", answer: r === null || r === false ? undefined : r, ...(outcome.answeredBy !== undefined ? { answeredBy: outcome.answeredBy } : {}) };
+        },
+        deniedReason: (answer) => decisionText(answer) ?? `tool "${toolName}" blocked by a PreToolUse hook`,
+    };
 }
-export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash, timeoutMs) {
-    return brandPolicyAskClass({
+export function createPreToolUseConstraintPolicy(chain, env) {
+    const judges = (p) => !p.observe;
+    const minted = brandPolicyAskClass({
         check: async (req, signal) => {
+            if (!chain.hasHandlers("classic.PreToolUse", judges))
+                return { action: "allow" };
             const unasked = unaskedSeatAnswer(req, signal, { aborted: `the inherited PreToolUse screening of "${req.toolName}" was not consulted: the run or turn was already interrupted`, unreachable: `the inherited PreToolUse screening of "${req.toolName}" was not consulted: nobody can be asked about this call` }, "hook");
             if (unasked !== undefined)
                 return unasked;
-            let r;
-            const boundMs = resolveHookTimeoutMs(timeoutMs, onCrash);
+            const subject = `this call to "${req.toolName}"`;
+            let outcome;
             try {
-                const seat = await runHookSeat("preToolUse", { timeoutMs: boundMs }, (sig) => preToolUse(req.toolName, req.args, { toolCallId: req.toolCallId, toolName: req.toolName, signal: sig, ...(env !== undefined ? { env } : {}) }));
-                if (seat.expired) {
-                    try {
-                        onCrash?.(hookSeatExpiredError("preToolUse", boundMs, seat.cause, `the inherited screening of "${req.toolName}" was refused fail-closed`));
-                    }
-                    catch {
-                    }
-                    return { action: "deny", message: preToolUseUnansweredReason(`this call to "${req.toolName}"`, boundMs, seat.cause), decisionReason: "hook" };
-                }
-                r = screenPreToolUseResult(seat.value);
+                outcome = await chain.dispatch("classic.PreToolUse", { tool: req.toolName, tool_use_id: req.toolCallId, input: judgedInputOf(req.args), ...(env !== undefined ? { env } : {}) }, {
+                    bottom: engineCore,
+                    participant: judges,
+                    ...(signal !== undefined ? { signal } : {}),
+                    checkAnswer: (a) => (a === ENGINE_CORE_ANSWER ? undefined : preToolUseAnswerViolation(a)),
+                });
             }
             catch (err) {
-                try {
-                    onCrash?.(err);
-                }
-                catch {
-                }
-                return { action: "deny", message: preToolUseCrashReason(`this call to "${req.toolName}"`, err), decisionReason: "hook" };
+                return { action: "deny", message: preToolUseRefusedReason(subject, { kind: "failed", registration: "engine", cause: "threw", reason: `could not raise the screening: ${describeThrown(err)}`, skipped: [] }), decisionReason: "hook" };
             }
-            if (r === undefined)
+            if (outcome.kind === "aborted")
+                return abortedSeatDeny(req, `the inherited PreToolUse screening of "${req.toolName}" ended when the run or turn was interrupted`, "hook");
+            if (outcome.kind === "failed")
+                return { action: "deny", message: preToolUseRefusedReason(subject, outcome), decisionReason: "hook" };
+            const r = screenPreToolUseResult(outcome.answer);
+            if (r === undefined || r === null || r === false)
                 return { action: "allow" };
             if (r.action === "deny") {
                 return { action: "deny", message: decisionText(r) ?? `tool "${req.toolName}" blocked by a PreToolUse hook`, decisionReason: "hook" };
@@ -239,6 +190,8 @@ export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash, timeo
             return r.updatedInput !== undefined ? { action: "allow", updatedInput: r.updatedInput, ...stated } : { action: "allow", ...stated };
         },
     }, "hook");
+    recordScreeningChain(minted, chain);
+    return minted;
 }
 export function askCarryRowMembers(carry) {
     if (carry === undefined)
@@ -253,54 +206,21 @@ export function askCarryRowMembers(carry) {
         ...(classed !== undefined ? classed : {}),
     };
 }
-export function createPreToolUseScreening(preToolUse, input, hookSeatMs, notifier) {
-    if (preToolUse === undefined)
-        return undefined;
-    const { toolCallId, toolName } = input.event;
-    const screenedName = wireOf("gate.preToolUse", input.event);
-    const hookCtx = (seatSignal) => ({
-        toolCallId,
-        toolName: screenedName,
-        ...(seatSignal !== undefined ? { signal: seatSignal } : {}),
-        ...(() => {
-            const c = input.trackedCwd?.();
-            return typeof c === "string" ? { cwd: c } : {};
-        })(),
-        ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}),
-        ...(input.identity !== undefined ? { identity: input.identity } : {}),
-    });
-    const bound = { timeoutMs: hookSeatMs, ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}), abortEnds: true };
-    return {
-        screen: (args) => runHookSeat("preToolUse", bound, (sig) => preToolUse(screenedName, args, hookCtx(sig))),
-        screened: screenPreToolUseResult,
-        crashReason: preToolUseCrashReason,
-        unansweredReason: async (subject, cause) => {
-            if (cause === "timeout")
-                traceHookCrash(input, hookSeatExpiredError("preToolUse", hookSeatMs, cause, `${subject} was NOT executed (fail-closed) and the screening face was signalled to stop`), notifier);
-            return preToolUseUnansweredReason(subject, hookSeatMs, cause);
-        },
-        deniedReason: (answer) => decisionText(answer) ?? `tool "${toolName}" blocked by a PreToolUse hook`,
-        refusedReason: (answer) => String(answer.message ?? `the PreToolUse hook's result for "${toolName}" was refused by the engine`),
-    };
-}
 export async function runToolGate(input) {
-    const { event, preToolUse, adjudicate, resolveAsk, suspendAsk } = input;
+    const { event, adjudicate, resolveAsk, suspendAsk } = input;
     const { toolCallId, toolName } = event;
     const callSignal = input.callSignal;
     const modelInput = event.input;
+    const owned = ownArgs(modelInput);
+    const args = owned.ok ? owned.value : modelInput;
     const notifier = createSafeNotifier(input.onNotifyError !== undefined ? { onError: input.onNotifyError } : undefined);
-    const hookSeatMs = resolveHookTimeoutMs(input.hookTimeoutMs, (err) => traceHookCrash(input, err, notifier));
-    const observerBound = { timeoutMs: hookSeatMs, ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}) };
-    const notifyPermissionDeniedSeat = async (payload) => {
-        if (input.permissionDenied === undefined)
-            return;
-        await notifier.notifyAsync(async () => {
-            const seat = await runHookSeat("permissionDenied", observerBound, (sig) => input.permissionDenied?.({ ...payload, signal: sig }));
-            if (seat.expired)
-                throw hookSeatExpiredError("permissionDenied", hookSeatMs, seat.cause, "the deny observation was abandoned; the deny itself is unchanged");
-        }, "toolGate.permissionDenied");
+    const notifyPermissionDeniedSeat = (payload) => {
+        const mode = input.observedPermissionMode?.();
+        const seen = mode !== undefined ? { ...payload, permissionMode: mode } : payload;
+        const onHostObserverFailure = (err) => void notifier.notify(() => { throw err; }, "toolGate.permissionDenied");
+        return observePermissionDenied({ legBus: input.modBus, hostObserver: input.permissionDenied, payload: seen, signal: input.abortSignal, onHostObserverFailure });
     };
-    const screening = createPreToolUseScreening(preToolUse, input, hookSeatMs, notifier);
+    const screening = createPreToolUseScreening(input);
     const pass = {
         input,
         event,
@@ -315,8 +235,9 @@ export async function runToolGate(input) {
         notifyPermissionDenied: notifyPermissionDeniedSeat,
         screening,
         afterFold: runGateLanes,
-        currentInput: modelInput,
-        req: { toolName, args: modelInput, toolCallId, ...(() => { const f = input.toolFaceOf?.(toolName); return f !== undefined ? { face: f } : {}; })() },
+        currentInput: args,
+        req: Object.freeze({ toolName, args, toolCallId, ...(() => { const f = input.toolFaceOf?.(toolName); const read = event.readArguments; if (f !== undefined && read !== undefined)
+                stampArgsReading(f, ownedReading(read)); return f !== undefined ? { face: f } : {}; })() }),
         preToolContext: [],
         hookAsk: undefined,
         parkFailed: undefined,
@@ -326,29 +247,15 @@ export async function runToolGate(input) {
         tightenedBy: undefined,
         policyRewrite: undefined,
     };
+    if (!owned.ok)
+        return await unownedArgsExit(pass, owned.reason);
     if (screening !== undefined) {
-        let r;
-        let unanswered;
-        try {
-            const seat = await screening.screen(pass.currentInput);
-            if (seat.expired)
-                unanswered = seat.cause;
-            else
-                r = screening.screened(seat.value);
-        }
-        catch (err) {
-            const reason = screening.crashReason(`this call to "${toolName}"`, err);
-            traceHookCrash(input, err, notifier);
-            return await engineFailClosedExit(pass, reason);
-        }
-        if (unanswered !== undefined) {
-            const reason = await screening.unansweredReason(`this call to "${toolName}"`, unanswered);
-            return await engineFailClosedExit(pass, reason);
+        const screened = await screening.screen(pass.currentInput, `this call to "${toolName}"`);
+        if (screened.kind === "refused") {
+            return await engineFailClosedExit(pass, screened.reason);
         }
+        const r = screened.answer;
         if (r) {
-            if (isEngineRefusal(r)) {
-                return await engineFailClosedExit(pass, screening.refusedReason(r));
-            }
             if (r.additionalContext) {
                 pass.preToolContext.push(r.additionalContext);
             }
@@ -356,13 +263,13 @@ export async function runToolGate(input) {
                 return hookDenyExit(pass, screening.deniedReason(r));
             }
             if (r.updatedInput !== undefined) {
-                pass.currentInput = r.updatedInput;
+                pass.currentInput = argsAsTheToolReads(pass.req, r.updatedInput);
             }
             if (r.action === "ask") {
                 pass.hookAsk = r;
             }
             if (r.action === "allow")
-                pass.hookAllowed = true;
+                pass.hookAllowedBy = screened.answeredBy !== undefined ? [screened.answeredBy] : [];
         }
     }
     return await runGateFold(pass);

package/dist/{tools/fs → core}/image-admission.d.ts

@@ -24,9 +24,27 @@
  * before the frame and the transcript read them. A block whose bytes the admission refuses becomes a text
  * block that names the tool, the refusal and the size — never the bytes, and never silently nothing.
  */
-import type { DocumentContent, ImageContent } from "../../internal/llm.js";
-import { type ImageDimensions, type ImageDownsampler } from "../../core/mcp.js";
-import { type MediaBlock } from "../../core/media-byte-cap.js";
+import type { DocumentContent, ImageContent } from "../internal/llm.js";
+import { type ImageDimensions, type ImageDownsampler } from "./image-downsample.js";
+import { type MediaBlock } from "./media-byte-cap.js";
+/** Byte cap on a Read-image WITHOUT a downsampler: an image file is returned AS a visual
+ *  `ImageContent` block (base64) rather than refused. Bounded so a huge image cannot blow the request.
+ *  This stat-time cap only bounds the READ; the accept/refuse decision is the base64 gate below (the
+ *  provider limit is on base64 LENGTH, so the effective no-sharp accept bound is raw ≤ 3.75MB). */
+export declare const MAX_IMAGE_READ_BYTES: number;
+/** Byte cap on a Read-image WITH a downsampler: sharp can shrink a big photo to CC's 2000×2000/3.75MB
+ *  target, so the smaller hard refusal does not apply (CC readImageWithTokenBudget reads the file
+ *  unbounded; we keep an OOM sanity bound — deliberate delta, camera photos fit comfortably). */
+export declare const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES: number;
+/** Max raw size sent whole as a document block (CC `PDF_TARGET_RAW_SIZE`). */
+export declare const PDF_TARGET_RAW_SIZE: number;
+/** Verify the raw bytes actually ARE the image format the extension claims (magic-number sniff). Extension alone
+ *  is forgeable: a `.png` holding text / an empty file / a truncated blob would otherwise become a malformed
+ *  `ImageContent` that makes the NEXT provider request fail (400). Pure — no I/O. */
+export declare function imageMagicMatches(bytes: Uint8Array, mimeType: string): boolean;
+/** True when the bytes start with the `%PDF-` magic. Magic outranks extension both ways: a mis-named
+ *  `.pdf` without it is refused, and a non-`.pdf` file carrying it is read AS a PDF. */
+export declare function pdfMagicMatches(bytes: Uint8Array): boolean;
 /** The image types the content API accepts — the only ones a signature check can verify. */
 export declare const ADMITTED_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
 /** The raw-byte read cap for an image, with or without a downsampler. */

package/dist/{tools/fs → core}/image-admission.js

@@ -1,9 +1,27 @@
-import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
-import { claimedMediaType } from "../../core/media-byte-cap.js";
-import { readMember } from "../../core/thrown-value.js";
-import { imageMagicMatches } from "./safety.js";
-import { MAX_IMAGE_READ_BYTES, MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES } from "./fs-shared.js";
-import { PDF_TARGET_RAW_SIZE, pdfMagicMatches } from "./pdf.js";
+import { MCP_IMAGE_MAX_BASE64 } from "./image-downsample.js";
+import { claimedMediaType } from "./media-byte-cap.js";
+import { readMember } from "./thrown-value.js";
+export const MAX_IMAGE_READ_BYTES = 5 * 1024 * 1024;
+export const MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES = 64 * 1024 * 1024;
+export const PDF_TARGET_RAW_SIZE = 20 * 1024 * 1024;
+export function imageMagicMatches(bytes, mimeType) {
+    const b = bytes;
+    switch (mimeType) {
+        case "image/png":
+            return b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 && b[4] === 0x0d && b[5] === 0x0a && b[6] === 0x1a && b[7] === 0x0a;
+        case "image/jpeg":
+            return b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff;
+        case "image/gif":
+            return b.length >= 6 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38 && (b[4] === 0x37 || b[4] === 0x39) && b[5] === 0x61;
+        case "image/webp":
+            return b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 && b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50;
+        default:
+            return false;
+    }
+}
+export function pdfMagicMatches(bytes) {
+    return bytes.length >= 5 && bytes[0] === 0x25 && bytes[1] === 0x50 && bytes[2] === 0x44 && bytes[3] === 0x46 && bytes[4] === 0x2d;
+}
 export const ADMITTED_IMAGE_MIME_TYPES = Object.freeze(["image/png", "image/jpeg", "image/gif", "image/webp"]);
 export function imageReadCap(downsampler) {
     return downsampler ? MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES : MAX_IMAGE_READ_BYTES;

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;