@sema-agent/core 7.51.2 → 7.52.0

package/dist/core/hooks.js

@@ -1,11 +1,9 @@
-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 { abortedSeatDeny, decisionText, describeThrown, isEngineRefusal, ownArgs, 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 +11,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 +86,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 +189,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 +205,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 +234,8 @@ 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); return f !== undefined ? { face: f } : {}; })() }),
         preToolContext: [],
         hookAsk: undefined,
         parkFailed: undefined,
@@ -326,29 +245,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);
             }
@@ -362,7 +267,7 @@ export async function runToolGate(input) {
                 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/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;

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

@@ -148,6 +148,22 @@ 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"]>;
 /**

package/dist/core/mcp.d.ts

@@ -1,4 +1,4 @@
-import { type McpInstructionsEntry, type PromptSectionSeat } from "./prompt-section-seat.js";
+import { type McpInstructionsEntry, type PromptSectionDisposer } from "./prompt-section-seat.js";
 import { McpConnectionPool } from "./mcp-connection-pool.js";
 import { type McpDelivered, type McpFailureKind, type McpServerLiveness } from "./mcp-failure.js";
 import type { AgentTool } from "../internal/harness-types.js";
@@ -101,7 +101,7 @@ export interface MaterializedMcp {
     toolAxes: McpToolAxis[];
     /**
      * MCP server `instructions` (design/64 §17.3, CC `# MCP Server Instructions`): the optional guidance a
-     * connected server returns from `initialize`, after the host's disposition (`PromptProvider.section`,
+     * connected server returns from `initialize`, after the host's disposition (the `prompt.section` station,
      * applied once at the dial: a dropped entry is absent, a replaced one carries `author: "host"`). The
      * Runner injects these into the (stable) system prompt. One entry per server whose entry survived.
      */
@@ -443,11 +443,15 @@ export declare const MCP_IDLE_TIMEOUT_HTTP_DEFAULT_MS: number;
  *  `MCP_IDLE_TIMEOUT_HTTP`, else the CC-matched default). Exported for tests. */
 export declare function mcpIdleTimeoutMs(kind: "stdio" | "http"): number;
 /**
- * Startup-phase (connect + initial listTools) timeout override in ms (env `MCP_TIMEOUT`); undefined keeps
- * the SDK default. Startup deliberately stays bounded: a hung server at materialize time should fail open
- * into a skipped-server warning quickly, not stall task preparation indefinitely.
+ * Startup-phase (connect + initial listTools) timeout override in ms; undefined keeps the SDK default. Startup
+ * deliberately stays bounded: a hung server at materialize time should fail open into a skipped-server warning
+ * quickly, not stall task preparation indefinitely. THE one reader of the knob: with a `server`, that
+ * declaration's own `startupTimeoutMs` wins over env `MCP_TIMEOUT` (typed data held to the env knob's range
+ * [{@link MCP_ENV_MS_MIN}, {@link MCP_ENV_MS_MAX}], but REFUSED outside it — `config.mcp_startup_timeout_invalid`
+ * — where a process string is clamped and announced); without one, the process-level bound alone. The env value
+ * is resolved either way, so a bad one is announced even when a declaration shadows it.
  */
-export declare function mcpStartupTimeoutMs(): number | undefined;
+export declare function mcpStartupTimeoutMs(server?: Pick<McpServerSpec, "name" | "startupTimeoutMs">): number | undefined;
 /** The protocol-range condition name for a JSON-RPC error code, or `undefined` for every other code
  *  (see {@link MCP_SPEC_ERROR_CODE_NAMES}). */
 export declare function describeMcpSpecErrorCode(code: unknown): string | undefined;
@@ -605,7 +609,7 @@ reminderDisclosure?: {
 }, poolOpts?: {
     pool: McpConnectionPool;
     ownsPool?: boolean;
-}, promptSections?: PromptSectionSeat): Promise<MaterializedMcp>;
+}, promptSections?: PromptSectionDisposer): Promise<MaterializedMcp>;
 /**
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.
  * Unlike server hints, the caller may RAISE or LOWER any axis: `effect` sets the repeat-safety class (lower to