@sema-agent/server 7.129.1 → 7.131.0

package/dist/boot/resolve-spec.js

@@ -2,10 +2,11 @@ import { realpathSync } from "node:fs";
 import { join } from "node:path";
 import { NodeExecutionEnv, QUESTION_AWAITS_RESUME, WRITE_EXEMPT_DIR_COVERS_ROOT_CODE, deriveAskEffective, expandTiers, modePolicyOf, resolveAskSeamForm } from "@sema-agent/core";
 import { cappedCeiling } from "../budget.js";
+import { recordFailOpen } from "../observability/fail-open.js";
 import { centerPromptProvider, centerIdentityAssembled } from "../capabilities/center-prompts.js";
 import { SessionEnvironmentSelection, selectEnvironmentTool } from "../capabilities/select-environment-tool.js";
 import { sendUserFileTool } from "../capabilities/send-user-file-tool.js";
-import { gateScenarioRequest, mergeUserSkills, selectScenario } from "../capabilities/scenarios.js";
+import { createScenarioGate, mergeUserSkills, selectScenario } from "../capabilities/scenarios.js";
 import { stampHandsLane, toolPolicyForHands } from "../capabilities/hands-lane.js";
 import { buildNoticeLaneFacts, noPersistentMemoryNotice, withNoPersistentMemoryNotice } from "../capabilities/memory-notice.js";
 import { applyLongtailDefer } from "../capabilities/tool-defer.js";
@@ -35,9 +36,11 @@ import { normalizeAttachments, normalizeResilience, normalizeResumeAtMode, norma
 import { isAbsoluteHostPath } from "@sema-agent/settings-schema";
 import { cwdHonored, deviceCwdHonored, effectiveHostWorkspace, inProcessSingleUserLane, parseAdditionalDirectories, satisfiedByProcessCwd, shellEnvMismatchCount } from "../task-cwd.js";
 import { assertRequestA2aUnlocked, resolveRequestA2a } from "../task-a2a.js";
-import { assertRequestMcpContentOrigin, assertRequestMcpIdentityHeaders, assertRequestMcpUnlocked, resolveRequestMcp } from "../task-mcp.js";
-import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, acceptAppendSystemPrompt, applyTaskSettings, effectivePermissionMode, effectiveThinking, hasConstitutionAnchors, parseTaskSettings, taskHooksHonored, providerDropsAppend, settingsPermissionBucketIssue, withPermissionMode } from "../task-settings.js";
-import { skillDenyInertEntryOf } from "../rule-entry-list.js";
+import { assertRequestMcpEntries, assertRequestMcpUnlocked, resolveRequestMcp } from "../task-mcp.js";
+import { storedToolAxesRereadM19 } from "../stored-request-tool-axes-m19.js";
+import { storedHooksRereadM20 } from "../stored-request-hooks-m20.js";
+import { MAX_SETTINGS_OUTPUT_STYLE_CHARS, REQUEST_SETTINGS_REFUSAL_PREFIX, acceptAppendSystemPrompt, applyTaskSettings, effectivePermissionMode, effectiveThinking, hasConstitutionAnchors, parseTaskSettings, taskHooksHonored, providerDropsAppend, settingsPermissionBucketIssue, withPermissionMode } from "../task-settings.js";
+import { inertToolListEntryOf } from "../rule-entry-list.js";
 import { TENANCY_WALL_CLOCK_BASE_SEC, enableForkFromBody, normalizeRetainSubagentSessions, selfOrchestrationFromBody } from "../task-workflow.js";
 import { redactSecrets } from "../trace/redact.js";
 import { DeferredSandboxPathEnv, isSandboxPathAdjudicationLane, sandboxPathEnvSlots } from "./deferred-sandbox-path-env.js";
@@ -47,6 +50,7 @@ import { withUnattendedLeg } from "../unattended-permission-mode.js";
 import { memoryFaceMounted } from "../memory-scope.js";
 export function createResolveSpec(ctx) {
     const { config, logger, metrics, localRoot, scenarios, principalCaps, centerRuntimeCapsResolver, getCenterPrompts, getKeyResolver, taskAttachmentStore, perSessionCwd, setSessionCwd, setSessionShellEnv, fenceSessionOwner, hookLlm, hookAgent, fleetBus, hookWakeBus, resumeAnchorStore, ownerAware, taskLimitCaps, taskTimeoutSec, selectEnvTool, sendUserFileToolSpec, memoryEngine, durableEnabled, approvalExemptionStore, checkpointStore, deploymentHooks, imageIndex, perTaskImage, sessionEnvSelection, liveQuestionFace, approverSeat, lockedKeys, } = ctx;
+    const scenarioGate = createScenarioGate({ config, scenarios, principalCaps, logger }, "enforce");
     assertGuardPatternsUsable(config);
     const onlySensitiveBaseline = buildOnlySensitiveBaselineWarning(config, {
         approvalSeat: durableEnabled ? "durable" : "absent",
@@ -69,9 +73,7 @@ export function createResolveSpec(ctx) {
             throw createCodedHttpError(501, "capability.checkpoint_store_required", seatRefusal);
         assertRequestMcpUnlocked(body.mcpServers, lockedKeys);
         if (opts?.leg === "fresh")
-            assertRequestMcpContentOrigin(body.mcpServers);
-        if (opts?.leg === "fresh")
-            assertRequestMcpIdentityHeaders(body.mcpServers);
+            assertRequestMcpEntries(body.mcpServers);
         if (opts?.leg === "fresh") {
             const conflict = scratchpadCoveringTaskRoot({
                 cwd: body.cwd,
@@ -111,9 +113,21 @@ export function createResolveSpec(ctx) {
                 throw new HttpError(400, bucketIssue.message, { code: "request.field_invalid", extra: bucketIssue.fields });
         }
         {
-            const skillDeny = skillDenyInertEntryOf(body);
-            if (skillDeny !== undefined)
-                throw new HttpError(400, skillDeny.message, { code: "request.field_invalid" });
+            const replay = opts?.leg === "resume";
+            const inertList = inertToolListEntryOf(body, replay ? ["deny"] : undefined);
+            if (inertList !== undefined)
+                throw new HttpError(400, inertList.message, { code: inertList.code, ...(inertList.extra !== undefined ? { extra: { ...inertList.extra } } : {}) });
+            if (replay) {
+                const stale = inertToolListEntryOf(body, ["allow"]);
+                if (stale !== undefined) {
+                    logger.warn("stored_allow_list_inert_resumed", {
+                        sessionId: auth?.sessionId ?? null,
+                        layer: stale.layer,
+                        sentence: stale.message,
+                        note: "this resumed task's stored request carries an allow-list entry the engine reads as nothing (a retired name, a case twin, an unreadable spelling or a content form): the entry stays as written and grants nothing — the task ran that way before the upgrade, so it continues; fix the entry in a new submission to get what it was meant to allow",
+                    });
+                }
+            }
         }
         assertRequestA2aUnlocked(body.a2aPeers, lockedKeys);
         const gated = await gateScenarioAndAppend(body, auth, opts);
@@ -136,7 +150,7 @@ export function createResolveSpec(ctx) {
         return stamped;
     };
     const gateScenarioAndAppend = async (body, auth, opts) => {
-        const scenarioName = gateScenarioRequest(await principalCaps?.scenarioRuling(auth?.principal), body.scenario, config.defaultScenario, Object.keys(scenarios), logger, auth?.principal);
+        const scenarioName = await scenarioGate(auth?.principal, body.scenario);
         gateExecutionLane(await principalCaps?.executionRuling(auth?.principal), executionLaneOf(config.remoteExec?.provider), logger);
         const cap = selectScenario(scenarios, scenarioName)(body, auth?.principal, auth?.sessionId !== undefined ? { sessionId: auth.sessionId } : {});
         const centerDecls = getCenterPrompts()?.declarations;
@@ -145,7 +159,7 @@ export function createResolveSpec(ctx) {
             : providerDropsAppend(cap.promptProvider, typeof body.systemPrompt === "string" ? body.systemPrompt : undefined);
         const acceptedAppend = acceptAppendSystemPrompt(body.appendSystemPrompt, (detail) => logger.warn("append_system_prompt_dropped", { detail, sessionId: auth?.sessionId ?? null }), appendLessPack);
         const objective = typeof body.objective === "string" ? body.objective : "";
-        const parsedSettings = parseTaskSettings(body.settings);
+        const parsedSettings = parseTaskSettings(body.settings, opts?.leg === "fresh" || !taskHooksHonored(config) ? {} : { storedHooksReread: storedHooksRereadM20(new Date().toISOString().slice(0, 10)) });
         if (opts?.leg === "fresh" && appendLessPack) {
             const riderPresent = typeof body.appendSystemPrompt === "string" && body.appendSystemPrompt.length > 0;
             if (riderPresent || parsedSettings.settings?.outputStyle) {
@@ -155,6 +169,17 @@ export function createResolveSpec(ctx) {
         if (parsedSettings.deferred.length > 0) {
             logger.warn("task_settings_deferred", { fields: parsedSettings.deferred, sessionId: auth?.sessionId ?? null });
         }
+        if (parsedSettings.hooksReread !== undefined) {
+            logger.warn("hooks_read_as_before_upgrade", {
+                migration: "M20",
+                sessionId: auth?.sessionId ?? null,
+                stripped: parsedSettings.hooksReread.stripped,
+                note: "this replayed request was stored before the upgrade and its settings.hooks carries a shape the hooks reader now refuses (a key the reader does not know that hides a guard-event member, or a JSON `__proto__` event key); while one-time migration M20 is open the keys named in `stripped` are dropped — what the pre-upgrade reader dropped — and the rest goes through the same reader again, so the guard hooks keep running; once the window closes the same request has its whole settings.hooks left out",
+            });
+        }
+        if (parsedSettings.deferred.includes("hooks") && taskHooksHonored(config)) {
+            recordFailOpen("server.hooks.resume-reader-refused", `leg=${opts?.leg ?? "resume"}`);
+        }
         let attachmentNotice;
         {
             const reqAtt = body.attachmentIds;
@@ -285,6 +310,7 @@ export function createResolveSpec(ctx) {
         }
         return { taskHooks, additionalDirectories, additionalReadDirectories, wireCatalog, picked };
     };
+    const NO_ANCHOR_HINT = "no rewind anchor is recorded under that handle (a prompt that carried attachments records none when its attachment frames were interrupted or their count did not match)";
     const resolveHistoryAnchors = async (body, auth) => {
         let resumeAtEntryId;
         if (typeof body.resumeAt === "string" && body.resumeAt.length > 0) {
@@ -294,7 +320,7 @@ export function createResolveSpec(ctx) {
                 throw new HttpError(501, "resume-at is not available on this worker (no session-store backend for the anchor map)");
             resumeAtEntryId = await resumeAnchorStore.resolve(auth.sessionId, body.resumeAt, auth.principal ?? null);
             if (resumeAtEntryId === undefined)
-                throw new HttpError(404, "resumeAt: no such message in this session (resume_at.unknown_event)", { code: "resume_at.unknown_event" });
+                throw new HttpError(404, `resumeAt: no such message in this session (resume_at.unknown_event) — ${NO_ANCHOR_HINT}; give an explicit resumeAt`, { code: "resume_at.unknown_event" });
         }
         let rewindFilesToEntryId;
         if (resumeAtEntryId === undefined && typeof body.rewindFilesTo === "string" && body.rewindFilesTo.length > 0) {
@@ -304,7 +330,7 @@ export function createResolveSpec(ctx) {
                 throw new HttpError(501, "rewind-files-to is not available on this worker (no session-store backend for the anchor map)");
             rewindFilesToEntryId = await resumeAnchorStore.resolve(auth.sessionId, body.rewindFilesTo, auth.principal ?? null);
             if (rewindFilesToEntryId === undefined)
-                throw new HttpError(404, "rewindFilesTo: no such message in this session (rewind_files_to.unknown_event)", { code: "rewind_files_to.unknown_event" });
+                throw new HttpError(404, `rewindFilesTo: no such message in this session (rewind_files_to.unknown_event) — ${NO_ANCHOR_HINT}; name another prompt`, { code: "rewind_files_to.unknown_event" });
         }
         const s4ProjectId = auth?.resolvedProjectId ?? (typeof body.projectId === "string" && body.projectId ? body.projectId.toLowerCase() : undefined);
         const s4DefaultScopes = s4ProjectId ? config.projects[s4ProjectId]?.defaultScopes : undefined;
@@ -334,6 +360,7 @@ export function createResolveSpec(ctx) {
             sessionId: auth?.sessionId,
             principal: auth?.principal,
             images: body.images,
+            ...(body.userAttachments !== undefined ? { userAttachments: body.userAttachments } : {}),
             ...(body.clientContext ? { clientContext: { timeZone: body.clientContext.timeZone, userEmail: body.clientContext.userEmail } } : {}),
             ...(() => {
                 const ct = body.compaction?.clampTolerance;
@@ -456,7 +483,7 @@ export function createResolveSpec(ctx) {
             ...(() => { const v = toolNameListFromBody(body.userInvokedSkills); return v ? { userInvokedSkills: v } : {}; })(),
             ...(parsedSettings.settings?.skillListingBudgetFraction !== undefined ? { skillListingBudgetFraction: parsedSettings.settings.skillListingBudgetFraction } : {}),
             ...(parsedSettings.settings?.skillListingMaxDescChars !== undefined ? { skillListingMaxDescChars: parsedSettings.settings.skillListingMaxDescChars } : {}),
-            mcp: resolveRequestMcp(mcpForScenario(config.mcpServers, scenarioName), body.mcpServers, config, logger, opts?.onNotice !== undefined ? { sessionId: auth?.sessionId, emit: opts.onNotice } : undefined),
+            mcp: resolveRequestMcp(mcpForScenario(config.mcpServers, scenarioName), body.mcpServers, config, logger, opts?.onNotice !== undefined ? { sessionId: auth?.sessionId, emit: opts.onNotice } : undefined, opts?.leg === "fresh" ? undefined : storedToolAxesRereadM19(new Date().toISOString().slice(0, 10))),
             a2a: resolveRequestA2a(a2aForScenario(config.a2aPeers, scenarioName), body.a2aPeers, config, logger),
             promptProvider: centerDecls ? centerPromptProvider(centerDecls, scenarioName) : cap.promptProvider,
             toolPolicy: toolPolicyForHands(hands, durableEnabled
@@ -596,7 +623,7 @@ export function createResolveSpec(ctx) {
                         ...(e.detail !== undefined ? { extra: { writeExemptDirCoversRoot: e.detail } } : {}),
                     });
                 }
-                throw new HttpError(422, `request settings cannot be applied as written: ${e.message}`);
+                throw new HttpError(422, `${REQUEST_SETTINGS_REFUSAL_PREFIX}${e.message}`);
             }
         }
         const notice = noPersistentMemoryNotice({

package/dist/boot/stage-02-web-admin-pull.js

@@ -4,6 +4,9 @@ import { composeExecutionLane, FILE_SOURCED_LANES } from "./execution-lane.js";
 import { serviceConfigSourceKind } from "../config-provider.js";
 import { logConfigDirMigration, migrateLocalConfigDirectory } from "../config-d-migration.js";
 import { defaultModelRefusal, refusedNameMintedRefusal } from "../model-entry-refusal.js";
+import { isRosterGateArmed } from "../config.js";
+import { judgeServedModelRoute } from "../model-route-endpoint.js";
+import { servedModelTableLeg } from "../model-select.js";
 export async function runStage02(ctx) {
     const { config, localRoot, logger, metrics } = ctx;
     const configSource = serviceConfigSourceKind(config);
@@ -11,10 +14,15 @@ export async function runStage02(ctx) {
         logConfigDirMigration(logger, await migrateLocalConfigDirectory(localRoot));
     await composeExecutionLane(config, { configSource, localRoot, logger, drivesFromFile: FILE_SOURCED_LANES });
     const webAdmin = await createWebAdminRuntime({ config, logger, metrics, localRoot });
-    const noDefaultModel = defaultModelRefusal(config, "env");
+    const servedLeg = servedModelTableLeg(config);
+    const noDefaultModel = defaultModelRefusal(config, servedLeg);
     if (noDefaultModel !== undefined) {
         throw new Error(noDefaultModel);
     }
+    const routeVerdict = judgeServedModelRoute(config, { envTableIsPlaceholder: isRosterGateArmed(config.webAdmin) });
+    if (routeVerdict !== undefined) {
+        throw new Error(routeVerdict.reason);
+    }
     const mintedRefused = refusedNameMintedRefusal(config);
     if (mintedRefused !== undefined) {
         throw new Error(mintedRefused);

package/dist/boot/stage-10-http-server.d.ts

@@ -56,7 +56,7 @@ export declare function runStage10(ctx: Awaited<ReturnType<typeof runStage09>>):
     resumeAnchorStore: import("../plugins/store-backend.js").ResumeAnchorStore | undefined;
     runStore: import("../plugins/store-backend.js").RunStore | undefined;
     scenarioDetails: Record<string, import("../capabilities/scenarios.js").ScenarioDetail>;
-    scenarios: Record<string, import("../index.js").Scenario>;
+    scenarios: Record<string, import("../capabilities/scenarios.js").Scenario>;
     selectEnvTool: import("@sema-agent/core").ToolSpec<import("@sema-agent/core").TSchema> | undefined;
     taskLimitCaps: {
         timeoutSec: number | undefined;

package/dist/boot/stage-10-http-server.js

@@ -19,6 +19,7 @@ import { mintEngineSignal } from "../fleet/engine-signal.js";
 import { createServingLeaseClient } from "../fleet/serving-lease.js";
 import { fleetFenceLaneOf } from "../config.js";
 import { createResolveSpec } from "./resolve-spec.js";
+import { createScenarioGate } from "../capabilities/scenarios.js";
 import { executionLaneOf } from "../execution-lane-caps.js";
 import { startFleetReconciler } from "../fleet/fleet-reconciler.js";
 import { createSideQueryLane } from "./side-query-lane.js";
@@ -210,7 +211,8 @@ export async function runStage10(ctx) {
     });
     const runnerFor = createHandsRunnerSelector({ full: runner, handsless: handslessRunner });
     const sideQuery = createSideQueryLane({ brain, config, getKeyResolver: () => webAdmin.getKeyResolver() });
-    const server = createHttpServer({ runner, runnerFor, sideQuery, config, resolveSpec, stores, coordinators, seams, observability, governance, deployment, knobs });
+    const scenarioGate = createScenarioGate({ config, scenarios, principalCaps, logger }, "peek");
+    const server = createHttpServer({ runner, runnerFor, sideQuery, scenarioGate, config, resolveSpec, stores, coordinators, seams, observability, governance, deployment, knobs });
     bindServerLateSeats({ config, logger, server });
     const fleetReconcile = startFleetReconciler({
         bus: fleetBus,
@@ -282,8 +284,11 @@ export async function runStage10(ctx) {
     const failoverFirstByte = buildFailoverFirstByteNotice(config);
     if (failoverFirstByte)
         logger.warn("failover_first_byte_lane", failoverFirstByte);
+    const bound = server.address();
+    if (bound === null || typeof bound === "string")
+        throw new Error(`http server listening without a TCP address (server.address() = ${JSON.stringify(bound)})`);
     logger.info("listening", {
-        port: config.port,
+        port: bound.port,
         bindHost: bindHost ?? "0.0.0.0/::(all interfaces)",
         ...(bindHost === "127.0.0.1" && !config.bindHost
             ? { bindHostNote: "auto-narrowed to loopback: write face is unauthenticated (ALLOW_UNAUTHED_WRITES with no service token). Set BIND_HOST explicitly to override." }

package/dist/capabilities/builtin-tools.js

@@ -1,7 +1,8 @@
 import { Type } from "typebox";
+import { NOW_TOOL_NAME } from "./host-tool-names.js";
 export function nowTool() {
     return {
-        name: "Now",
+        name: NOW_TOOL_NAME,
         description: "Return the current date-time as an ISO-8601 UTC string. Use when the task involves dates/deadlines/'today'.",
         effect: "read",
         parameters: Type.Object({}),

package/dist/capabilities/composite-members.d.ts

@@ -54,6 +54,7 @@ export declare const COMPOSITE_CAPABILITY_MEMBERS: {
     readonly workflowsGate: readonly ["engineCan", "denial"];
     readonly sealedKey: readonly ["alg", "publicKeyId", "publicKey"];
     readonly workspaceSync: readonly ["persist", "keep", "timeoutMs", "cache"];
+    readonly userAttachments: readonly ["entries", "kinds", "supplies", "limits"];
 };
 type CompositeTable = typeof COMPOSITE_CAPABILITY_MEMBERS;
 /** 值的**具名成员对象臂**(标量 / 字面词 / `false` / `null` / `undefined` / 数组 / 函数臂剥掉)。 */

package/dist/capabilities/composite-members.js

@@ -15,6 +15,7 @@ export const COMPOSITE_CAPABILITY_MEMBERS = {
     workflowsGate: ["engineCan", "denial"],
     sealedKey: ["alg", "publicKeyId", "publicKey"],
     workspaceSync: ["persist", "keep", "timeoutMs", "cache"],
+    userAttachments: ["entries", "kinds", "supplies", "limits"],
 };
 export function gateCompositeMembers(body) {
     return body;

package/dist/capabilities/hands-lane.js

@@ -1,5 +1,5 @@
 import { handBandEffects, judgeRuleToolName, combinePolicies, createAllowDenyPolicy } from "@sema-agent/core";
-import { NO_DECLARED_TOOL_NAMES } from "../namespaced-rule-name.js";
+import { TOOL_NAME_ROSTER } from "../namespaced-rule-name.js";
 export function withoutHands(deps) {
     const { executionEnvFactory: _handsDropped, lspManager: _lspDropped, ...rest } = deps;
     return rest;
@@ -20,7 +20,7 @@ export const HANDS_BAND_TOOL_NAMES = Object.freeze([
     "EnterWorktree",
     "ExitWorktree",
     "ListAgents",
-].filter((n, i, all) => judgeRuleToolName(n, NO_DECLARED_TOOL_NAMES).kind === "current" && all.indexOf(n) === i));
+].filter((n, i, all) => judgeRuleToolName(n, TOOL_NAME_ROSTER).kind === "current" && all.indexOf(n) === i));
 export const HANDS_DUAL_USE_TOOL_NAMES = Object.freeze(["TaskOutput", "TaskStop", "SendMessage", "AgentTranscript", "ListAgents"]);
 export const HANDS_EXCLUSIVE_TOOL_NAMES = Object.freeze(HANDS_BAND_TOOL_NAMES.filter((n) => !HANDS_DUAL_USE_TOOL_NAMES.includes(n)));
 export function handsDenyPolicy() {

package/dist/capabilities/host-tool-names.d.ts

@@ -0,0 +1,17 @@
+/**
+ * **本仓自己铸给模型的工具的名字** —— 唯一的名字源(叶模块,零依赖)。铸它们的地方(`builtin-tools.ts` / `send-user-file-tool.ts` / `select-environment-tool.ts` / `repo-tools.ts`)
+ * 与读它们的地方(工具名清单的受理判:`rule-entry-list.ts` 的名册;场景详情的工具名单;长尾延迟披露集)都从这里取,不手抄。
+ *
+ * 为什么受理口要知道它们:请求的 `allowTools` / `excludeTools` / 子代的 `allowTools` / `denyTools` 里把 `SendUserFile` 写成 `SENDUSERFILE`,引擎只在开跑时按这一 run 真挂着的名册告运维;
+ * 受理口读不到那份名册,读得到的是「引擎目录 ∪ 本仓自铸的这几只」—— 不把这几只放进名册,它们的孪生就是受理口漏掉的同一类静默失效。
+ * 宿主之外的调用方工具、MCP / A2A 对端的工具不在其中(前者本仓不挂,后者是协议名,由协议段判)。
+ */
+export declare const NOW_TOOL_NAME = "Now";
+export declare const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
+export declare const SELECT_ENVIRONMENT_TOOL_NAME = "SelectEnvironment";
+export declare const REPO_TREE_TOOL_NAME = "repo_tree";
+export declare const REPO_READ_FILE_TOOL_NAME = "repo_read_file";
+export declare const REPO_PULL_DIFF_TOOL_NAME = "repo_pull_diff";
+/** 本仓自铸的全部工具名(受理口工具名清单的名册成员;加一只自铸工具 ⇒ 这里加一行)。 */
+export declare const HOST_TOOL_NAMES: ReadonlySet<string>;
+//# sourceMappingURL=host-tool-names.d.ts.map

package/dist/capabilities/host-tool-names.js

@@ -0,0 +1,15 @@
+export const NOW_TOOL_NAME = "Now";
+export const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
+export const SELECT_ENVIRONMENT_TOOL_NAME = "SelectEnvironment";
+export const REPO_TREE_TOOL_NAME = "repo_tree";
+export const REPO_READ_FILE_TOOL_NAME = "repo_read_file";
+export const REPO_PULL_DIFF_TOOL_NAME = "repo_pull_diff";
+export const HOST_TOOL_NAMES = new Set([
+    NOW_TOOL_NAME,
+    SEND_USER_FILE_TOOL_NAME,
+    SELECT_ENVIRONMENT_TOOL_NAME,
+    REPO_TREE_TOOL_NAME,
+    REPO_READ_FILE_TOOL_NAME,
+    REPO_PULL_DIFF_TOOL_NAME,
+]);
+//# sourceMappingURL=host-tool-names.js.map

package/dist/capabilities/mcp-probe.js

@@ -1,10 +1,10 @@
-import { probeMcpServers } from "@sema-agent/core";
+import { probeMcpServers, readMcpToolAxes } 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, requestEntryIdentityRefusal, validateRequestMcp, } from "../task-mcp.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, requestEntryIdentityRefusal, requestEntryToolAxesRefusal, validateRequestMcp, } from "../task-mcp.js";
 import { toCoreMcpServerSpec } from "../mcp-assertion-header.js";
 import { buildDisplaySafeUrl } from "../trace/redact.js";
 import { projectWiringManifestMcpRows } from "../trace/project.js";
@@ -53,7 +53,7 @@ function entryKeyIssue(entry, at) {
             scanKeyClosure(t, `${at}.transport.`, new Set(keys), NO_TOLERATED_KEYS, buckets);
     }
     if (buckets.unknown.length === 0) {
-        const refusal = requestEntryIdentityRefusal(entry);
+        const refusal = requestEntryIdentityRefusal(entry, at);
         if (refusal === undefined)
             return null;
         return refusal.errorCode === "request.body_shape" ? shapeRefusal(refusal.message) : fieldRefusal(refusal.message);
@@ -64,6 +64,9 @@ function entryKeyIssue(entry, at) {
         `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 axesRefusal = requestEntryToolAxesRefusal(entry, at);
+    if (axesRefusal !== undefined)
+        return fieldRefusal(axesRefusal.message);
     const read = validateRequestMcp([entry]);
     if (read === null)
         return fieldRefusal(`${at} is not a readable MCP declaration`);
@@ -71,7 +74,7 @@ function entryValueIssue(entry, at) {
     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)`);
+            ` (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)`);
@@ -82,12 +85,22 @@ function entryValueIssue(entry, 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);
+    const diff = jsonPathDiff(stripEquivalentEmpties(declaredAsJudged(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)");
+        " (this endpoint refuses, because the reading would then describe a server you did not ask about)");
+}
+function declaredAsJudged(entry) {
+    const declared = entry;
+    if (!("toolAxes" in declared))
+        return declared;
+    const read = readMcpToolAxes(declared.toolAxes);
+    if (!read.ok)
+        return declared;
+    const { toolAxes: _declaredAxes, ...rest } = declared;
+    return read.toolAxes === undefined ? rest : { ...rest, toolAxes: read.toolAxes };
 }
 function stripEquivalentEmpties(entry) {
     const emptyRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0;

package/dist/capabilities/repo-tools.js

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { z } from "zod";
+import { REPO_PULL_DIFF_TOOL_NAME, REPO_READ_FILE_TOOL_NAME, REPO_TREE_TOOL_NAME } from "./host-tool-names.js";
 export function parseRepo(input) {
     const s = input.trim().replace(/\.git$/, "");
     const m = /^[a-z]+:\/\/[^/]+\/(.+)$/i.exec(s);
@@ -160,7 +161,7 @@ export function repoToolsFor(client, coords) {
     const ref = (r) => (r ? Promise.resolve(r) : client.defaultBranch(coords));
     return [
         {
-            name: "repo_tree",
+            name: REPO_TREE_TOOL_NAME,
             description: "List file paths in the repository (recursive). Use this first to understand structure, then read specific files.",
             effect: "read",
             parameters: Type.Object({ ref: Type.Optional(Type.String({ description: "branch/tag/sha; default = repo default branch" })) }),
@@ -171,7 +172,7 @@ export function repoToolsFor(client, coords) {
             },
         },
         {
-            name: "repo_read_file",
+            name: REPO_READ_FILE_TOOL_NAME,
             description: "Read one file's text from the repository. Read only the files you need (just-in-time).",
             effect: "read",
             parameters: Type.Object({ path: Type.String(), ref: Type.Optional(Type.String()) }),
@@ -181,7 +182,7 @@ export function repoToolsFor(client, coords) {
             },
         },
         {
-            name: "repo_pull_diff",
+            name: REPO_PULL_DIFF_TOOL_NAME,
             description: "Get the unified diff of a pull request by its number (for reviewing a PR's changes).",
             effect: "read",
             parameters: Type.Object({ index: Type.Integer({ description: "the PR number" }) }),

package/dist/capabilities/scenarios.d.ts

@@ -295,4 +295,38 @@ export declare function danglingScenarioRefusal(name: string, source: ScenarioNa
  *     ({@link danglingScenarioRefusal})。`principal` 只进那一行运维日志,不参与判定。
  */
 export declare function gateScenarioRequest(ruling: ScenarioRuling | undefined, bodyScenario: unknown, defaultScenario: string, known: readonly string[], logger?: Logger, principal?: string): string;
+/**
+ * 一条请求的场景名过门 —— {@link gateScenarioRequest} 的**唯一一处实参装配**。
+ *
+ * 门的六个实参各有来源:中心裁定(`principalCaps.scenarioRuling`,按 principal)、请求点名的名字、部署缺省场景、**在册词表**
+ * (`Object.keys(scenarios)` —— 场景表活引用,不抄快照)、日志与 principal。「此主体在此场景能看见什么」这类问题有不止一个读口
+ * (任务提交腿 `resolveSpec`、`run-local`、`GET /v1/capabilities/mcp` 的状态面、`GET /v1/sessions/:id/mcp` / `…/a2a` 两张会话面板),
+ * 每个读口自己拼一遍这六个实参 = 第二只门:两口对「在册」「放行」「缺席取谁」各判各的,读口就开始对不上 run。
+ * 所以装配只在这里,读口持有的是**绑好的门**;凡回答这类问题的口,场景名都由门给 —— 点名与缺席都问。
+ *
+ * 契约:`(principal, requested) => 在册的场景名`(返回值一定在册;被拒 ⇒ 抛 {@link gateScenarioRequest} 的那几只 typed 错,
+ * 读口不改写)。`requested` 非串(缺席)⇒ 门走指派链(ruling 胜者,否则部署缺省),与 run 时同一读法。
+ * `principalCaps` 缺席(无中心 / 干跑 / 嵌入方 / `run-local`)⇒ 无 ruling,门退回「请求名或部署缺省」那条现状链。
+ */
+export interface ScenarioGateSources {
+    readonly config: {
+        readonly defaultScenario: string;
+    };
+    /** 场景表(活引用):词表按调用时的自有键取,与表同生同灭。 */
+    readonly scenarios: Readonly<Record<string, unknown>>;
+    readonly principalCaps: {
+        scenarioRuling(principal: string | undefined): Promise<ScenarioRuling | undefined>;
+        peekScenarioRuling(principal: string | undefined): Promise<ScenarioRuling | undefined>;
+    } | undefined;
+    readonly logger?: Logger;
+}
+export type ScenarioGate = (principal: string | undefined, requested: unknown) => Promise<string>;
+/**
+ * 门问中心裁定走哪条腿(闭集;新增一词 ⇒ 下面的穷尽 `switch` 编译红)—— 与 `resolveRuntimeCaps` / `peekRuntimeCaps` 是同一对:
+ *  · `enforce` —— 任务提交腿:中心裁定走执法腿,center 硬失败铸下的 fail-closed 降级项两腿都认;
+ *  · `peek` —— 读面(`GET /v1/capabilities/mcp` 状态面、`GET /v1/sessions/:id/mcp` / `…/a2a` 两张会话面板):只读腿,同一只缓存 / 同一条抓取 / 同一份 fail-open 判决,但硬失败铸的降级项只对读面自己算数,
+ *    不替这个主体的真提交留下 `{allowWorkflows:false, allowFork:false, autoMode:false}` 的短窗 deny(读面不许成为别人被拒的原因)。
+ */
+export type ScenarioGateLeg = "enforce" | "peek";
+export declare function createScenarioGate(sources: ScenarioGateSources, leg: ScenarioGateLeg): ScenarioGate;
 //# sourceMappingURL=scenarios.d.ts.map

package/dist/capabilities/scenarios.js

@@ -2,6 +2,7 @@ import { CODE_AGENT_PROMPT, CODE_SYSTEM_PROMPT, DEFAULT_SYSTEM_PROMPT, WEB_FETCH
 import { HttpError, createCodedHttpError } from "../security.js";
 import { createSubagentExtraTools, extraToolsErrorFields, nowTool } from "./builtin-tools.js";
 import { parseRepo, repoToolsFor } from "./repo-tools.js";
+import { NOW_TOOL_NAME, REPO_PULL_DIFF_TOOL_NAME, REPO_READ_FILE_TOOL_NAME, REPO_TREE_TOOL_NAME } from "./host-tool-names.js";
 import { stablePrompt } from "./prompt.js";
 import { createWebSearchBackend, judgeRequestWebSearch } from "../plugins/web-search.js";
 import { skillsForScenario } from "./skills.js";
@@ -119,16 +120,16 @@ export function builtinScenarioDetails(scenarios, deps) {
             return fallback;
         }
     };
-    const REPO_TOOLS = ["repo_tree", "repo_read_file", "repo_pull_diff", "Now"];
+    const REPO_TOOLS = [REPO_TREE_TOOL_NAME, REPO_READ_FILE_TOOL_NAME, REPO_PULL_DIFF_TOOL_NAME, NOW_TOOL_NAME];
     const mk = (name, summary, toolset, tools, promptSummary) => ({
         name, source: "builtin", builtin: true, summary, toolset, tools, promptSummary, enabled: true,
         ...availabilityFields(deps, toolset),
     });
     const details = {
-        code: mk("code", "编码主场景([891] 出厂缺省;CC 编码 persona 蒸馏版,default 全量工具面;终验旋钮独立)", "full-body", probe("code", {}, undefined, ["Now"]), deps.brandIdentity
+        code: mk("code", "编码主场景([891] 出厂缺省;CC 编码 persona 蒸馏版,default 全量工具面;终验旋钮独立)", "full-body", probe("code", {}, undefined, [NOW_TOOL_NAME]), deps.brandIdentity
             ? "Sema 产品身份 + core 编码完全体提示词(CODE_AGENT persona+自治自检;CC 血统对表)"
             : "core 编码完全体提示词(CODE_AGENT persona+自治自检;CC 血统对表)"),
-        default: mk("default", "通用/助理场景(域中性 persona,CC agent loop 全量工具面;[891] 起非出厂缺省,显式可选)", "full-body", probe("default", {}, undefined, ["Now"]), deps.brandIdentity ? "Sema 产品身份 + core 默认宪法(结构层由引擎合成)" : "core 默认宪法(中性,无场景附加 persona)"),
+        default: mk("default", "通用/助理场景(域中性 persona,CC agent loop 全量工具面;[891] 起非出厂缺省,显式可选)", "full-body", probe("default", {}, undefined, [NOW_TOOL_NAME]), deps.brandIdentity ? "Sema 产品身份 + core 默认宪法(结构层由引擎合成)" : "core 默认宪法(中性,无场景附加 persona)"),
         "code-review": mk("code-review", "代码评审(clone-free 只读仓库工具)", "repo-readonly", probe("code-review", { repo: "probe/probe" }, undefined, REPO_TOOLS), "评审员提示词(产出契约)"),
         scan: mk("scan", "中性只读仓库扫描(输出契约由 objective+skills 决定)", "repo-readonly", probe("scan", { repo: "probe/probe" }, undefined, REPO_TOOLS), "无场景附加提示词(objective+center skills 拥有输出契约)"),
     };
@@ -149,7 +150,7 @@ export function centerScenarioDetails(specs, builtinNames, deps) {
             builtin: builtinNames.includes(spec.name),
             summary: "",
             toolset: spec.toolset,
-            tools: spec.toolset === "repo-readonly" ? ["repo_tree", "repo_read_file", "repo_pull_diff", "Now"] : ["Now"],
+            tools: spec.toolset === "repo-readonly" ? [REPO_TREE_TOOL_NAME, REPO_READ_FILE_TOOL_NAME, REPO_PULL_DIFF_TOOL_NAME, NOW_TOOL_NAME] : [NOW_TOOL_NAME],
             promptSummary: "",
             enabled: true,
             ...availabilityFields(deps, spec.toolset),
@@ -297,4 +298,19 @@ export function gateScenarioRequest(ruling, bodyScenario, defaultScenario, known
     }
     return name;
 }
+export function createScenarioGate(sources, leg) {
+    const rulingOf = (principal) => {
+        switch (leg) {
+            case "enforce":
+                return sources.principalCaps?.scenarioRuling(principal);
+            case "peek":
+                return sources.principalCaps?.peekScenarioRuling(principal);
+            default: {
+                const unhandled = leg;
+                return unhandled;
+            }
+        }
+    };
+    return async (principal, requested) => gateScenarioRequest(await rulingOf(principal), requested, sources.config.defaultScenario, Object.keys(sources.scenarios), sources.logger, principal);
+}
 //# sourceMappingURL=scenarios.js.map

package/dist/capabilities/select-environment-tool.js

@@ -1,4 +1,5 @@
 import { Type } from "typebox";
+import { SELECT_ENVIRONMENT_TOOL_NAME } from "./host-tool-names.js";
 import { BoundedSessionMap } from "../bounded-session-map.js";
 import { resolveSandboxImageRef } from "../per-task-image.js";
 export class SessionEnvironmentSelection {
@@ -22,7 +23,7 @@ async function availableProfiles(catalog, viewer) {
 }
 export function selectEnvironmentTool(deps) {
     return {
-        name: "SelectEnvironment",
+        name: SELECT_ENVIRONMENT_TOOL_NAME,
         description: "Switch this session's sandbox environment (image profile) or discover available ones. " +
             "Call with no arguments to list available profiles and their capabilities. " +
             "Call with `profile` (optionally `capabilitiesNeeded`) to select one. " +

package/dist/capabilities/send-user-file-tool.d.ts

@@ -43,7 +43,6 @@ export declare function sendUserFileTool(deps: {
     }) => Promise<IssuedFileLink>;
     emitter: SendUserFileEmitter;
 }): ToolSpec;
-export declare const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
 /**
  * The deployment's group for the delegated-child injection (`createSubagentExtraTools` in `builtin-tools.ts` composes it with
  * `Now` into the delegation tool's `extraTools` factory AND its `extraToolNames` roster — one list, read twice): SendUserFile,

package/dist/capabilities/send-user-file-tool.js

@@ -1,6 +1,7 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 import { Type } from "typebox";
 import { builtinAgentDefinitions } from "@sema-agent/core";
+import { SEND_USER_FILE_TOOL_NAME } from "./host-tool-names.js";
 export class SendUserFileEmitter {
     als = new AsyncLocalStorage();
     runWithContext(ctx, fn) {
@@ -19,7 +20,7 @@ export const SEND_USER_FILE_MAX_BYTES = 100 * 1024 * 1024;
 export const SEND_USER_FILE_MAX_CAPTION = 500;
 export function sendUserFileTool(deps) {
     return {
-        name: "SendUserFile",
+        name: SEND_USER_FILE_TOOL_NAME,
         description: "Send file(s) to the user — surfaced as downloadable/inline cards in their pane. " +
             "Use when the file itself is the deliverable (generated charts, reports, screenshots, build artifacts) " +
             "and you want it surfaced, not just mentioned. Files must already exist on local disk (this tool sends " +
@@ -91,7 +92,6 @@ export function sendUserFileTool(deps) {
         },
     };
 }
-export const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
 const READONLY_BUILTIN_AGENT_TYPES = new Set(builtinAgentDefinitions().map((d) => d.name));
 export function subagentSendUserFileExtraTools(deps) {
     return { tools: [deps.spec], forSpawn: (ctx) => !(ctx.agentType !== undefined && READONLY_BUILTIN_AGENT_TYPES.has(ctx.agentType)) };

package/dist/capabilities/skills.js

@@ -107,7 +107,7 @@ export function skillsForScenario(loaded, scenario) {
     return loaded.filter((k) => k.scenarios.length === 0 || k.scenarios.includes(scenario)).map((k) => k.spec);
 }
 export function parseFrontmatter(raw) {
-    const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(raw);
+    const m = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*\r?(?:\n|$)([\s\S]*)$/.exec(raw);
     if (!m)
         return { meta: {}, body: raw };
     const meta = {};

package/dist/capabilities/tool-defer.js

@@ -1,4 +1,5 @@
-export const LONGTAIL_DEFER_TOOLS = new Set(["SelectEnvironment"]);
+import { SELECT_ENVIRONMENT_TOOL_NAME } from "./host-tool-names.js";
+export const LONGTAIL_DEFER_TOOLS = new Set([SELECT_ENVIRONMENT_TOOL_NAME]);
 export function applyLongtailDefer(tools, enabled) {
     if (!enabled)
         return tools;