@sema-agent/server 7.92.1 → 7.93.0

package/dist/capabilities/mcp-probe.js

@@ -0,0 +1,318 @@
+import { probeMcpServers } from "@sema-agent/core";
+import { createHash } from "node:crypto";
+import { createFixedWindowRateLimiter } from "../device-enrollment.js";
+import { canonicalJson } from "../canonical-json.js";
+import { echoKeyName, keyClosureClause, scanKeyClosure } from "../request-key-closure.js";
+import { CONTENT_ORIGIN_WORDS, describeBadContentOrigin, isContentOriginWord } from "../mcp-content-origin.js";
+import { HTTP_MCP_TRANSPORT_KEYS, MAX_REQUEST_MCP_SERVERS, MCP_ENTRY_EMPTY_ARRAY_KEYS, MCP_ENTRY_EMPTY_RECORD_KEYS, MCP_SERVER_ENTRY_KEYS, MCP_TRANSPORT_EMPTY_ARRAY_KEYS, MCP_TRANSPORT_EMPTY_RECORD_KEYS, STDIO_MCP_TRANSPORT_KEYS, validateRequestMcp, } from "../task-mcp.js";
+import { buildDisplaySafeUrl } from "../trace/redact.js";
+import { projectWiringManifestMcpRows } from "../trace/project.js";
+export const MCP_PROBE_REFUSAL_CODES = [
+    "capability.mcp_injection_required",
+    "limit.rate_exceeded",
+    "request.body_shape",
+    "request.field_invalid",
+    "state.mcp_probe_incomplete",
+];
+export const MCP_PROBE_HTTP_STATUS = {
+    "capability.mcp_injection_required": 501,
+    "limit.rate_exceeded": 429,
+    "request.body_shape": 400,
+    "request.field_invalid": 400,
+    "state.mcp_probe_incomplete": 503,
+};
+export const MCP_PROBE_RATE_POLICY = { limit: 12, windowMs: 60_000 };
+export const MCP_PROBE_CACHE_TTL_MS = 30_000;
+export const MCP_PROBE_CACHE_MAX_ENTRIES = 256;
+export const MCP_PROBE_MAX_INFLIGHT = 32;
+export const MCP_PROBE_VERDICT_TIMEOUT_MS = 10_000;
+export function buildMcpProbeWalkTimeoutMs(declarations) {
+    return Math.ceil(Math.max(1, declarations) / MCP_PROBE_CONCURRENCY) * MCP_PROBE_VERDICT_TIMEOUT_MS + MCP_PROBE_RESIDUE_SLACK_MS;
+}
+export const MCP_PROBE_CONCURRENCY = 8;
+export const MCP_PROBE_RESIDUE_SLACK_MS = 4_000;
+export const MCP_PROBE_OUTCOMES = ["probed", "cached", "empty", "gate_closed", "rate_limited", "bad_request", "failed"];
+const PROBE_BODY_KEYS = ["mcpServers"];
+const ACCEPTED_PROBE_BODY = new Set(PROBE_BODY_KEYS);
+const NO_TOLERATED_KEYS = new Set();
+const shapeRefusal = (message, unknownKeys) => ({
+    errorCode: "request.body_shape",
+    message,
+    ...(unknownKeys !== undefined ? { unknownKeys } : {}),
+});
+const fieldRefusal = (message) => ({ errorCode: "request.field_invalid", message });
+function entryKeyIssue(entry, at) {
+    const buckets = { unknown: [], unsupported: [] };
+    scanKeyClosure(entry, `${at}.`, new Set(MCP_SERVER_ENTRY_KEYS), NO_TOLERATED_KEYS, buckets);
+    const t = entry.transport;
+    if (t !== null && typeof t === "object" && !Array.isArray(t)) {
+        const kind = t.kind;
+        const keys = kind === "stdio" ? STDIO_MCP_TRANSPORT_KEYS : kind === "http" ? HTTP_MCP_TRANSPORT_KEYS : undefined;
+        if (keys !== undefined)
+            scanKeyClosure(t, `${at}.transport.`, new Set(keys), NO_TOLERATED_KEYS, buckets);
+    }
+    if (buckets.unknown.length === 0)
+        return null;
+    buckets.unknown.sort();
+    return shapeRefusal(`body: unrecognized key(s) on an MCP declaration — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
+        `${keyClosureClause(buckets.unknown, "unknown (not an mcpServers[] key — check the spelling)")}. ` +
+        `Accepted per entry: ${[...MCP_SERVER_ENTRY_KEYS].sort().join(",")} (transport.kind "stdio": ${[...STDIO_MCP_TRANSPORT_KEYS].sort().join(",")}; "http": ${[...HTTP_MCP_TRANSPORT_KEYS].sort().join(",")})`, buckets.unknown);
+}
+function entryValueIssue(entry, at) {
+    const read = validateRequestMcp([entry]);
+    if (read === null)
+        return fieldRefusal(`${at} is not a readable MCP declaration`);
+    const dropped = read.dropped[0];
+    if (dropped !== undefined || read.ok.length !== 1) {
+        const field = dropped?.field ?? "entry";
+        return fieldRefusal(`${at}.${field} is not a usable value${urlEchoFor(entry, field)} — this endpoint refuses the whole list rather than dialing a silently shortened one` +
+            ` (a task submission would instead drop just this declaration and mount its siblings; a probe answering "can I use these" must not quietly answer about fewer)`);
+    }
+    if (read.badContentOrigin.length > 0) {
+        return fieldRefusal(`${at}.contentOrigin must be one of ${CONTENT_ORIGIN_WORDS.map((w) => `"${w}"`).join(" | ")} — got ${describeBadContentOrigin(entry.contentOrigin)} (omit the key for the default: this server's tools classify as external content)`);
+    }
+    return declarationDowngradeIssue(entry, read.ok[0], at);
+}
+function declarationDowngradeIssue(entry, spec, at) {
+    if (spec === undefined)
+        return fieldRefusal(`${at} is not a readable MCP declaration`);
+    const diff = jsonPathDiff(stripEquivalentEmpties(entry), stripEquivalentEmpties(spec), at);
+    if (diff.length === 0)
+        return null;
+    diff.sort();
+    return fieldRefusal(`${keyClosureClause(diff, "unusable value(s)")} — this deployment's declaration reader could not use these exactly as written, and a probe must not dial a configuration that differs from the one you declared` +
+        " (a task submission would instead keep the server and silently drop just these, which is why the two faces disagree here on purpose; this endpoint refuses, because the reading would then describe a server you did not ask about)");
+}
+function stripEquivalentEmpties(entry) {
+    const emptyRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0;
+    const emptyArray = (v) => Array.isArray(v) && v.length === 0;
+    const keep = (bag, recordKeys, arrayKeys) => {
+        const out = {};
+        for (const [k, v] of Object.entries(bag)) {
+            if (recordKeys.includes(k) && emptyRecord(v))
+                continue;
+            if (arrayKeys.includes(k) && emptyArray(v))
+                continue;
+            out[k] = v;
+        }
+        return out;
+    };
+    const top = keep(entry, MCP_ENTRY_EMPTY_RECORD_KEYS, MCP_ENTRY_EMPTY_ARRAY_KEYS);
+    const t = top.transport;
+    if (t !== null && typeof t === "object" && !Array.isArray(t)) {
+        top.transport = keep(t, MCP_TRANSPORT_EMPTY_RECORD_KEYS, MCP_TRANSPORT_EMPTY_ARRAY_KEYS);
+    }
+    return top;
+}
+function jsonPathDiff(a, b, path) {
+    if (canonicalJson(a) === canonicalJson(b))
+        return [];
+    const aRec = a !== null && typeof a === "object" && !Array.isArray(a) ? a : undefined;
+    const bRec = b !== null && typeof b === "object" && !Array.isArray(b) ? b : undefined;
+    if (aRec !== undefined && bRec !== undefined) {
+        const out = [];
+        for (const k of new Set([...Object.keys(aRec), ...Object.keys(bRec)]))
+            out.push(...jsonPathDiff(aRec[k], bRec[k], `${path}.${k}`));
+        return out.length > 0 ? out : [path];
+    }
+    if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) {
+        const out = [];
+        for (let i = 0; i < a.length; i++)
+            out.push(...jsonPathDiff(a[i], b[i], `${path}[${i}]`));
+        return out.length > 0 ? out : [path];
+    }
+    return [path];
+}
+function urlEchoFor(entry, field) {
+    if (field !== "transport.url")
+        return "";
+    const t = entry.transport;
+    const raw = t !== null && typeof t === "object" ? t.url : undefined;
+    return typeof raw === "string" ? ` (got "${buildDisplaySafeUrl(raw)}"; an MCP declaration's address must be an http(s) URL — put credentials in transport.headers, never in the URL)` : "";
+}
+export function readMcpProbeBody(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return { ok: false, refusal: shapeRefusal("body must be a JSON object of the shape { mcpServers: [ … ] } (the same declaration list a task submits)") };
+    const buckets = { unknown: [], unsupported: [] };
+    scanKeyClosure(raw, "", ACCEPTED_PROBE_BODY, NO_TOLERATED_KEYS, buckets);
+    if (buckets.unknown.length > 0) {
+        buckets.unknown.sort();
+        return {
+            ok: false,
+            refusal: shapeRefusal(`body: unrecognized top-level key(s) — refused rather than dropped, because a dropped key reads as "in effect" to the caller. ` +
+                `${keyClosureClause(buckets.unknown, "unknown (this face takes only the declaration list)")}. ` +
+                `Accepted: ${[...ACCEPTED_PROBE_BODY].sort().join(",")}`, buckets.unknown),
+        };
+    }
+    const list = raw.mcpServers;
+    if (!Array.isArray(list))
+        return { ok: false, refusal: shapeRefusal("mcpServers must be an array of MCP server declarations (send [] to ask about nothing)") };
+    if (list.length > MAX_REQUEST_MCP_SERVERS) {
+        return { ok: false, refusal: fieldRefusal(`mcpServers carries ${list.length} declarations, above this deployment's ceiling of ${MAX_REQUEST_MCP_SERVERS} — the probe dials every one of them, so the list is refused whole rather than silently truncated to a partial answer`) };
+    }
+    for (let i = 0; i < list.length; i++) {
+        const at = `mcpServers[${i}]`;
+        const entry = list[i];
+        if (entry === null || typeof entry !== "object" || Array.isArray(entry))
+            return { ok: false, refusal: shapeRefusal(`${at} must be an object`) };
+        const keyIssue = entryKeyIssue(entry, at);
+        if (keyIssue)
+            return { ok: false, refusal: keyIssue };
+        const valueIssue = entryValueIssue(entry, at);
+        if (valueIssue)
+            return { ok: false, refusal: valueIssue };
+    }
+    const validated = validateRequestMcp(list);
+    if (validated === null || validated.ok.length !== list.length) {
+        return {
+            ok: false,
+            refusal: fieldRefusal(`mcpServers: this deployment's declaration reader answered differently for the list (${validated === null ? 0 : validated.ok.length}) than it did entry by entry (${list.length}),` +
+                " so the probe refuses rather than dialing a silently shortened list. This is a belt on a path that should not be reachable (the reader is deterministic and the list was already capped)," +
+                " so nothing in your body needs changing — if you see it, this deployment has a bug worth reporting"),
+        };
+    }
+    return { ok: true, specs: validated.ok };
+}
+export function buildMcpProbeIdentity(principal) {
+    return principal !== undefined && principal.length > 0 ? principal : "local";
+}
+export function buildMcpProbeCacheKey(principal, specs) {
+    return `${buildMcpProbeIdentity(principal)}::${createHash("sha256").update(canonicalJson(specs), "utf8").digest("hex")}`;
+}
+export function buildMcpProbeRateKey(principal) {
+    return `mcp-probe:${buildMcpProbeIdentity(principal)}`;
+}
+export function createMcpProbeLocal() {
+    const rate = createFixedWindowRateLimiter(MCP_PROBE_RATE_POLICY);
+    const cache = new Map();
+    const pruneCache = (now) => {
+        const settled = (v) => v.settledAt !== undefined;
+        for (const [k, v] of cache)
+            if (v.settledAt !== undefined && now - v.settledAt > MCP_PROBE_CACHE_TTL_MS)
+                cache.delete(k);
+        if (cache.size <= MCP_PROBE_CACHE_MAX_ENTRIES)
+            return;
+        const victims = [...cache.entries()].filter(([, v]) => settled(v)).sort((a, b) => (a[1].settledAt ?? 0) - (b[1].settledAt ?? 0));
+        for (const [k] of victims) {
+            if (cache.size <= MCP_PROBE_CACHE_MAX_ENTRIES)
+                break;
+            cache.delete(k);
+        }
+    };
+    return {
+        check: async (key) => await rate.check(key),
+        cached: (key, now) => {
+            const hit = cache.get(key);
+            if (hit === undefined)
+                return undefined;
+            if (hit.settledAt === undefined)
+                return hit.body;
+            if (now - hit.settledAt > MCP_PROBE_CACHE_TTL_MS) {
+                cache.delete(key);
+                return undefined;
+            }
+            return hit.body;
+        },
+        remember: (key, at, walk, now = () => Date.now()) => {
+            cache.set(key, { settledAt: undefined, body: walk.answer });
+            void walk.dials.then(() => {
+                const cur = cache.get(key);
+                if (cur?.body === walk.answer)
+                    cur.settledAt = now();
+            }, () => {
+                const cur = cache.get(key);
+                if (cur?.body === walk.answer)
+                    cache.delete(key);
+            });
+            pruneCache(at);
+        },
+        size: () => cache.size,
+        inflight: () => [...cache.values()].filter((v) => v.settledAt === undefined).length,
+    };
+}
+export function createMcpProbeWalk(specs, principal, now = Date.now) {
+    const bound = buildMcpProbeWalkTimeoutMs(specs.length);
+    const controller = new AbortController();
+    const dials = probeMcpServers(specs, {
+        ...(principal !== undefined && principal.length > 0 ? { principal } : {}),
+        timeoutMs: MCP_PROBE_VERDICT_TIMEOUT_MS,
+        concurrency: MCP_PROBE_CONCURRENCY,
+        signal: controller.signal,
+    });
+    dials.catch(() => undefined);
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort(new McpProbeIncomplete(bound));
+            reject(new McpProbeIncomplete(bound));
+        }, bound);
+    });
+    const answer = (async () => {
+        try {
+            const result = await Promise.race([dials, deadline]);
+            const rows = projectWiringManifestMcpRows(result.entries) ?? [];
+            if (rows.length !== specs.length) {
+                throw new Error(`mcp probe row count ${rows.length} does not match the ${specs.length} declarations it must align with by index — refusing to publish a list a consumer would mis-pair`);
+            }
+            return { probedAt: new Date(now()).toISOString(), ttlSec: Math.floor(MCP_PROBE_CACHE_TTL_MS / 1000), servers: rows };
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    })();
+    answer.catch(() => undefined);
+    return { answer, dials };
+}
+export class McpProbeIncomplete extends Error {
+    boundMs;
+    constructor(boundMs) {
+        super("mcp probe walk did not settle within this deployment's bound");
+        this.boundMs = boundMs;
+        this.name = "McpProbeIncomplete";
+    }
+}
+export function buildMcpProbeIncompleteRefusal(boundMs) {
+    return {
+        errorCode: "state.mcp_probe_incomplete",
+        message: `the MCP probe did not finish within ${boundMs / 1000}s, so this endpoint has no honest per-server answer to give and will not return a partial one that reads as complete — ` +
+            "the usual cause is a declared server that completes its handshake and then stops answering, which the engine cannot cancel (its dial owns no deadline). " +
+            "Retrying may well succeed; if it keeps happening, the declaration that never answers is the thing to fix",
+    };
+}
+export function buildEmptyMcpProbeFace(now = Date.now()) {
+    return { probedAt: new Date(now).toISOString(), ttlSec: Math.floor(MCP_PROBE_CACHE_TTL_MS / 1000), servers: [] };
+}
+export function buildMcpInjectionRefusal() {
+    return {
+        errorCode: "capability.mcp_injection_required",
+        message: "this deployment does not honor caller-supplied MCP declarations, so it will not dial them on your behalf: " +
+            "either it is multi-tenant (REQUIRE_PRINCIPAL=true — a tenant must not make the shared worker run an arbitrary command or connect to a body-chosen address), " +
+            "or `mcp` is an administratively locked config key, or its compliance posture denies `mcp_servers`. " +
+            "Read `capabilities.mcpInjection` to tell before asking; `GET /v1/capabilities/mcp` reports this deployment's OWN declared servers and stays available",
+    };
+}
+export function buildMcpProbeRateRefusal() {
+    return {
+        errorCode: "limit.rate_exceeded",
+        message: "MCP probe rate limit exceeded — this face dials every declared server, so it is capped per caller identity " +
+            `(${MCP_PROBE_RATE_POLICY.limit} per ${MCP_PROBE_RATE_POLICY.windowMs / 1000}s per replica) independently of every other limit on this deployment; ` +
+            `a reading already taken is reused for ${MCP_PROBE_CACHE_TTL_MS / 1000}s and does NOT consume the cap`,
+    };
+}
+export function buildMcpProbeInflightRefusal() {
+    return {
+        errorCode: "limit.rate_exceeded",
+        message: `too many MCP probes are still dialing on this replica (${MCP_PROBE_MAX_INFLIGHT} at once) — this endpoint refuses rather than opening one more set of connections, ` +
+            "and it deliberately does not drop an in-flight walk to make room (that would remove the one guarantee that keeps a repeated question from re-dialing). " +
+            `Retry-After is a HINT, not a promise: each server's verdict is bounded (${MCP_PROBE_VERDICT_TIMEOUT_MS / 1000}s) but a peer that answers the handshake and then stalls holds its dial with no deadline at all`,
+    };
+}
+export function buildMcpProbeDeclarationRefusal() {
+    return {
+        errorCode: "request.field_invalid",
+        message: "mcpServers: the engine refused this declaration SET as a whole before dialing anything — the usual cause is two declarations that would mount under one tool-namespace prefix, " +
+            "which a task submission refuses the same way, so a probe must not answer as if one of them had been dropped. Give every declared server a name that stays distinct after namespacing",
+    };
+}
+//# sourceMappingURL=mcp-probe.js.map

package/dist/http/resume-legs.js

@@ -1,10 +1,10 @@
 import { redactErrorMessage, redactHead } from "../observability/run-terminal.js";
 import { createHash } from "node:crypto";
-import { uuidv7, resumeWithVerification, CheckpointError, defaultTaskRegistry, validatePendingSteer, GLOBAL_USAGE_KEY, terminalProjection, PAUSE_REGISTRY } from "@sema-agent/core";
+import { uuidv7, resumeWithVerification, CheckpointError, defaultTaskRegistry, validatePendingSteer, GLOBAL_USAGE_KEY, PAUSE_REGISTRY } from "@sema-agent/core";
 import { decideParkedAgent, denyWorkflowParksUnreadable, findParkOrigin, planWorkflowParkedDecide } from "../parked-decide.js";
 import { HttpError, decodeCheckpointScope, CHECKPOINT_PUBLIC_SCOPE } from "../security.js";
 import { evictIfConflict, parkToolCallId, TurnAnchorCapture, HEARTBEAT_MS, markChildrenStoppedByUserOnAbort } from "../runs.js";
-import { failureCodeOf, nestedPauseOf, stripResumeToken } from "../terminal.js";
+import { failureCodeOf, nestedPauseOf, sealResultForExit, outwardPlane } from "../terminal.js";
 import { mintCancelledResult } from "../run-cancel-context.js";
 import {} from "../host-decision.js";
 import { readTurnActivityMs, recordTurnActivity } from "../turn-activity.js";
@@ -30,6 +30,7 @@ import { mintAndDriveDurableRun } from "./durable-run-leg.js";
 import { createSessionsLocal } from "./routes/sessions.js";
 import { createSessionSyncLocal } from "./routes/session-sync.js";
 import { createImagesLocal } from "./routes/images.js";
+import { createCapabilitiesLocal } from "./routes/capabilities.js";
 import { gatedPrincipal, explicitOperatorOk } from "./principal-gate.js";
 import { buildActiveRunConflict, resumeEntryForGate } from "./active-run-conflict.js";
 import { commitPlacement, devicePlacementErrorBody } from "./device-placement.js";
@@ -550,7 +551,7 @@ export function createResumeLegs(ctx) {
                     resumeLegLive = true;
                     const vr = await resumeWithVerification(legRunner, token, outcome, { ...resumeTaskConfig, signal: cancelCtrl.signal, preemptSignal: preemptCtrl.signal }, resumeObjective, verifyRounds, verifyInternals);
                     await commitResumeCtx();
-                    let safe = stripResumeToken(vr);
+                    let safe = sealResultForExit(vr);
                     const vrNested = nestedPauseOf(vr.terminal);
                     const reParkStatus = nestedParkStatusOf(vr);
                     const reSuspended = vrNested !== undefined;
@@ -679,7 +680,7 @@ export function createResumeLegs(ctx) {
                     if (taskId)
                         steerableRuns.set(taskId, stream);
                     if (!taskId || !rs)
-                        return await stream.result();
+                        return sealResultForExit(await stream.result());
                     onAccepted?.(acceptedResumingReceipt(taskId, sessionId));
                     for await (const ev of stream) {
                         recordTurnActivity(taskId);
@@ -790,7 +791,7 @@ export function createResumeLegs(ctx) {
                     }
                     await flush();
                     const r = await stream.result();
-                    const rPark = r.terminal.kind === "paused" ? terminalProjection(r.terminal).status : undefined;
+                    const rPark = r.terminal.kind === "paused" ? outwardPlane(r.terminal).status : undefined;
                     if (rPark === "suspended") {
                         const parkCallId = await parkToolCallId(r, deps.checkpointStore);
                         await append("suspended", { gate: r.terminal.kind === "paused" ? r.terminal.gate : null, ...(parkCallId !== undefined ? { toolCallId: parkCallId } : {}) });
@@ -812,7 +813,7 @@ export function createResumeLegs(ctx) {
                         }
                         return r;
                     }
-                    const safe = await attachModelUsage(stripResumeToken(r), { append, getEvents: (id, a) => rs.getEvents(id, a), modelUsage: deps.modelUsage, taskId });
+                    const safe = await attachModelUsage(sealResultForExit(r), { append, getEvents: (id, a) => rs.getEvents(id, a), modelUsage: deps.modelUsage, taskId });
                     await append("done", { result: safe });
                     if (taskConfig.suggestNextPrompts && safe.terminal.kind === "completed") {
                         const suggestions = await stream.suggestions().catch(() => []);
@@ -951,16 +952,17 @@ export function createResumeLegs(ctx) {
         }
         evictIfConflict(deps.runner, sessionId, result);
         const checkpointReopened = reopenConfirmedPark;
-        const resumePlane = terminalProjection(result.terminal);
+        const sealed = sealResultForExit(result);
+        const resumePlane = outwardPlane(sealed.terminal);
         if (taskId && deps.runStore) {
             if (resumePlane.status === "suspended" || checkpointReopened)
                 await deps.runStore.setSuspended(taskId);
             else if (resumePlane.status === "needs_review")
                 await deps.runStore.setNeedsReview(taskId);
             else
-                await deps.runStore.setTerminal(taskId, resumePlane.status, stripResumeToken(result), resumePlane.errorMessage ?? null);
+                await deps.runStore.setTerminal(taskId, resumePlane.status, sealed, resumePlane.errorMessage ?? null);
         }
-        settleFleet(checkpointReopened ? "suspended" : resumePlane.status, fleetRunResiduals(result));
+        settleFleet(checkpointReopened ? "suspended" : resumePlane.status, fleetRunResiduals(sealed));
         return {
             status: 200,
             body: {
@@ -1243,7 +1245,7 @@ export function createResumeLegs(ctx) {
         deps,
         registry: { idemCache, inflightRuns, preemptableRuns, cancelledViaVerb, steerableRuns, wakeParkMints, counters },
         helpers: { readJson, readRawBody, rateLimited, quotaExceeded, ownerQuotaDenied, leaseDenied, ownerLeaseDenied, usageWindowDenied, safeDecode, isFleetWide, runOwnerOk, sessionOwnerScope, sessionOwnerScopeForWrite, runSessionAcceptOk },
-        local: { images: createImagesLocal(deps), sessions: createSessionsLocal(), sessionSync: createSessionSyncLocal() },
+        local: { images: createImagesLocal(deps), sessions: createSessionsLocal(), sessionSync: createSessionSyncLocal(), capabilities: createCapabilitiesLocal() },
         legs: { prepareSpec, finalizeTaskResult, resumeCheckpoint, driveResumeIntoRunLog, resumePreempted, resumeWake, resumePlanReview },
     };
     return { routeCtxBase, resumeCheckpoint, driveResumeIntoRunLog, driveResumeLeg, mayDiscloseRowError, resumePreempted, startFreshHostTurn, resumeWake, resumePlanReview };

package/dist/http/route-ctx.d.ts

@@ -21,6 +21,7 @@ import type { FlatServiceDeps, RequestAuth } from "./server.js";
 import type { TaskRequestBody, DecideBinding } from "./wire-types.js";
 import type { IdempotencyCache, SubmitOutcome } from "./idempotency.js";
 import type { ImagesLocal } from "./routes/images.js";
+import type { CapabilitiesLocal } from "./routes/capabilities.js";
 import type { SessionsLocal } from "./routes/sessions.js";
 import type { SessionSyncLocal } from "./routes/session-sync.js";
 import type { PlanApprovePermissionModeAfter } from "../task-settings.js";
@@ -87,6 +88,8 @@ export interface RouteHelpers {
  *  (模块级会把 rate-limiter / 缓存跨实例串味,测试里一个进程建几十个 server)。 */
 export interface RouteLocals {
     images: ImagesLocal;
+    /** S-481:`GET /v1/capabilities/mcp` / `POST /v1/capabilities/mcp/probe` 的 TTL 缓存与每 principal 限速窗。 */
+    capabilities: CapabilitiesLocal;
     sessions: SessionsLocal;
     sessionSync: SessionSyncLocal;
 }

package/dist/http/routes/capabilities.d.ts

@@ -6,10 +6,19 @@
  * 本域零可变状态;deps 面宽(能力布尔逐条对应各路由的 501 门,单源不许漂移)但全是存在性只读。
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { type McpProbeLocal } from "../../capabilities/mcp-probe.js";
 import type { RouteCtx, RouteMatch, RouteIdsOf } from "../route-ctx.js";
 /** 路由体 = 从 `server.ts` 的 `handle()` 里**整段剪切**过来的原文(唯一改动:统一去缩进两格)。裸 `return;`
  *  的语义原样 =「本域已应答」;走到函数尾才是「没匹配上」,置 `miss.fell` 交回装配器继续下一个域。
  *  跨域的东西(deps / 助手 / 单域状态 / 每请求量)一律在首行解构出来,于是下面每一行都逐字不变。 */
+/**
+ * S-481 —— 本域独占的运行期状态(每 `createHttpServer` 实例一份)。**模块级不行**:测试里一个进程建几十台
+ * server,一张模块级缓存会把 A 台的探测读数发给 B 台,一只模块级限速窗会让第二台起来就被第一台的计数挡住。
+ */
+export interface CapabilitiesLocal {
+    readonly mcpProbe: McpProbeLocal;
+}
+export declare function createCapabilitiesLocal(): CapabilitiesLocal;
 export declare function handleCapabilities(req: IncomingMessage, res: ServerResponse, match: RouteMatch<CapabilitiesRouteId>, ctx: RouteCtx): Promise<void>;
 export declare const CAPABILITIES_ROUTES: readonly [{
     readonly id: "models";
@@ -24,6 +33,14 @@ export declare const CAPABILITIES_ROUTES: readonly [{
     readonly pattern: RegExp;
     readonly label: "/v1/capabilities/scenarios/:name";
     readonly methods: readonly ["GET"];
+}, {
+    readonly id: "capability-mcp";
+    readonly path: "/v1/capabilities/mcp";
+    readonly methods: readonly ["GET"];
+}, {
+    readonly id: "capability-mcp-probe";
+    readonly path: "/v1/capabilities/mcp/probe";
+    readonly methods: readonly ["POST"];
 }];
 /** 本域可分派行的 `id` 闭集 —— handler 的 `switch` 按它判穷尽(漏一口 = 编译红)。 */
 export type CapabilitiesRouteId = RouteIdsOf<typeof CAPABILITIES_ROUTES>;

package/dist/http/routes/capabilities.js

@@ -6,6 +6,8 @@ import { cwdHonored, deviceCwdHonored } from "../../task-cwd.js";
 import { DEVICE_PROTOCOL_VERSION, DEVICE_WS_PATH } from "../../device-ws-protocol.js";
 import { a2aInjectionHonored } from "../../task-a2a.js";
 import { mcpInjectionHonored } from "../../task-mcp.js";
+import { buildEmptyMcpProbeFace, buildMcpInjectionRefusal, buildMcpProbeCacheKey, buildMcpProbeInflightRefusal, buildMcpProbeRateKey, buildMcpProbeRateRefusal, createMcpProbeLocal, buildMcpProbeDeclarationRefusal, buildMcpProbeIncompleteRefusal, McpProbeIncomplete, MCP_PROBE_HTTP_STATUS, MCP_PROBE_MAX_INFLIGHT, MCP_PROBE_VERDICT_TIMEOUT_MS, createMcpProbeWalk, readMcpProbeBody, } from "../../capabilities/mcp-probe.js";
+import { mcpForScenario } from "../../config-center/facade.js";
 import { sendJson, sendError } from "../send.js";
 import { assertNever } from "../route-ctx.js";
 import { resolveStreamApprovalGate } from "../../tool-approval.js";
@@ -19,7 +21,7 @@ import { workflowModelAllowlistFor, selfOrchestrationDenial } from "../../task-w
 import { centerEntitlementSourceWired } from "../../runtime-caps-resolver.js";
 import { judgeAutoModeArming } from "../../auto-mode-face.js";
 import { coercePermissionModeStrict, SETTINGS_PERMISSION_MODE_WORDS } from "../../task-settings.js";
-import { gatedPrincipal } from "../principal-gate.js";
+import { gatedPrincipal, sendPrincipalRefusal } from "../principal-gate.js";
 function routePairingOf(deps, name, m) {
     if (isSealedKeyPoison(deps.config.modelApiKeys?.[name]))
         return "unknown";
@@ -33,6 +35,9 @@ function retentionAdvertisement(config) {
         return null;
     return { mode: sweep.mode, maxAgeDays: policy.maxAgeDays };
 }
+export function createCapabilitiesLocal() {
+    return { mcpProbe: createMcpProbeLocal() };
+}
 export async function handleCapabilities(req, res, match, ctx) {
     const { deps } = ctx;
     switch (match.decl.id) {
@@ -138,6 +143,7 @@ export async function handleCapabilities(req, res, match, ctx) {
                 modelUsage: Boolean(deps.runStore && deps.modelUsage),
                 sessionInit: true,
                 mcp: true,
+                mcpProbe: true,
                 mcpElicitation: Boolean(deps.elicitation),
                 askUserQuestion: Boolean(deps.question),
                 toolApproval: Boolean(deps.toolApproval),
@@ -188,6 +194,33 @@ export async function handleCapabilities(req, res, match, ctx) {
             });
             return;
         }
+        case "capability-mcp": {
+            const principal = gatedPrincipal(req, deps.config);
+            if (deps.config.requirePrincipal && !principal) {
+                sendPrincipalRefusal(res, req, deps.config);
+                return;
+            }
+            await serveMcpProbeFace(res, ctx, principal, mcpForScenario(deps.config.mcpServers, deps.config.defaultScenario) ?? [], "deployment");
+            return;
+        }
+        case "capability-mcp-probe": {
+            const principal = gatedPrincipal(req, deps.config);
+            if (deps.config.requirePrincipal && !principal) {
+                sendPrincipalRefusal(res, req, deps.config);
+                return;
+            }
+            if (!mcpInjectionHonored(deps.config)) {
+                sendMcpProbeRefusal(res, ctx, buildMcpInjectionRefusal(), "gate_closed");
+                return;
+            }
+            const parsed = readMcpProbeBody(await ctx.helpers.readJson(req));
+            if (!parsed.ok) {
+                sendMcpProbeRefusal(res, ctx, parsed.refusal, "bad_request");
+                return;
+            }
+            await serveMcpProbeFace(res, ctx, principal, parsed.specs, "caller");
+            return;
+        }
         case "models": {
             const atCatalog = expandTiers(deps.config.models, deps.config.tiers ?? {}) ?? deps.config.models;
             const atAllowlist = deps.config.atModelAllowlist ?? [];
@@ -215,9 +248,68 @@ export async function handleCapabilities(req, res, match, ctx) {
             return assertNever(match.decl.id);
     }
 }
+function sendMcpProbeRefusal(res, ctx, refusal, outcome, retryAfterSec) {
+    ctx.deps.metrics?.inc("mcp_probe_total", { outcome });
+    const status = MCP_PROBE_HTTP_STATUS[refusal.errorCode];
+    if (retryAfterSec !== undefined)
+        res.setHeader("retry-after", String(retryAfterSec));
+    sendError(res, status, refusal.errorCode, refusal.message, {
+        ...(refusal.unknownKeys !== undefined ? { unknownKeys: refusal.unknownKeys } : {}),
+        ...(retryAfterSec !== undefined ? { retryAfterSec } : {}),
+    });
+}
+async function serveMcpProbeFace(res, ctx, principal, specs, declaredBy) {
+    const { deps } = ctx;
+    const local = ctx.local.capabilities.mcpProbe;
+    if (specs.length === 0) {
+        deps.metrics?.inc("mcp_probe_total", { outcome: "empty" });
+        sendJson(res, 200, buildEmptyMcpProbeFace());
+        return;
+    }
+    const key = buildMcpProbeCacheKey(principal, specs);
+    const hit = local.cached(key, Date.now());
+    if (hit !== undefined) {
+        await answerMcpProbe(res, ctx, hit, "cached", declaredBy);
+        return;
+    }
+    if (local.inflight() >= MCP_PROBE_MAX_INFLIGHT) {
+        sendMcpProbeRefusal(res, ctx, buildMcpProbeInflightRefusal(), "rate_limited", Math.ceil(MCP_PROBE_VERDICT_TIMEOUT_MS / 1000));
+        return;
+    }
+    const verdict = await local.check(buildMcpProbeRateKey(principal));
+    if (!verdict.allowed) {
+        sendMcpProbeRefusal(res, ctx, buildMcpProbeRateRefusal(), "rate_limited", verdict.retryAfterSec);
+        return;
+    }
+    const walk = createMcpProbeWalk(specs, principal);
+    local.remember(key, Date.now(), walk);
+    await answerMcpProbe(res, ctx, walk.answer, "probed", declaredBy);
+}
+async function answerMcpProbe(res, ctx, answer, outcome, declaredBy) {
+    const { deps } = ctx;
+    try {
+        const body = await answer;
+        sendJson(res, 200, body);
+        deps.metrics?.inc("mcp_probe_total", { outcome });
+    }
+    catch (err) {
+        deps.metrics?.inc("mcp_probe_total", { outcome: "failed" });
+        if (err instanceof McpProbeIncomplete) {
+            sendMcpProbeRefusal(res, ctx, buildMcpProbeIncompleteRefusal(err.boundMs), "failed", Math.ceil(err.boundMs / 1000));
+            return;
+        }
+        if (declaredBy === "caller") {
+            sendMcpProbeRefusal(res, ctx, buildMcpProbeDeclarationRefusal(), "failed");
+            return;
+        }
+        throw err;
+    }
+}
 export const CAPABILITIES_ROUTES = [
     { id: "models", path: "/v1/models", methods: ["GET"] },
     { id: "capabilities", path: "/v1/capabilities", methods: ["GET"] },
     { id: "capability-scenario", pattern: /^\/v1\/capabilities\/scenarios\/(?<name>.*)$/, label: "/v1/capabilities/scenarios/:name", methods: ["GET"] },
+    { id: "capability-mcp", path: "/v1/capabilities/mcp", methods: ["GET"] },
+    { id: "capability-mcp-probe", path: "/v1/capabilities/mcp/probe", methods: ["POST"] },
 ];
 //# sourceMappingURL=capabilities.js.map

package/dist/http/routes/memory-origin.d.ts

@@ -105,7 +105,7 @@ export declare function buildClearanceRowWire(r: OriginClearanceRow): {
     requestId: string;
     reason: string;
     at: number;
-    status: "failed" | "pending" | "done";
+    status: "pending" | "failed" | "done";
     originUnknownKeys?: string[] | undefined;
     clearanceId: string;
     entryId: string;