@sema-agent/server 1.322.0 → 2.0.0

package/dist/capabilities/scenarios.d.ts

@@ -3,6 +3,12 @@ import type { Metrics } from "../observability/metrics.js";
 import type { Logger } from "../observability/logger.js";
 import { GiteaClient } from "./repo-tools.js";
 import { type LoadedSkill } from "./skills.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
+ * coordinates and build cheap closures, so there is no per-request "assembly" cost.
+ */
 export interface ScenarioRequest {
     scenario?: string;
     repo?: string;
@@ -12,22 +18,37 @@ export interface ScenarioBundle {
     tools: ToolSpec[];
     skills: SkillSpec[];
     promptProvider?: PromptProvider;
+    /** [849] 场景解释层定死的终验开关(core TaskSpec.finalVerification):bench 实测产品默认请求与
+     *  bench 态差距三件之一。只有 `autonomous` 置 true;spec 组装处与 caller 显式声明取 OR(场景只会
+     *  多加一轮收官验证,绝不收窄 caller 意图),壳/caller 不感知。 */
     finalVerification?: true;
 }
 export type Scenario = (req: ScenarioRequest, principal?: string) => ScenarioBundle;
 export interface ScenarioDeps {
     runner: Runner;
+    /** In-memory runner for ephemeral sub-tasks (council lenses/arbiter) — keeps them out of TiDB. */
     subRunner: Runner;
     model: string;
     skills: LoadedSkill[];
     repoClient?: GiteaClient;
+    /** Multi-tenant deployment (REQUIRE_PRINCIPAL). Gates the full-body `WebFetch` tool out of the
+     *  default roster — core says a multi-tenant deployment MUST allowlist hosts (an injected/malicious tenant model
+     *  could exfil via an arbitrary public URL; the SSRF floor only blocks internal). Single-user TOC keeps WebFetch. */
     requirePrincipal?: boolean;
+    /** Deployment-injected WebSearch backend (Brave/Tavily/SearXNG via `WEB_SEARCH_PROVIDER`). When set,
+     *  `assembleCodeTools` mounts the WebSearch tool; absent ⇒ not assembled (core ships no search backend). */
     webSearch?: WebSearchConfig;
+    /** [1900]/[1904] WebFetch 摘要器(core `makeWebFetchSummarizer(brain, summarize 角色模型)` 的产物,
+     *  main.ts 构造一次注入)。在场 ⇒ 装配实参携 `webFetch.summarize`——带 prompt 的 WebFetch 走 cheap
+     *  模型摘要而非整页灌上下文([1870] L1 的 ~660× 放大就是这缝);缺席 ⇒ `webFetch` 键不铸(修前
+     *  字节形,core 落「summarization unavailable」诚实兜底)。 */
     webFetchSummarize?: (content: string, prompt: string, signal?: AbortSignal) => Promise<string>;
     metrics?: Metrics;
     logger?: Logger;
+    /** OA backend coordinates for the `oa` scenario (read /api/v1, write /api/assets). */
     oaApiBaseUrl?: string;
     oaServiceToken?: string;
+    /** 可选：`oa` 场景注入"开 Gitea issue"工具(OA AI 请求#5)；repo/token/labels 固定，模型只填 title/body。 */
     oaIssue?: {
         baseUrl: string;
         owner: string;
@@ -35,29 +56,113 @@ export interface ScenarioDeps {
         token: string;
         defaultLabels?: number[];
     };
+    /**
+     * 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 (oa/team/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
+     * execute-time late-bound via ctx.taskId → TaskEnvRegistry, so ONE spec serves every spawn) cannot ride the
+     * ASSEMBLY-time static `subagent.tools` pool; this factory is evaluated by core at each spawn and its product is
+     * merged into the pool, then goes through core's `resolveToolSubset` whitelist like any other tool (agent-def
+     * allowTools/denyTools still govern — no extra gate needed on our side). Absent ⇒ no dynamic injection (children
+     * see exactly the static full-body roster, the pre-1.287 behavior).
+     */
     subagentExtraTools?: (ctx: SubagentSpawnContext) => ToolSpec[];
+    /**
+     * core 1.364 durable background agents(design/151 S1,[1503] 提货单②写半场):后台子代 `a*` 行的
+     * durable 执行记录 store。**必须与 `RunnerDeps.backgroundAgentStore` 同实例**(读写双点配对,engine
+     * 无法核对——半接=静默死特性,RB-37①)。绝不在这里另起实例。absent ⇒ pre-151 行为(settle 后
+     * eager release,读面纯 live)。
+     */
     backgroundAgentStore?: BackgroundAgentStore;
+    /**
+     * core 1.382(design/153 二拍B 件1+件2,parked 状态机)[1561] 提货单①②:「同车必接」的一对——core
+     * `parkEligible` 门要求 checkpointStore 与 ensureChildSessionDurable **全在场**才成立,任一缺席 = 净是
+     * pre-153 行为(子代 SAFETY ask 照旧 deny+continue,零回归)。
+     *  - `checkpointStore` 必须与 `RunnerDeps.checkpointStore`(主 runner 的 per-task spec 面)**同实例**
+     *    ——子代 suspend 在那里铸 token,异实例 = park 全静默失效(core JSDoc 钉过症状,组装区注释同步)。
+     *  - `ensureChildSessionDurable` = park 提交前的 capability 挂点(core 签名 `(sessionId) => Promise<void>`)
+     *    ——resolve = 该子代 session 已从任意进程可读,reject/缺席 = veto(子代按 pre-153 settle failed,
+     *    checkpoint 被 expire)。**本车保守实现**:只在子代 session 已经真正路由到宿主 durable 会话店
+     *    **且真有内容**(`getLeafId() !== null`——排除 F-7 同族的空壳 claim-create 行,那种行 acquire
+     *    命中但零内容,是`register()`对任意自报 sessionId 的副作用,不是真正 durable 的会话)时 resolve
+     *    (=fork 续聊的常见形),其余一律 reject——不做「主动迁移私店会话进 durable 店」这一步
+     *    (ForkRoutingSessionStore 的路由表是私有状态,无迁移 API;主动迁移是更大的活,candidate 留给
+     *    后续按需再做)。
+     */
     checkpointStore?: CheckpointStore;
     ensureChildSessionDurable?: (sessionId: string) => Promise<void>;
 }
+/**
+ * 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
+ * the operator configured — not Claude/Anthropic), so the agent never inherits the model's training-time
+ * "I am Claude" hallucination.
+ *
+ * Live-caught incident (a Qwen3.5 deployment self-described as "running on a DeepSeek model"):
+ * NOTHING substrate-specific may be hardcoded here — onboard is multi-provider (Qwen/GLM/Kimi/self-hosted
+ * vLLM…), so a baked maker name makes every non-DeepSeek deployment 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
+ * 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` 场景的提示词提供者([849] 造,[891] clay 裁定改名 autonomous→code):role 基底 = core
+ * {@link CODE_SYSTEM_PROMPT}(core 1.298 [891] 改名批正名,旧名 FULL_BODY_SYSTEM_PROMPT=恒等
+ * 别名过渡窗;CODE_AGENT persona + AUTONOMY_SELF_AUDIT + ANTI_VERBOSITY +
+ * TOOL_PARAM_JSON;[891] 血缘定论 = 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;
+/** @deprecated [891] 改名 code——一版过渡期保留旧符号(与场景名 alias 同窗退役)。 */
 export declare const autonomousPromptProvider: typeof codePromptProvider;
 export declare function buildScenarios(deps: ScenarioDeps): Record<string, Scenario>;
+/** Resolve the scenario for a request (falls back to `default`). */
 export declare function selectScenario(scenarios: Record<string, Scenario>, name: string | undefined): Scenario;
+/** web 渲染契约(定稿形状;knobs 现在没有=整字段省略)。 */
 export interface ScenarioDetail {
     name: string;
+    /** selectScenario 实际用哪份定义(center 同名 shadow 时="center")——与 centerScenarios overlay 同判定源。 */
     source: "builtin" | "center";
+    /** 是否存在同名内建定义(被 shadow 时仍 true,web 画锁徽章+shadow 标注)。 */
     builtin: boolean;
     summary: string;
     toolset: string;
     tools: string[];
+    /** 内建=概览(不外泄提示词资产全文);center 条目=prompt 原文(本就 ≤4KB 明文在配置域)。 */
     promptSummary: string;
     enabled: boolean;
 }
+/** 内建六场景详情。default/autonomous/team 工厂对良性请求无副作用可真调(拿真实工具名单);code-review/scan/oa 是
+ *  fail-loud 语义(缺 GIT_API/OA 配置/principal 即 throw)→ 探针失败落静态表兜底(表↔工厂一致性由测试锁:
+ *  测试喂 fake deps 真调工厂对账工具名)。enabled 对内建恒 true(约定②)。 */
 export declare function builtinScenarioDetails(scenarios: Record<string, Scenario>, deps: Pick<ScenarioDeps, "brandIdentity">): Record<string, ScenarioDetail>;
+/** center 条目详情(有效性判定与 centerScenarios 完全同款:无效条目既不进 overlay 也不进详情——
+ *  保证约定①「详情显示的来源=运行实际用的定义」永不错位)。 */
 export declare function centerScenarioDetails(specs: CenterScenarioSpec[] | undefined, builtinNames: string[]): Record<string, ScenarioDetail>;
 export interface CenterScenarioSpec {
     name: string;
@@ -66,14 +171,39 @@ export interface CenterScenarioSpec {
     enabled?: boolean;
 }
 export declare const SCENARIO_NAME_RE: RegExp;
+/**
+ * Build the center-declared scenario overlay. Invalid specs are SKIPPED with a warning (never fail
+ * boot — same posture as skills/teams); valid ones become scenarios keyed by name, ready to be merged
+ * OVER the built-ins (center wins). Returns the overlay plus which built-in names it shadows.
+ */
 export declare function centerScenarios(deps: ScenarioDeps, specs: CenterScenarioSpec[] | undefined, builtinNames: string[], logger?: Logger): {
     overlay: Record<string, Scenario>;
     shadows: string[];
 };
+/**
+ * Personalization seam: merge the caller's own skills AFTER the scenario's, with
+ * SCENARIO-WINS on a name clash — the security baseline (scenario/center skills) can never be shadowed
+ * by user content. Duplicate names within the user list keep the first. Clashes are logged for audit
+ * (silent drops would make "my skill didn't fire" undebuggable). Input is already shape/size-validated
+ * by the HTTP layer (validateUserSkills); this stays pure merge policy.
+ */
 export declare function mergeUserSkills(scenarioSkills: SkillSpec[] | undefined, userSkills: SkillSpec[] | undefined, logger?: Logger): SkillSpec[] | undefined;
+/** center caps view 的解析结果两键(形状钉死)。`scenario` null = 三层皆未配。 */
 export interface ScenarioRuling {
     scenario: string | null;
+    /** 纯场景名集合(principal/组名不上 wire);空 = 该 principal 无任何指派 = 无治理。 */
     allowlist: string[];
 }
+/**
+ * resolveSpec 的执法入口(指派为默认、body.scenario 可换但限 allowlist)。返回本请求的
+ * 生效场景名(未做 unknown→default 回退——那是 resolveSpec 既有职责,保持单点)。
+ *
+ *   - body.scenario 显式给出:allowlist 非空且集外 ⇒ typed 拒绝(400 `scenario_not_allowed`,附 allowlist
+ *     ——机器码归 wire、人话归壳/web);集内 ⇒ 用户主动切换赢。allowlist 为空(无 ruling / 该 principal
+ *     三层皆无指派 / caps 面故障)⇒ 无治理约束,现状放行(与「null 落兜底链」同一语义:分配面未覆盖 =
+ *     不收紧,恒不比没有治理时更宽;caps 故障不把用户锁死在 default——场景切换不是权限放大面,fail-open
+ *     到现状,与 workflows 面的 fail-closed 是刻意的 posture 差异,见 runtime-caps-resolver)。
+ *   - body.scenario 未给:ruling 胜者 ⇒ 指派为默认;无胜者 ⇒ defaultScenario 现状链。
+ */
 export declare function gateScenarioRequest(ruling: ScenarioRuling | undefined, bodyScenario: unknown, defaultScenario: string): string;
 //# sourceMappingURL=scenarios.d.ts.map

package/dist/capabilities/scenarios.js

@@ -8,29 +8,101 @@ import { createTeamTool, teamCoordinatorPrompt, getTeam, teamNames } from "./tea
 import { oaTools, oaPrompt } from "./oa-tools.js";
 import { createWebSearchBackend, webSearchConfigFromSettings } from "../plugins/web-search.js";
 import { skillsForScenario } from "./skills.js";
-export { SEMA_IDENTITY } from "./prompts/identity.js";
+/**
+ * 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
+ * the operator configured — not Claude/Anthropic), so the agent never inherits the model's training-time
+ * "I am Claude" hallucination.
+ *
+ * Live-caught incident (a Qwen3.5 deployment self-described as "running on a DeepSeek model"):
+ * NOTHING substrate-specific may be hardcoded here — onboard is multi-provider (Qwen/GLM/Kimi/self-hosted
+ * vLLM…), so a baked maker name makes every non-DeepSeek deployment 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
+ * substrate facts are removed.
+ */
+export { SEMA_IDENTITY } from "./prompts/identity.js"; // copy moved to the bundle-data layer
 import { 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 function semaIdentityProvider() {
+    // Lens-4 endgame (core 1.310, [1006]②/[1012]): the typed stableBlocks branch now carries core's OWN
+    // pass-through guard (M9-family anchor detection on identity declarations → provider-assembled,
+    // un-doubled) — the 0c3352f server-side fallback routing for the already-assembled input face is
+    // retired; the real-composer parity matrix keeps that face pinned byte-equal against the pre-M14 form.
     return {
+        // M14 (core 1.303, 板 [968]): the branded head is a TYPED block — the stable id "sema/identity" gives
+        // it a manifest section identity + digest (the G-1 observability gap; IDENTITY-DIGEST-MIGRATION.md
+        // route B, this hook is its carrier). identity-slot semantics: the block REPLACES core/role.base at
+        // the head position, so it must carry the FULL role layer (identity + role base) — byte-identical to
+        // the previous stableSystem string. Finer identity/role digest separation is the catalog-section
+        // endgame, not this hook's job.
         stableBlocks: (ctx) => [
             { id: "sema/identity", slot: "identity", text: `${SEMA_IDENTITY}\n\n${ctx.userSystemPrompt ?? DEFAULT_SYSTEM_PROMPT}` },
         ],
     };
 }
+/**
+ * `code` 场景的提示词提供者([849] 造,[891] clay 裁定改名 autonomous→code):role 基底 = core
+ * {@link CODE_SYSTEM_PROMPT}(core 1.298 [891] 改名批正名,旧名 FULL_BODY_SYSTEM_PROMPT=恒等
+ * 别名过渡窗;CODE_AGENT persona + AUTONOMY_SELF_AUDIT + ANTI_VERBOSITY +
+ * TOOL_PARAM_JSON;[891] 血缘定论 = 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 function codePromptProvider(brand) {
+    // [1158]/[1161]/[1162] b 案(clay 拍):provider 供给的字节 core 永不改写(provenance 卫,1.329),
+    // 所以 known-constant narrowing 够不着 provider 手里的 CODE_SYSTEM_PROMPT——simple 形的「裸底」
+    // 由 server 自己按 ctx.promptProfile 选 core 常量(CODE_AGENT_PROMPT=core 1.329 narrowing 的同一
+    // 目标常量,引用不复制,[891] 同源铁律)。classic 全链字节等价旧形;行为九段随 pack 走(平形
+    // stableSystem/stableBlocks 都不排段;server 从未用 replaceAll)。
     const roleBase = (ctx) => ctx.userSystemPrompt ?? (ctx.promptProfile === "classic" ? CODE_SYSTEM_PROMPT : CODE_AGENT_PROMPT);
+    // Unbranded: plain role layer via the string hook — core keeps its own core/role.base section identity,
+    // and the reference-equality bench-parity tests keep comparing the exact core constant.
     if (!brand) {
         return { stableSystem: (ctx) => roleBase(ctx) };
     }
+    // Branded: same M14 typed form as semaIdentityProvider (identity slot = role-layer replacement with the
+    // brand line on top; the base under the brand follows the SAME profile fork — the brand overlay is the
+    // legal divergence ([1134] 宪法二类), the base stays core-owned bytes).
     return {
         stableBlocks: (ctx) => [
             { id: "sema/identity", slot: "identity", text: `${SEMA_IDENTITY}\n\n${roleBase(ctx)}` },
         ],
     };
 }
+/** @deprecated [891] 改名 code——一版过渡期保留旧符号(与场景名 alias 同窗退役)。 */
 export const autonomousPromptProvider = codePromptProvider;
 export function buildScenarios(deps) {
+    // The default scenario filters skills by "default" — NOT by req.scenario (which may be an unknown name
+    // that fell back here): the bundle must be a coherent "default" set, matching how main.ts resolves an
+    // unknown scenario to "default" for tools/prompt/mcp too (council finding — else default-tagged drop).
+    // 抽成具名工厂:`autonomous` 直接复用它取 bundle(工具/技能面与 default 恒等由构造保证,不靠两处
+    // 各写一份 assembleCodeTools 参数再祈祷不漂移)。
     const defaultScenario = (req) => {
+        // gap-audit rank-1 BLOCKER: the default agent is the CC agent loop — it MUST have the
+        // full-body roster, not just nowTool. core's `assembleCodeTools` (1.161) ships TodoWrite (planning) +
+        // the subagent/Task delegation tool (runs on the sub-runner, child ⊆ parent — no escalation) + WebFetch.
+        // 🔒 WebFetch is GATED OUT on a multi-tenant deployment (REQUIRE_PRINCIPAL): allowHosts is unset = all PUBLIC,
+        // and core says a multi-tenant deployment MUST allowlist (an injected tenant model could exfil via an
+        // arbitrary public URL — the SSRF floor only blocks INTERNAL). Single-user TOC keeps it (the user's own box).
+        // WebSearch backend resolution: a per-request `body.settings.webSearch` (the user's shell settings) WINS, but
+        // ONLY on the single-user host lane (a per-request endpoint/key is a capability config — on multi-tenant a tenant
+        // could SSRF via a `searxng` URL pointed at an internal host, so multi-tenant uses ONLY the deployment-env
+        // `deps.webSearch`; design/107 axis, mirrors settings.env). Absent both ⇒ WebSearch not assembled (core ships none).
         const reqWebSearch = deps.requirePrincipal !== true
             ? webSearchConfigFromSettings(req?.settings?.webSearch)
             : undefined;
@@ -39,9 +111,29 @@ export function buildScenarios(deps) {
             tools: [
                 nowTool(),
                 ...assembleCodeTools({
+                    // [1900]/[1904]:WebFetch 摘要缝——键在场才铸(负控=修前字节形)。
                     ...(deps.webFetchSummarize ? { webFetch: { summarize: deps.webFetchSummarize } } : {}),
+                    // CC 201 parity: CC 201 makes the two planning families MUTUALLY
+                    // EXCLUSIVE — with TodoV2 (the Task trio) enabled, TodoWriteTool.isEnabled returns false and the
+                    // interactive model sees ONE family (TodoWrite survives only as an SDK/non-interactive compat slot).
+                    // Both-on was the CC 198 posture (live-caught cost: the model wastes a turn comparing the two tools
+                    // and juggles duplicate state). taskList:true below ⇒ TodoWrite OFF.
                     todoWrite: false,
+                    // core 1.215 (design/119): the structured task-list family (TaskCreate/TaskGet/TaskUpdate/TaskList —
+                    // stable ids, status transitions, dependencies); core defaults it OFF, the full-body deployment opts
+                    // in. Under CC 201 this family is the ONLY planning leg (see todoWrite above).
                     taskList: true,
+                    // core 1.206 (design/115 P3): `background` exposes CC's `run_in_background` on the Agent tool — the
+                    // child runs async under an `a*` task id (TaskOutput/TaskStop; ONE "later" completion notification;
+                    // parent teardown aborts orphans). Same trust envelope as the sync path (child ⊆ parent roster, same
+                    // rights) — only the scheduling is async, so no posture gate. owner/scope: core 1.365 BREAKING 升必填,
+                    // 但 core 仍 ctx-first(subagent.js `ctx.taskId ?? bg.owner` / `ctx.principal ?? bg.scope`)——引擎链
+                    // 每 spawn 恒带 ctx.taskId,这里的值是类型要求的兜底:scope="default" 与引擎链 `principal ?? "default"`
+                    // 同词([1509] 单租户拼法);owner 哨兵在 ctx.taskId 缺席的病态窗把行锚到无人可匹配的键(fail-closed
+                    // 方向,default-deny 谓词下不可读,绝不放大)。
+                    // core 1.364 agentStore = durable 写半场,与 RunnerDeps.backgroundAgentStore 同实例(deps 注入)。
+                    // core 1.382 checkpointStore/ensureChildSessionDurable = design/153 parked 状态机的「同车必接」
+                    // 一对([1561] 提货单①②,ScenarioDeps 字段注释详述);两者任一缺席 = 净是 pre-153 行为。
                     subagent: {
                         runner: deps.subRunner,
                         background: {
@@ -52,7 +144,11 @@ export function buildScenarios(deps) {
                             ...(deps.checkpointStore ? { checkpointStore: deps.checkpointStore } : {}),
                             ...(deps.ensureChildSessionDurable ? { ensureChildSessionDurable: deps.ensureChildSessionDurable } : {}),
                         },
+                        // core 1.287 extraTools seam ([795]/[802]③): per-spawn dynamic tool injection (SendUserFile
+                        // reaches the delegated-child roster; product still goes through resolveToolSubset).
                         ...(deps.subagentExtraTools ? { extraTools: deps.subagentExtraTools } : {}),
+                        // 历史复审轴B #3(1.254):extraTools 工厂 throw 的错误 sink——core 契约「absent ⇒ dropped after
+                        // the generic disclosure」= 部署日志零痕迹,只剩模型面固定 note。接 warn 让故障可观测。
                         ...(deps.subagentExtraTools && deps.logger
                             ? { onExtraToolsError: (err, info) => deps.logger?.warn?.("subagent_extra_tools_error", { ...info, err: err instanceof Error ? err.message : String(err) }) }
                             : {}),
@@ -61,21 +157,41 @@ export function buildScenarios(deps) {
                 }).filter((t) => t.name !== "WebFetch" || deps.requirePrincipal !== true),
             ],
             skills: skillsForScenario(deps.skills, "default"),
+            // Local/TOC deployment brands the neutral default scenario as Sema (so the local engine answers "who
+            // are you" as Sema, not the model's hallucinated identity). Cloud leaves it neutral unless opted in.
             ...(deps.brandIdentity ? { promptProvider: semaIdentityProvider() } : {}),
         };
     };
     return {
         default: defaultScenario,
+        // [849]→[891] code(原名 autonomous,clay 裁定改名+persona×终验解耦):与 default 完全同 roster
+        // (full-body 工具面 + default 技能面原样复用,连 WebFetch 多租户闸/WebSearch 装配都跟着 default
+        // 工厂走),只换一轴——role 基底 = core CODE_SYSTEM_PROMPT(CC 编码 persona 蒸馏版,见
+        // codePromptProvider)。**不再定死 finalVerification**([891] 解耦:终验是无人值守运行模式旋钮,
+        // caller 显式声明,交互态不多烧终验轮)。这是 [891] 起的出厂缺省场景(config DEFAULT_SCENARIO
+        // 缺省 "code")——编码产品出厂态对标 CC 出厂态;通用域中性 persona 的 default 保留为显式可选。
+        // 刻意走内建、不走 center overlay:overlay 已无 prompt 通道([1053] ScenarioEntry.prompt 直删,场景级提示词=center prompts binding)。
         code: (req, principal) => ({
             ...defaultScenario(req, principal),
             promptProvider: codePromptProvider(deps.brandIdentity === true),
         }),
+        // [891] 兼容 alias(一版过渡,deprecation warn 在 main.ts 解析处):旧语义逐字保留 —— code persona
+        // + finalVerification 场景层定死 true(存量 TB harness/部署传 "autonomous" 的行为一根毛不变;
+        // 新调用方要终验请显式传 body.finalVerification)。
         autonomous: (req, principal) => ({
             ...defaultScenario(req, principal),
             promptProvider: codePromptProvider(deps.brandIdentity === true),
             finalVerification: true,
         }),
         "code-review": (req) => codeReview(deps, req),
+        // Neutral repo-readonly scenario (OA ask): the SAME clone-free read-only repo tools as code-review
+        // (repo_tree / repo_read_file / repo_pull_diff over GIT_API_TOKEN) with NO promptProvider — the
+        // objective and the center-distributed skills own the output contract. The reviewer framing was
+        // never a security control (the boundary is the token's scope + the read-only tool set); it only
+        // fought skill-driven outputs (live: oa-repo-scan loaded but the lead still wrote a review).
+        // Deliberately NOT the alternative "let a scenario-targeted skill override promptProvider": that
+        // would let runtime-distributed content rewrite the deployment-pinned system prompt and break the
+        // stablePrompt STABLE→VARIABLE prefix-cache discipline (design/12/17).
         scan: (req) => {
             if (!deps.repoClient)
                 throw new HttpError(501, "scan scenario needs GIT_API_BASEURL configured");
@@ -90,8 +206,11 @@ export function buildScenarios(deps) {
         oa: (req, principal) => {
             if (!deps.oaApiBaseUrl || !deps.oaServiceToken)
                 throw new HttpError(501, "oa scenario needs OA_API_BASEURL + OA_SERVICE_TOKEN configured");
+            // OA enforces the END USER's RBAC from the forwarded principal — without one, every OA call would
+            // run unattributed. Refuse rather than silently send a null principal.
             if (!principal)
                 throw new HttpError(401, "oa scenario requires an authenticated principal (set REQUIRE_PRINCIPAL + x-agent-principal)");
+            // 写权限的"开 issue"工具仅当配置了 OA_ISSUE_* 时注入；token/repo 固定，模型只填 title/body。
             const issueTool = deps.oaIssue
                 ? [createGiteaIssueTool({ ...deps.oaIssue, name: "open_gitea_issue", description: "把用户的 bug/需求开成 Gitea issue 报给老板。只填 title(简洁)/body(现象、影响、复现/建议)。仓库与标签由部署固定。" })]
                 : [];
@@ -101,9 +220,13 @@ export function buildScenarios(deps) {
                 promptProvider: oaPrompt,
             };
         },
+        // Multi-agent team: pick a template, the consumer (OA) injects business context, we run it.
+        // Templates resolve from the live registry (`getTeam`) = BUILTIN_TEAMS overridden/extended by the
+        // sema registry at runtime (applyEffective → registerTeams), so a team is config-driven; built-ins
+        // are the fallback when the center supplies none.
         team: (req) => {
             const name = typeof req.team === "string" ? req.team : "default";
-            const template = getTeam(name);
+            const template = getTeam(name); // built-ins, overridden/extended by the sema registry at runtime
             if (!template) {
                 throw new HttpError(404, `unknown team "${name}" (available: ${teamNames().join(", ")})`);
             }
@@ -117,16 +240,20 @@ export function buildScenarios(deps) {
         },
     };
 }
+/** Resolve the scenario for a request (falls back to `default`). */
 export function selectScenario(scenarios, name) {
     return (name && scenarios[name]) || scenarios.default;
 }
+/** 内建六场景详情。default/autonomous/team 工厂对良性请求无副作用可真调(拿真实工具名单);code-review/scan/oa 是
+ *  fail-loud 语义(缺 GIT_API/OA 配置/principal 即 throw)→ 探针失败落静态表兜底(表↔工厂一致性由测试锁:
+ *  测试喂 fake deps 真调工厂对账工具名)。enabled 对内建恒 true(约定②)。 */
 export function builtinScenarioDetails(scenarios, deps) {
     const probe = (name, req, principal, fallback) => {
         try {
             return (scenarios[name]?.(req, principal)?.tools ?? []).map((t) => t.name);
         }
         catch {
-            return fallback;
+            return fallback; // 工厂 fail-loud(部署未配该场景的后端)→ 静态名单(web 仍能展示工具面选项)
         }
     };
     const REPO_TOOLS = ["repo_tree", "repo_read_file", "repo_pull_diff", "Now"];
@@ -145,6 +272,8 @@ export function builtinScenarioDetails(scenarios, deps) {
         team: mk("team", "多智能体团队圆桌(模板成员+synthesizer,模板可由 registry 配置)", "team", probe("team", {}, undefined, ["run_team"]), "团队协调者提示词(圆桌纪律+合成流程)"),
     };
 }
+/** center 条目详情(有效性判定与 centerScenarios 完全同款:无效条目既不进 overlay 也不进详情——
+ *  保证约定①「详情显示的来源=运行实际用的定义」永不错位)。 */
 export function centerScenarioDetails(specs, builtinNames) {
     const out = {};
     for (const spec of specs ?? []) {
@@ -158,9 +287,11 @@ export function centerScenarioDetails(specs, builtinNames) {
             name: spec.name,
             source: "center",
             builtin: builtinNames.includes(spec.name),
-            summary: "",
+            summary: "", // center spec 无 notes 字段(回落空串;registry 侧加 notes 后在此透传)
             toolset: spec.toolset,
             tools: spec.toolset === "repo-readonly" ? ["repo_tree", "repo_read_file", "repo_pull_diff", "Now"] : ["Now"],
+            // [1053] ScenarioEntry.prompt 已删(scenario 级提示词=center prompts binding 单入口)——center 条目
+            // 恒空串;字段本身保留(builtin 条目仍有真值,wire 形不变)。
             promptSummary: "",
             enabled: true,
         };
@@ -182,6 +313,12 @@ const TOOLSETS = {
     },
 };
 export const SCENARIO_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
+// ([1053] registry-core 0.10.15:SCENARIO_PROMPT_MAX 随 ScenarioEntry.prompt 一并退役)
+/**
+ * Build the center-declared scenario overlay. Invalid specs are SKIPPED with a warning (never fail
+ * boot — same posture as skills/teams); valid ones become scenarios keyed by name, ready to be merged
+ * OVER the built-ins (center wins). Returns the overlay plus which built-in names it shadows.
+ */
 export function centerScenarios(deps, specs, builtinNames, logger) {
     const overlay = {};
     const shadows = [];
@@ -197,6 +334,9 @@ export function centerScenarios(deps, specs, builtinNames, logger) {
             logger?.warn("sema_registry_scenario_invalid", { name: spec.name, reason: `unknown toolset "${String(spec.toolset)}" (have: ${Object.keys(TOOLSETS).join(", ")})` });
             continue;
         }
+        // [1053] registry-core 0.10.15:ScenarioEntry.prompt 直删(clay 亲裁)——center 场景的提示词通道收敛为
+        // center prompts binding(scenario 维,[1050]①a/[1051]③a);overlay 只组装工具面+技能面,提示词由投影腿
+        // (effective 声明数组→core stableBlocks,[1054]③ 已认领)在 binding 落地后统一承载。
         const name = spec.name;
         overlay[name] = (req) => ({
             tools: toolset.build(deps, req),
@@ -217,15 +357,25 @@ function codeReview(deps, req) {
     const repoTools = repoToolsFor(deps.repoClient, coords);
     const skills = skillsForScenario(deps.skills, "code-review");
     const objective = typeof req.objective === "string" ? req.objective : "Review this repository.";
+    // Tiering: `council: true` runs the multi-lens council (L1 parallel lenses + L3 arbiter) — for
+    // high-value/whole-repo review (~15× tokens). Default = the lead reviews the in-scope files DIRECTLY
+    // (cheap, reliable, finishes fast). A live run showed the model self-orchestrates unreliably, so for
+    // review (a KNOWN decomposition) the subagent fan-out is CODE-driven here, not left to the model
+    // (deterministic + cheaper + cacheable; see design/35). For OPEN-ENDED tasks where the decomposition
+    // isn't known, core's `createSubagentTool` (model-driven self-delegation, with maxDepth / isolated
+    // context / compressed-report guardrails) is the right tool — wire it in a dedicated scenario then.
     if (req.council === true) {
-        const rounds = clampRounds(req.rounds);
+        const rounds = clampRounds(req.rounds); // finite-guarded (NaN/±Inf → undefined → council default 1)
         return {
             tools: [
                 createCouncilTool(deps.subRunner, repoTools, objective, {
                     metrics: deps.metrics,
                     logger: deps.logger,
-                    debate: req.debate === true,
+                    debate: req.debate === true, // L1+L2+L3 (peer debate) vs L1+L3
+                    // OA cost/coverage dial: an optional structured lens COUNT (clamped to [1,6] + NaN-guarded in pickLenses;
+                    // absent = all 6 → zero regression). Per-request, no restart — orthogonal to the lens MODEL (startup env).
                     ...(typeof req.lenses === "number" ? { lensCount: req.lenses } : {}),
+                    // Caller-settable debate rounds (finite, clamped [1,3]; absent/NaN = default 1). Only when debate=true.
                     ...(rounds !== undefined ? { rounds } : {}),
                 }),
             ],
@@ -237,12 +387,24 @@ function codeReview(deps, req) {
 }
 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.";
+// Each provider supplies ONLY its stable base; `stablePrompt` enforces STABLE→VARIABLE ordering
+// (base, then userSystemPrompt, then per-user memoryBlock) so the prefix-cache discipline can't be
+// got wrong by hand (design/12, design/17).
+/** Default: the lead reads the in-scope files and reviews them directly. */
 const directReviewerPrompt = stablePrompt("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);
+/** Council mode: the lead just runs the (code-driven) council tool and returns its result verbatim. */
 const coordinatorPrompt = stablePrompt("You coordinate a code-review council. Call `run_council` exactly once (no arguments). When it " +
     "returns the arbitrated review, output that review as your final answer VERBATIM — do not " +
     "summarize, shorten, or rewrite it.");
+/**
+ * Personalization seam: merge the caller's own skills AFTER the scenario's, with
+ * SCENARIO-WINS on a name clash — the security baseline (scenario/center skills) can never be shadowed
+ * by user content. Duplicate names within the user list keep the first. Clashes are logged for audit
+ * (silent drops would make "my skill didn't fire" undebuggable). Input is already shape/size-validated
+ * by the HTTP layer (validateUserSkills); this stays pure merge policy.
+ */
 export function mergeUserSkills(scenarioSkills, userSkills, logger) {
     if (!userSkills || userSkills.length === 0)
         return scenarioSkills;
@@ -254,13 +416,24 @@ export function mergeUserSkills(scenarioSkills, userSkills, logger) {
             dropped.push(s.name);
             continue;
         }
-        reserved.add(s.name);
+        reserved.add(s.name); // also dedupes within the user list itself (first wins)
         out.push(s);
     }
     if (dropped.length > 0)
         logger?.warn("user_skills_dropped", { reason: "name reserved by scenario (or duplicate)", names: dropped });
     return out;
 }
+/**
+ * resolveSpec 的执法入口(指派为默认、body.scenario 可换但限 allowlist)。返回本请求的
+ * 生效场景名(未做 unknown→default 回退——那是 resolveSpec 既有职责,保持单点)。
+ *
+ *   - body.scenario 显式给出:allowlist 非空且集外 ⇒ typed 拒绝(400 `scenario_not_allowed`,附 allowlist
+ *     ——机器码归 wire、人话归壳/web);集内 ⇒ 用户主动切换赢。allowlist 为空(无 ruling / 该 principal
+ *     三层皆无指派 / caps 面故障)⇒ 无治理约束,现状放行(与「null 落兜底链」同一语义:分配面未覆盖 =
+ *     不收紧,恒不比没有治理时更宽;caps 故障不把用户锁死在 default——场景切换不是权限放大面,fail-open
+ *     到现状,与 workflows 面的 fail-closed 是刻意的 posture 差异,见 runtime-caps-resolver)。
+ *   - body.scenario 未给:ruling 胜者 ⇒ 指派为默认;无胜者 ⇒ defaultScenario 现状链。
+ */
 export function gateScenarioRequest(ruling, bodyScenario, defaultScenario) {
     if (typeof bodyScenario === "string") {
         const allowed = ruling?.allowlist ?? [];

package/dist/capabilities/select-environment-tool.d.ts

@@ -1,12 +1,17 @@
 import type { ToolSpec } from "@sema-agent/core";
 import { type SandboxImageResolver } from "../per-task-image.js";
 import type { ImageViewer, ImageIndexEntry, ImageListFilter } from "../plugins/store-contracts.js";
+/** The catalog slice the tool needs: fail-closed resolution + the viewer-scoped published listing. */
 export interface EnvironmentCatalog extends SandboxImageResolver {
     list(filter: ImageListFilter): Promise<{
         entries: ImageIndexEntry[];
         nextCursor: string | null;
     }>;
 }
+/** Session-keyed selected PROFILE (intent). Mirrors PerTaskImageRegistry's bounded-eviction shape, but holds
+ *  the profile string so every subsequent task re-resolves fail-closed (re-admit discipline). In-memory —
+ *  honest v1 boundary: a worker restart drops the selection (the model can re-select; nothing fails closed
+ *  the wrong way, the session just falls back to the worker default image). */
 export declare class SessionEnvironmentSelection {
     private readonly maxEntries;
     private readonly map;
@@ -17,6 +22,8 @@ export declare class SessionEnvironmentSelection {
 export declare function selectEnvironmentTool(deps: {
     catalog: EnvironmentCatalog;
     selection: SessionEnvironmentSelection;
+    /** Trusted viewer scope derived from the AUTH channel at spec-prep (never from tool args/ctx besides the
+     *  read-only ctx.principal the Runner threads) — built per-execute so operator/tenant scoping stays live. */
     viewerFor: (principal: string | undefined) => ImageViewer;
 }): ToolSpec;
 //# sourceMappingURL=select-environment-tool.d.ts.map