@sema-agent/server 7.130.0 → 7.132.0

package/dist/capabilities/mcp-probe.js

@@ -1,12 +1,10 @@
-import { probeMcpServers, readMcpToolAxes } from "@sema-agent/core";
+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, requestEntryIdentityRefusal, requestEntryToolAxesRefusal, validateRequestMcp, } from "../task-mcp.js";
-import { toCoreMcpServerSpec } from "../mcp-assertion-header.js";
-import { buildDisplaySafeUrl } from "../trace/redact.js";
+import { keyClosureClause, scanKeyClosure } from "../request-key-closure.js";
+import { requestMcpDeclarationRefusal, validateRequestMcp } from "../task-mcp.js";
+import { declaresMcpAssertionHeader, toCoreMcpServerSpec } from "../mcp-assertion-header.js";
 import { projectWiringManifestMcpRows } from "../trace/project.js";
 export const MCP_PROBE_REFUSAL_CODES = [
     "capability.mcp_injection_required",
@@ -42,113 +40,6 @@ const shapeRefusal = (message, unknownKeys) => ({
     ...(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) {
-        const refusal = requestEntryIdentityRefusal(entry);
-        if (refusal === undefined)
-            return null;
-        return refusal.errorCode === "request.body_shape" ? shapeRefusal(refusal.message) : fieldRefusal(refusal.message);
-    }
-    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 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`);
-    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)`);
-    }
-    const read0 = read.ok[0];
-    return declarationDowngradeIssue(entry, read0 === undefined ? undefined : toCoreMcpServerSpec(read0), at);
-}
-function declarationDowngradeIssue(entry, spec, at) {
-    if (spec === undefined)
-        return fieldRefusal(`${at} is not a readable MCP declaration`);
-    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)");
-}
-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;
-    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)") };
@@ -164,32 +55,30 @@ export function readMcpProbeBody(raw) {
         };
     }
     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 };
-    }
+    if (list === undefined || list === null)
+        return { ok: false, refusal: shapeRefusal("mcpServers is required: the declaration list to probe (send [] to ask about nothing)") };
+    const refusal = requestMcpDeclarationRefusal(list);
+    if (refusal !== undefined)
+        return { ok: false, refusal };
     const validated = validateRequestMcp(list);
-    if (validated === null || validated.ok.length !== list.length) {
+    const declared = Array.isArray(list) ? list.length : 0;
+    if (validated === null || validated.ok.length !== declared) {
         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)," +
+            refusal: fieldRefusal(`mcpServers: this deployment's declaration reader kept ${validated === null ? 0 : validated.ok.length} of the ${declared} declarations its judge accepted,` +
+                " so the probe refuses rather than dialing a silently shortened list. This is a belt on a path that should not be reachable (the judge and the reader read every key with the same predicate)," +
                 " so nothing in your body needs changing — if you see it, this deployment has a bug worth reporting"),
         };
     }
+    const carried = validated.ok.findIndex(declaresMcpAssertionHeader);
+    if (carried >= 0) {
+        return {
+            ok: false,
+            refusal: fieldRefusal(`mcpServers[${carried}].transport.assertionHeader is declared, but this engine does not send an assertion header yet — a task would mount the server WITHOUT it, ` +
+                "so a probe dialing it would describe a configuration you did not declare (a server that answers the handshake and asks for the assertion only on calls would read as connected). " +
+                "Probe the entry without the key to see how the server answers without it"),
+        };
+    }
     return { ok: true, specs: validated.ok.map(toCoreMcpServerSpec) };
 }
 export function buildMcpProbeIdentity(principal) {

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

@@ -1,4 +1,4 @@
-import { type WebFetchConfig, type BackgroundAgentStore, type CheckpointStore, type PromptProvider, type Runner, type SkillSpec, type TaskListStore, type ToolSpec, type WebSearchConfig } from "@sema-agent/core";
+import { type WebFetchConfig, type BackgroundAgentStore, type CheckpointStore, type Runner, type SkillSpec, type TaskListStore, type TaskSpec, type ToolSpec, type WebSearchConfig } from "@sema-agent/core";
 import type { Logger } from "../observability/logger.js";
 import { type SubagentExtraToolSet } from "./builtin-tools.js";
 import { type RepoReadClient } from "./repo-tools.js";
@@ -6,8 +6,8 @@ import { type LoadedSkill } from "./skills.js";
 import type { ScenarioHands } from "./hands-lane.js";
 /**
  * Scenario routing — a deployment serves many scenarios from one image. Each request's `scenario`
- * selects a pre-wired capability bundle: tools (incl. subagent roster) + a whole-harness prompt +
- * skills. Heavy bits (HTTP clients, skill files) are startup singletons; per task we only bind
+ * selects a pre-wired capability bundle: tools (incl. subagent roster) + its prompt seats + skills.
+ * Heavy bits (HTTP clients, skill files) are startup singletons; per task we only bind
  * coordinates and build cheap closures, so there is no per-request "assembly" cost.
  */
 export interface ScenarioRequest {
@@ -26,12 +26,33 @@ export interface ScenarioBundle {
      * `scan` 声明 clone-free 四件、实际拿到全量可写手)。
      */
     hands: ScenarioHands;
-    promptProvider?: PromptProvider;
+    /** 本场景对提示的贡献(缺席 = 不贡献:引擎目录的缺省角色)。经 {@link buildPromptSeats} 写进 `TaskSpec`,这是场景到提示的唯一通道。 */
+    prompt?: ScenarioPrompt;
     /** [ref] 场景解释层定死的终验开关(core TaskSpec.finalVerification):bench 实测产品默认请求与
      *  bench 态差距三件之一。[ref] 起无场景定死(autonomous 退役)——纯 caller 显式旋钮;spec 组装处 OR 折入(场景只会
      *  多加一轮收官验证,绝不收窄 caller 意图),壳/caller 不感知。 */
     finalVerification?: true;
 }
+/**
+ * 一个场景对提示的贡献 —— 只有两个座,都是 `TaskSpec` 上的任务类座位:
+ *  · `role`:选目录里的哪一种角色基底(`TaskSpec.promptRole`;缺席 = 引擎缺省 `general`);
+ *  · `roleText`:场景自己的角色文本,写在调用方 `systemPrompt` 之前一起进 `TaskSpec.systemPrompt`(它整替选中的角色基底)。
+ * 两者都**不许**是引擎目录的文本(抄目录文本 = 第二份文本;逐字含锁定段的角色文本引擎在 prepare 拒 `prompt.assembled_role_refused`)。
+ * 宪法、行为段、记忆段、追加段的落位全归引擎。
+ */
+export interface ScenarioPrompt {
+    readonly role?: NonNullable<TaskSpec["promptRole"]>;
+    readonly roleText?: string;
+}
+/**
+ * 一次请求写进 `TaskSpec` 的提示座 —— **`promptBinding` 的唯一写点**,HTTP 腿(`resolveSpec`)与 `run-local` 同用这一只:
+ *  · `promptBinding` = 场景名,恒写:它是引擎提示选择器的一维,每一类 overlay(中心 artifact / 部署注册 / 任务)的 `when.binding` 都读它 ——
+ *    不写 ⇒ 每条 `anyOf` 恒假、每条 `noneOf` 恒真,按场景定向的中心段与部署的品牌行全部失效。场景名过了场景门的文法
+ *    (`SCENARIO_NAME_RE`,≤ 32 个 ASCII 字)⇒ 恒在引擎 binding 文法之内(非空白、≤ `PROMPT_BINDING_MAX_CHARS` 码点);委派子代经父 spec 座继承它。
+ *  · `promptRole` = 场景的角色选择器(缺席 = 引擎缺省 `general`);
+ *  · `systemPrompt` = 角色文本(场景自己的在前、调用方 `systemPrompt` 在后,`\n\n` 相连;空串不占位;两者都缺席 ⇒ 键不写,调用方给的空串原样交引擎)。
+ */
+export declare function buildPromptSeats(scenarioName: string, prompt: ScenarioPrompt | undefined, callerSystemPrompt: string | undefined): Pick<TaskSpec, "promptBinding" | "promptRole" | "systemPrompt">;
 /**
  * [ref]:场景工厂的**服务端事实**上下文 —— 与 `req`(= 调用方请求体,不可信)分开的第三个入参。
  * 这里的每一位都由鉴权信道解析,调用方无法自报;新增位一律走本接口,绝不往 `req` 上加。
@@ -70,14 +91,6 @@ export interface ScenarioDeps {
      *  字节形,core 落「summarization unavailable」诚实兜底)。 */
     webFetchSummarize?: NonNullable<NonNullable<WebFetchConfig["summarize"]>>;
     logger?: Logger;
-    /**
-     * When true, the `default` scenario carries the Sema product identity (see {@link semaIdentityProvider}).
-     * Set by the local/TOC deployment (CONFIG_PROVIDER=local / run-local) so the local engine answers "who
-     * are you" as Sema instead of the model's hallucinated identity. Business scenarios (code-review)
-     * keep their own prompts; cloud (CONFIG_PROVIDER≠local) leaves the default scenario neutral unless turned
-     * on, so integrators that inject their own persona are unaffected.
-     */
-    brandIdentity?: boolean;
     /**
      * core 1.287 `SubagentToolOptions.extraTools` seam wire-through — per-SPAWN dynamic tool injection into the
      * delegated (Agent-tool) child roster. Deployment-injected per-task tools (today: SendUserFile — its instance is
@@ -126,8 +139,9 @@ export interface ScenarioDeps {
     taskListStoreFor?: (sessionId: string) => TaskListStore;
 }
 /**
- * Sema product identity, prepended to the core default base for the `default` scenario when
- * {@link ScenarioDeps.brandIdentity} is on. Honest about the substrate (the engine runs whichever model
+ * Sema product identity — the brand line of the `default` / `code` scenarios on a branded deployment (local / TOC). It is not a
+ * scenario seat: it is one deployment-class overlay (`capabilities/brand-identity.ts`, minted by `createDeploymentMods`) whose
+ * `when.binding` names the two scenarios. Honest about the substrate (the engine runs whichever model
  * the operator configured — not Claude/Anthropic), so the agent never inherits the model's training-time
  * "I am Claude" hallucination.
  *
@@ -138,34 +152,10 @@ export interface ScenarioDeps {
  * that maker's misstate its own substrate. Same for
  * the gateway protocol (the brain stack serves Anthropic-compatible routes too — routing brain +
  * createAnthropicBrain — so "OpenAI-compatible gateway" would be the same class of lie). Neutral wording
- * (zero core-seam need; interpolating the model id would need a `StablePromptContext.model`
- * seam and reads poorly for ugly preset ids). The anti-"I am Claude" design is kept — only the baked
+ * (interpolating the model id reads poorly for ugly preset ids). The anti-"I am Claude" design is kept — only the baked
  * substrate facts are removed.
  */
 export { SEMA_IDENTITY } from "./prompts/identity.js";
-/**
- * Prompt provider for the branded `default` scenario: SEMA_IDENTITY on top of the ROLE base — the
- * task's own `body.systemPrompt`, or core's {@link DEFAULT_SYSTEM_PROMPT} when none. Core 1.243
- * (提示词主权批) appends the constitution structurally AFTER this role layer (harness
- * safety blocks + modes + memory guidance + the prefix-cache-safe `<user_memory>` tail), so identity
- * cannot displace the safety blocks. The pre-1.243 form (identity + `defaultPromptProvider.stableSystem`,
- * i.e. an ALREADY-assembled prompt) would now trip the migration guard (anchor-detect → pass-through +
- * `onError(phase:"prompt-constitution")`) — this role-only form is the guard-free contract.
- */
-export declare function semaIdentityProvider(): PromptProvider;
-/**
- * `code` 场景的提示词提供者([ref] 造,[ref] clay 裁定改名 autonomous→code):role 基底 = core
- * {@link CODE_SYSTEM_PROMPT}(core 1.298 [ref] 改名批正名,旧名 FULL_BODY_SYSTEM_PROMPT=恒等
- * 别名过渡窗;CODE_AGENT persona + AUTONOMY_SELF_AUDIT + ANTI_VERBOSITY +
- * TOOL_PARAM_JSON;[ref] 谱系定论 = CC 生产编码提示词的蒸馏去牌版,底本随 CC 版本对表 cc-anchors,
- * 非自研)——与 bench 的请求组装完全同源,引用 core 常量随版本走,绝不复制字符串(tb bench 实测:
- * 产品默认请求与同引擎 bench 态的差距根因就在这三件 persona/自检/终验)。品牌层与
- * {@link semaIdentityProvider} 同构:brandIdentity 开时 SEMA_IDENTITY 叠在 role 基底之上;任务自带
- * systemPrompt 按同一优先序赢过基底(role 合成规则与 default 场景一致)。宪法由 core 1.243 在 role
- * 层之后结构化追加——此处只产 role-only 形态(guard-free 契约,同 semaIdentityProvider 注释)。
- * 无 systemPrompt 且无品牌时原样返回 core 常量(测试以引用比对锁 bench 同源,不做字符串快照)。
- */
-export declare function codePromptProvider(brand: boolean): PromptProvider;
 export declare function buildScenarios(deps: ScenarioDeps): Record<string, Scenario>;
 /**
  * Resolve the scenario bundle for a name. `undefined` = no preference ⇒ the built-in `default`; any OTHER name must be
@@ -203,7 +193,11 @@ export interface ScenarioDetail {
  *  这里没跟 = 编译红;wire 变更清单的自铸登记表(`trace/self-minted-wire.ts` 的 `builtinScenario`)同按它 `satisfies`。 */
 export declare const BUILTIN_SCENARIO_NAMES: readonly ["code", "default", "code-review", "scan"];
 export type BuiltinScenarioName = (typeof BUILTIN_SCENARIO_NAMES)[number];
-export declare function builtinScenarioDetails(scenarios: Record<string, Scenario>, deps: Pick<ScenarioDeps, "brandIdentity" | "repoClient">): Record<string, ScenarioDetail>;
+/**
+ * `branded` = 这台部署是不是品牌部署 —— 部署座挂品牌行读的同一只判官(`brand-identity.ts` `isBrandedDeployment`)交进来;没有默认值:每个调用点说出这件事实。
+ * 品牌部署上,品牌行 `when.binding` 那张表里的场景(`BRAND_IDENTITY_SCENARIOS`)的 `promptSummary` 点名 Sema 产品身份 —— 读面说的就是模型收到的。
+ */
+export declare function builtinScenarioDetails(scenarios: Record<string, Scenario>, deps: Pick<ScenarioDeps, "repoClient">, branded: boolean): Record<string, ScenarioDetail>;
 /** center 条目详情(有效性判定与 centerScenarios 完全同款:无效条目既不进 overlay 也不进详情——
  *  保证约定①「详情显示的来源=运行实际用的定义」永不错位)。 */
 export declare function centerScenarioDetails(specs: CenterScenarioSpec[] | undefined, builtinNames: string[], deps: Pick<ScenarioDeps, "repoClient">): Record<string, ScenarioDetail>;
@@ -296,16 +290,17 @@ export declare function danglingScenarioRefusal(name: string, source: ScenarioNa
  */
 export declare function gateScenarioRequest(ruling: ScenarioRuling | undefined, bodyScenario: unknown, defaultScenario: string, known: readonly string[], logger?: Logger, principal?: string): string;
 /**
- * 一条请求点名的场景名过门 —— {@link gateScenarioRequest} 的**唯一一处实参装配**。
+ * 一条请求的场景名过门 —— {@link gateScenarioRequest} 的**唯一一处实参装配**。
  *
  * 门的六个实参各有来源:中心裁定(`principalCaps.scenarioRuling`,按 principal)、请求点名的名字、部署缺省场景、**在册词表**
- * (`Object.keys(scenarios)` —— 场景表活引用,不抄快照)、日志与 principal。「这个场景能看见什么」这类问题有不止一个读面
- * (任务提交腿 `resolveSpec`、`GET /v1/capabilities/mcp?scenario=` 的状态面),每个读面自己拼一遍这六个实参 = 第二只门:
- * 两面对「在册」「放行」各判各的,读面就开始对不上 run。所以装配只在这里,读面持有的是**绑好的门**。
+ * (`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 胜者,否则部署缺省)—— 状态面只在**请求点名了**时才问门。
- * `principalCaps` 缺席(无中心 / 干跑 / 嵌入方)⇒ 无 ruling,门退回「请求名或部署缺省」那条现状链。
+ * 读口不改写)。`requested` 非串(缺席)⇒ 门走指派链(ruling 胜者,否则部署缺省),与 run 时同一读法。
+ * `principalCaps` 缺席(无中心 / 干跑 / 嵌入方 / `run-local`)⇒ 无 ruling,门退回「请求名或部署缺省」那条现状链。
  */
 export interface ScenarioGateSources {
     readonly config: {
@@ -323,7 +318,7 @@ export type ScenarioGate = (principal: string | undefined, requested: unknown) =
 /**
  * 门问中心裁定走哪条腿(闭集;新增一词 ⇒ 下面的穷尽 `switch` 编译红)—— 与 `resolveRuntimeCaps` / `peekRuntimeCaps` 是同一对:
  *  · `enforce` —— 任务提交腿:中心裁定走执法腿,center 硬失败铸下的 fail-closed 降级项两腿都认;
- *  · `peek` —— 读面(`GET /v1/capabilities/mcp?scenario=`):只读腿,同一只缓存 / 同一条抓取 / 同一份 fail-open 判决,但硬失败铸的降级项只对读面自己算数,
+ *  · `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";

package/dist/capabilities/scenarios.js

@@ -1,30 +1,17 @@
-import { CODE_AGENT_PROMPT, CODE_SYSTEM_PROMPT, DEFAULT_SYSTEM_PROMPT, WEB_FETCH_TOOL_NAME, assembleCodeTools, defaultTaskRegistry } from "@sema-agent/core";
+import { WEB_FETCH_TOOL_NAME, assembleCodeTools, defaultTaskRegistry } from "@sema-agent/core";
 import { HttpError, createCodedHttpError } from "../security.js";
 import { createSubagentExtraTools, extraToolsErrorFields, nowTool } from "./builtin-tools.js";
 import { parseRepo, repoToolsFor } from "./repo-tools.js";
-import { stablePrompt } from "./prompt.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 { createWebSearchBackend, judgeRequestWebSearch } from "../plugins/web-search.js";
 import { skillsForScenario } from "./skills.js";
-export { SEMA_IDENTITY } from "./prompts/identity.js";
-import { SEMA_IDENTITY } from "./prompts/identity.js";
-export function semaIdentityProvider() {
-    return {
-        stableBlocks: (ctx) => [
-            { id: "sema/identity", slot: "identity", text: `${SEMA_IDENTITY}\n\n${ctx.userSystemPrompt ?? DEFAULT_SYSTEM_PROMPT}` },
-        ],
-    };
-}
-export function codePromptProvider(brand) {
-    const roleBase = (ctx) => ctx.userSystemPrompt ?? (ctx.promptProfile === "classic" ? CODE_SYSTEM_PROMPT : CODE_AGENT_PROMPT);
-    if (!brand) {
-        return { stableSystem: (ctx) => roleBase(ctx) };
-    }
-    return {
-        stableBlocks: (ctx) => [
-            { id: "sema/identity", slot: "identity", text: `${SEMA_IDENTITY}\n\n${roleBase(ctx)}` },
-        ],
-    };
+import { BRAND_IDENTITY_SCENARIOS } from "./brand-identity.js";
+export function buildPromptSeats(scenarioName, prompt, callerSystemPrompt) {
+    const parts = [prompt?.roleText, callerSystemPrompt].filter((t) => typeof t === "string" && t.length > 0);
+    const systemPrompt = parts.length > 0 ? parts.join("\n\n") : callerSystemPrompt;
+    return { promptBinding: scenarioName, ...(prompt?.role !== undefined ? { promptRole: prompt.role } : {}), ...(systemPrompt !== undefined ? { systemPrompt } : {}) };
 }
+export { SEMA_IDENTITY } from "./prompts/identity.js";
 function requestWebSearchBackend(verdict, deployment, logger) {
     switch (verdict.kind) {
         case "absent":
@@ -74,14 +61,13 @@ export function buildScenarios(deps) {
             ],
             hands: "full",
             skills: skillsForScenario(deps.skills, "default"),
-            ...(deps.brandIdentity ? { promptProvider: semaIdentityProvider() } : {}),
         };
     };
     return {
         default: defaultScenario,
         code: (req, principal, ctx) => ({
             ...defaultScenario(req, principal, ctx),
-            promptProvider: codePromptProvider(deps.brandIdentity === true),
+            prompt: { role: "code" },
         }),
         "code-review": (req) => codeReview(deps, req),
         scan: (req) => {
@@ -110,7 +96,7 @@ function availabilityFields(deps, toolset) {
     return verdict.available ? { available: true } : { available: false, unavailableReason: verdict.reason };
 }
 export const BUILTIN_SCENARIO_NAMES = ["code", "default", "code-review", "scan"];
-export function builtinScenarioDetails(scenarios, deps) {
+export function builtinScenarioDetails(scenarios, deps, branded) {
     const probe = (name, req, principal, fallback) => {
         try {
             return ((Object.hasOwn(scenarios, name) ? scenarios[name] : undefined)?.(req, principal)?.tools ?? []).map((t) => t.name);
@@ -119,16 +105,15 @@ 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 brandedScenario = (name) => branded && BRAND_IDENTITY_SCENARIOS.includes(name);
     const details = {
-        code: mk("code", "编码主场景([891] 出厂缺省;CC 编码 persona 蒸馏版,default 全量工具面;终验旋钮独立)", "full-body", probe("code", {}, undefined, ["Now"]), 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)"),
+        code: mk("code", "编码主场景([891] 出厂缺省;CC 编码 persona 蒸馏版,default 全量工具面;终验旋钮独立)", "full-body", probe("code", {}, undefined, [NOW_TOOL_NAME]), `${brandedScenario("code") ? "Sema 产品身份 + " : ""}core 编码完全体提示词(CODE_AGENT persona+自治自检;CC 血统对表)`),
+        default: mk("default", "通用/助理场景(域中性 persona,CC agent loop 全量工具面;[891] 起非出厂缺省,显式可选)", "full-body", probe("default", {}, undefined, [NOW_TOOL_NAME]), brandedScenario("default") ? "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 +134,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),
@@ -229,13 +214,12 @@ function codeReview(deps, req) {
     const repoTools = repoToolsFor(repoClient, coords);
     const skills = skillsForScenario(deps.skills, "code-review");
     const hands = "none";
-    return { tools: [...repoTools, nowTool()], hands, skills, promptProvider: directReviewerPrompt };
+    return { tools: [...repoTools, nowTool()], hands, skills, prompt: { roleText: REVIEWER_ROLE_TEXT } };
 }
-const reviewBody = "Produce ONE prioritized review: a short summary, then findings grouped by severity " +
-    "(blocker / major / minor), each with `path:line`, the problem, and a concrete fix. Cite real code — never invent files or symbols.";
-const directReviewerPrompt = stablePrompt("You are a senior code reviewer. Call repo_tree to map the repository, then repo_read_file to read " +
+const REVIEWER_ROLE_TEXT = "You are a senior code reviewer. Call repo_tree to map the repository, then repo_read_file to read " +
     "the files in scope, then review them yourself. " +
-    reviewBody);
+    "Produce ONE prioritized review: a short summary, then findings grouped by severity " +
+    "(blocker / major / minor), each with `path:line`, the problem, and a concrete fix. Cite real code — never invent files or symbols.";
 export function mergeUserSkills(scenarioSkills, userSkills, logger) {
     if (!userSkills || userSkills.length === 0)
         return scenarioSkills;

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

@@ -1,5 +1,6 @@
 import type { SkillSpec } from "@sema-agent/core";
 import type { RemoteExecProvider } from "../execution-lane-caps.js";
+import { type Logger } from "../observability/logger.js";
 /**
  * Built-in skills baked into the image, loaded ONCE at startup (no per-task disk IO). A skill is a
  * Markdown capability (frontmatter + body). core uses **progressive disclosure** (core ≥1.98.0):
@@ -26,6 +27,10 @@ import type { RemoteExecProvider } from "../execution-lane-caps.js";
  *   description: when to use it
  *   scenarios: code-review, oa     # which scenarios get it; omit = all scenarios
  *   ---
+ *
+ * 🔴 **frontmatter 读不了的技能不装,不降成全局技能**(安全轴:`scenarios` 是场景围栏,丢了它技能就对每个场景可见):文件第一行是围栏(`---`,行尾只许空白 / 制表 / CR,
+ * 与 CC 2.1.296 的开头正则同判)而块没有收尾 ⇒ {@link parseFrontmatter} 答 `unclosed`,这一个技能被**拒载**并落一行 `skill_refused` warn(点名技能与文件、不带正文);
+ * 兄弟技能照装。第一行不是围栏的文件没有 frontmatter,是正当的全局技能。
  */
 export interface LoadedSkill {
     spec: SkillSpec;
@@ -52,6 +57,8 @@ export interface LoadSkillsOptions {
      * core 的律也明写缺席 ⇒ 结果逐字节与 baseDir 到货之前相同)。两个方向不对称 ⇒ 默认取轻的那边。
      */
     toolsShareThisFilesystem?: boolean;
+    /** 拒载一行 warn 的出口(见文件头注「frontmatter 读不了的技能不装」)。缺席 ⇒ 进程的 JSON 行 logger(`createLogger("warn")`,stderr)—— 拒载没有「安静」的形;装配点传自己的 logger 只为字段与级别跟部署同一份。 */
+    logger?: Logger;
 }
 /** `p` 的 realpath 必须落在 `rootReal` 之内(含自身),否则抛。`sep` 边界判定防 `/a/root-evil` 撞
  *  `/a/root` 前缀。目标不存在 ⇒ realpath 抛 ENOENT,同样是拒绝(悬空链接不该被读)。
@@ -70,12 +77,20 @@ export declare function loadDeploymentSkills(config: {
     readonly remoteExec?: {
         readonly provider: RemoteExecProvider;
     } | undefined;
-}): LoadedSkill[];
+}, logger?: Logger): LoadedSkill[];
 /** Skills applicable to a scenario: those tagged with it, plus untagged (global) ones.
  *  [ref]:alias 窗撤销,单键查询——退役旧名标签不再命中(迁移面在 7.44 发车帖/MIGRATION 记载)。 */
 export declare function skillsForScenario(loaded: LoadedSkill[], scenario: string): SkillSpec[];
-export declare function parseFrontmatter(raw: string): {
-    meta: Record<string, string>;
-    body: string;
+/** {@link parseFrontmatter} 的三种读数(闭集):`absent` = 第一行不是围栏,没有 frontmatter(正当的全局技能)· `block` = 围栏收好了的块 · `unclosed` = 第一行是围栏而块没收好(读不了 —— 调用方拒载)。 */
+export type FrontmatterRead = {
+    readonly kind: "absent";
+    readonly body: string;
+} | {
+    readonly kind: "block";
+    readonly meta: Record<string, string>;
+    readonly body: string;
+} | {
+    readonly kind: "unclosed";
 };
+export declare function parseFrontmatter(raw: string): FrontmatterRead;
 //# sourceMappingURL=skills.d.ts.map