@sema-agent/server 1.323.0 → 2.0.1

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

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

@@ -1,5 +1,31 @@
+/**
+ * RFC A2 (docs/design/ENV-SELECT-AND-REGION-SOURCE.md) — the model-facing `SelectEnvironment` tool.
+ * A 切片先行;挂载路线 = RFC 判定②(a):deployment 经 `spec.tools` 注入(同 lsp/
+ * 自定义工具),core 收编等真用起来再谈。
+ *
+ * Backend = the EXISTING trusted admission chain, nothing new:
+ *  - discovery: `ImageIndex.list({latestOnly, status:'published', viewer})` — the SAME per-principal
+ *    visibility the `/v1/images/select` catalog applies (SQL-baked, never caller enumeration).
+ *  - selection: `resolveSandboxImageRef` (fail-closed profile→digest re-admission).
+ *  - binding: a session-keyed PROFILE (intent — never a digest) the next task's resolveSpec re-resolves
+ *    FAIL-CLOSED, exactly like a body-supplied `sandboxImageProfile`. Storing the profile (not the ref)
+ *    keeps the re-admit discipline intact: every task re-resolves LIVE, a stale digest can never ride a
+ *    session binding past admission.
+ *
+ * Boundary contract (verbatim in the tool's model-facing note): a binding change takes
+ * effect ONLY at a task boundary; any child (including design/129 session-scoped background children)
+ * inherits the binding at its spawn moment and never drifts mid-flight. This tool therefore only writes
+ * the session-profile store — the RUNNING task's sandbox is untouched.
+ *
+ * 409-style self-correction: a failed selection returns `missing` + the viewer-visible catalog
+ * (tenant-neutral profile names only — the list enters model context).
+ */
 import { Type } from "typebox";
 import { resolveSandboxImageRef } from "../per-task-image.js";
+/** 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 class SessionEnvironmentSelection {
     maxEntries;
     map = new Map();
@@ -24,6 +50,7 @@ const capList = (caps) => Object.entries(caps ?? {})
     .map(([k]) => k);
 async function availableProfiles(catalog, viewer) {
     const { entries } = await catalog.list({ ...viewer, status: "published", latestOnly: true, limit: 100 });
+    // tenant-neutral: profile name + boolean capability keys only (this list enters model context).
     return entries.map((e) => ({ profile: e.profile, capabilities: capList(e.capabilities) }));
 }
 export function selectEnvironmentTool(deps) {
@@ -35,6 +62,7 @@ export function selectEnvironmentTool(deps) {
             "The change takes effect for the NEXT task/subagent — the current sandbox is not swapped mid-run; " +
             "running work keeps the environment it started with, and artifacts hand over via the workspace/git. " +
             "Use this instead of hand-installing SDK-level toolchains (Android SDK, JVM, browsers, …).",
+        // set-to-value on a session-keyed map: repeat-safe with the same args.
         effect: "idempotent",
         parameters: Type.Object({
             profile: Type.Optional(Type.String({ description: "Target image profile name (from the available list). Omit to discover." })),
@@ -59,6 +87,7 @@ export function selectEnvironmentTool(deps) {
                 index: deps.catalog,
             });
             if (!resolved.ok) {
+                // self-correction payload: the error + the viewer's own catalog. Model retries with a valid one.
                 const available = await availableProfiles(deps.catalog, viewer);
                 return {
                     content: JSON.stringify({ error: resolved.message, ...(caps.length > 0 ? { missing: caps } : {}), available }),
@@ -66,6 +95,7 @@ export function selectEnvironmentTool(deps) {
                 };
             }
             if (!sessionId) {
+                // outside a Runner session there is nothing to bind to — honest failure, not a silent success.
                 return { content: JSON.stringify({ error: "no session to bind the environment selection to" }), details: { mode: "select-failed" } };
             }
             deps.selection.set(sessionId, a.profile);

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

@@ -1,10 +1,12 @@
 import type { SubagentSpawnContext, ToolSpec } from "@sema-agent/core";
 import type { IssuedFileLink } from "../plugins/send-user-file.js";
+/** The frame the web/shell renders as a file card. Rides the durable events tail (replayable). */
 export interface FileLinkFrame {
     type: "file_link";
     url: string;
     filename: string;
     size: number;
+    /** 0 = permanent (public track). */
     ttlSec: number;
     status: "normal" | "proactive";
     caption?: string;
@@ -14,15 +16,25 @@ export interface SendUserFileRunContext {
     taskId: string;
     emit: (frame: FileLinkFrame) => Promise<void>;
 }
+/** Per-run ALS carrier (QuestionCoordinator pattern): run legs wrap their body via runWithContext; the tool
+ *  recovers the ambient emit at execute time. No pending state, no respond face — emission is one-way. */
 export declare class SendUserFileEmitter {
     private readonly als;
     runWithContext<T>(ctx: SendUserFileRunContext, fn: () => Promise<T>): Promise<T>;
+    /** Emit into the ambient run's events tail. Returns false when no run context is ambient (a leg not wrapped —
+     *  the caller reports "sent but not surfaced live" honestly rather than pretending). */
     emit(frame: FileLinkFrame): Promise<boolean>;
 }
+/** Per-call caps (bounded model-facing surface; the issuer has its own ttl/name guards). */
 export declare const SEND_USER_FILE_MAX_FILES = 10;
 export declare const SEND_USER_FILE_MAX_BYTES: number;
 export declare const SEND_USER_FILE_MAX_CAPTION = 500;
 export declare function sendUserFileTool(deps: {
+    /** Lane-scoped send: read/stat the file where the lane lives, upload, mint the user-facing link.
+     *  Enforces the size cap itself (host: fs stat; sandbox: in-sandbox stat BEFORE presigning). Throws
+     *  typed Errors (not-found / too-large / no-sandbox) — surfaced verbatim per file in the tool result.
+     *  `principal` = core's VERIFIED ToolExecuteContext.principal — the multi-tenant SCOPE the issuer keys the
+     *  hashed key segment on and the ledger records (absent on single-user lanes → the "_" sentinel). */
     send: (path: string, ctx: {
         taskId?: string;
         sessionId?: string;
@@ -31,8 +43,29 @@ export declare function sendUserFileTool(deps: {
     emitter: SendUserFileEmitter;
 }): ToolSpec;
 export declare const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
+/**
+ * Build the `SubagentToolOptions.extraTools` factory that injects SendUserFile into delegated-child rosters —
+ * WITH the two gates the bare `() => [spec]` wiring lacked:
+ *
+ * F1 (HIGH, codex): the subRunner carries NO tool policy and core's child spec does not inherit the parent's
+ * `toolPolicy`, so an extraTools-injected SendUserFile BYPASSED the deployment approval gate (evidence: with
+ * `APPROVAL_DENY=SendUserFile` the top-level call is denied but a delegated child could still call it). Until
+ * core lands a child-policy propagation seam, the CONSERVATIVE server-side stopgap is a deployment-policy
+ * PRE-CHECK: if the deployment's approval face gates SendUserFile at all (deny OR ask — approvalDeny /
+ * approvalRequire / approvalNeverAuto, matched in canonical space exactly like src/approval.ts), the factory
+ * injects NOTHING. deny obviously must not reach children; ask-gated is ALSO withheld because the child leg has
+ * no policy to route the ask (injecting would silently auto-allow — the exact bypass). The gate is read LIVE per
+ * spawn (a getter, not a boot snapshot) so center/env hot-applied governance is honored, mirroring how the
+ * per-request approval baseline reads live config. A deployment with no gate intent is unchanged.
+ *
+ * F2 (MED, codex): read-only builtin agents (Explore/Plan) must NOT get SendUserFile — a read-only agent that
+ * can read sensitive files AND mint public links off them breaks the read-only posture (their denyTools sets
+ * predate this tool, so core's resolveToolSubset would let it through). `ctx.agentType` carries the spawned
+ * definition's name (core subagent.js); membership in core's builtin catalog ⇒ inject nothing for that spawn.
+ */
 export declare function subagentSendUserFileExtraTools(deps: {
     spec: ToolSpec;
+    /** LIVE deployment approval face (config.approvalDeny/approvalRequire/approvalNeverAuto) — evaluated per spawn. */
     approvalGate: () => {
         deny?: string[];
         require?: string[];

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

@@ -1,11 +1,39 @@
+/**
+ * SendUserFile — the tool face (slice 2 of the dual-track public-link lane; the issuer core is
+ * src/plugins/send-user-file.ts, shipped in 1.186.0).
+ *
+ * TOOL CONTRACT = the real CC-web schema (operator-provided verbatim, 2026-07-14 — CC-parity discipline):
+ *   files: string[]        (required — paths, absolute or relative to the task cwd; ONE file still rides an array)
+ *   status: "normal" | "proactive"  (required — proactive = pushed while the user is away; normal = replying)
+ *   caption?: string       (one-line context, e.g. "the failing line is 42")
+ *   display?: "render" | "attach"   (render = inline in the side panel; attach = download card; omitted = by type)
+ * Returns DELIVERY metadata only — never the file content, and (deliberately) not the URL either: the link is
+ * a capability secret for the USER's pane; echoing it into model context invites mis-transcription + leakage.
+ *
+ * Delivery = a `file_link` frame on the run's durable events tail (same posture as `question`/`suggestions`:
+ * the shell/web renders it; it is NEVER re-fed to a model). Emission recovers the per-run emit sink via
+ * AsyncLocalStorage, the exact QuestionCoordinator/ElicitationCoordinator pattern — sub-tasks inherit the
+ * top-level run's frame.
+ *
+ * File source: the injected `send` seam — one path string in, an issued link out. Two lane shapes (v2,
+ * clay ruling 2026-07-14): HOST lane reads the local disk and uploads server-side (single-user only —
+ * host-lane multi-tenant is permanently closed); SANDBOX lanes (e2b/k8s) stat + `curl -T` INSIDE the
+ * sandbox against a server-presigned single-object PUT (bytes never relay through the server, creds never
+ * enter the sandbox; the sandbox's own filesystem IS the tenant boundary, so any tenant may use it).
+ * Lanes without a wired send face simply don't get the tool (honest seam, no fake-live).
+ */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { Type } from "typebox";
 import { builtinAgentDefinitions, canonicalToolName } from "@sema-agent/core";
+/** Per-run ALS carrier (QuestionCoordinator pattern): run legs wrap their body via runWithContext; the tool
+ *  recovers the ambient emit at execute time. No pending state, no respond face — emission is one-way. */
 export class SendUserFileEmitter {
     als = new AsyncLocalStorage();
     runWithContext(ctx, fn) {
         return this.als.run(ctx, fn);
     }
+    /** Emit into the ambient run's events tail. Returns false when no run context is ambient (a leg not wrapped —
+     *  the caller reports "sent but not surfaced live" honestly rather than pretending). */
     async emit(frame) {
         const ctx = this.als.getStore();
         if (!ctx)
@@ -14,8 +42,9 @@ export class SendUserFileEmitter {
         return true;
     }
 }
+/** Per-call caps (bounded model-facing surface; the issuer has its own ttl/name guards). */
 export const SEND_USER_FILE_MAX_FILES = 10;
-export const SEND_USER_FILE_MAX_BYTES = 100 * 1024 * 1024;
+export const SEND_USER_FILE_MAX_BYTES = 100 * 1024 * 1024; // 100 MiB per file — issuer PUT is a single upload
 export const SEND_USER_FILE_MAX_CAPTION = 500;
 export function sendUserFileTool(deps) {
     return {
@@ -59,6 +88,7 @@ export function sendUserFileTool(deps) {
             const sendCtx = {
                 ...(ctx.taskId !== undefined ? { taskId: ctx.taskId } : {}),
                 ...(ctx.sessionId !== undefined ? { sessionId: ctx.sessionId } : {}),
+                // scope passthrough (multi-tenant governance): core's VERIFIED principal — never a model-supplied value.
                 ...(ctx.principal !== undefined ? { principal: ctx.principal } : {}),
             };
             for (const path of a.files) {
@@ -77,10 +107,17 @@ export function sendUserFileTool(deps) {
                     sent.push({ filename: link.filename, size: link.size, surfacedLive });
                 }
                 catch (e) {
+                    // 修4 defense-in-depth: per-file errors are spliced VERBATIM into the model-visible result below —
+                    // the send chain already redacts its own capability URLs (redactPutUrl) and the ledger throws
+                    // coordinate-free incident codes, but any URL that still survives an unforeseen path (adapter echo,
+                    // store error body) must not reach model context, where the public endpoint transparency in
+                    // capabilities would make it a reconstructable permanent link. Scrub generically; the useful typed
+                    // errors (not-found / cap / no-sandbox) carry no URLs and pass through untouched.
                     const raw = e instanceof Error ? e.message : String(e);
                     failed.push({ file: path, error: raw.replace(/https?:\/\/\S+/gi, "<url>") });
                 }
             }
+            // Delivery metadata ONLY (CC contract) — no URL, no content, into model context.
             const summary = `sent ${sent.length}/${a.files.length} file(s)` +
                 (failed.length > 0 ? `; FAILED: ${failed.map((f) => `${f.file} (${f.error})`).join("; ")}` : "");
             return {
@@ -91,13 +128,40 @@ export function sendUserFileTool(deps) {
         },
     };
 }
+// ── subagent extraTools gate(codex F1/F2,core 1.287 seam 的 server 半场守门)────────────────────────
 export const SEND_USER_FILE_TOOL_NAME = "SendUserFile";
+/** core's read-only builtin agents (Explore/Plan) — derived from core's OWN builtinAgentDefinitions so the set
+ *  cannot drift when core adds/renames a read-only builtin. Every entry of that catalog is a read-only agent by
+ *  contract (their systemPrompts forbid ALL writes and their denyTools strip the write tools). */
 const READONLY_BUILTIN_AGENT_TYPES = new Set(builtinAgentDefinitions().map((d) => d.name));
+/**
+ * Build the `SubagentToolOptions.extraTools` factory that injects SendUserFile into delegated-child rosters —
+ * WITH the two gates the bare `() => [spec]` wiring lacked:
+ *
+ * F1 (HIGH, codex): the subRunner carries NO tool policy and core's child spec does not inherit the parent's
+ * `toolPolicy`, so an extraTools-injected SendUserFile BYPASSED the deployment approval gate (evidence: with
+ * `APPROVAL_DENY=SendUserFile` the top-level call is denied but a delegated child could still call it). Until
+ * core lands a child-policy propagation seam, the CONSERVATIVE server-side stopgap is a deployment-policy
+ * PRE-CHECK: if the deployment's approval face gates SendUserFile at all (deny OR ask — approvalDeny /
+ * approvalRequire / approvalNeverAuto, matched in canonical space exactly like src/approval.ts), the factory
+ * injects NOTHING. deny obviously must not reach children; ask-gated is ALSO withheld because the child leg has
+ * no policy to route the ask (injecting would silently auto-allow — the exact bypass). The gate is read LIVE per
+ * spawn (a getter, not a boot snapshot) so center/env hot-applied governance is honored, mirroring how the
+ * per-request approval baseline reads live config. A deployment with no gate intent is unchanged.
+ *
+ * F2 (MED, codex): read-only builtin agents (Explore/Plan) must NOT get SendUserFile — a read-only agent that
+ * can read sensitive files AND mint public links off them breaks the read-only posture (their denyTools sets
+ * predate this tool, so core's resolveToolSubset would let it through). `ctx.agentType` carries the spawned
+ * definition's name (core subagent.js); membership in core's builtin catalog ⇒ inject nothing for that spawn.
+ */
 export function subagentSendUserFileExtraTools(deps) {
     const canonical = canonicalToolName(SEND_USER_FILE_TOOL_NAME);
     return (ctx) => {
+        // F2: read-only builtin child (Explore/Plan) — never inject.
         if (ctx.agentType !== undefined && READONLY_BUILTIN_AGENT_TYPES.has(ctx.agentType))
             return [];
+        // F1: deployment policy gates SendUserFile (deny/ask) — withhold from ALL children (fail-closed stopgap
+        // until core propagates the parent toolPolicy into child specs). Canonical-space match (S8 discipline).
         const gate = deps.approvalGate();
         const gated = [...(gate.deny ?? []), ...(gate.require ?? []), ...(gate.neverAuto ?? [])].some((t) => canonicalToolName(t) === canonical);
         return gated ? [] : [deps.spec];