@sema-agent/server 1.323.0 → 2.0.1

package/dist/capabilities/sandbox-file-send.js

@@ -1,7 +1,27 @@
 import { hasDestroy } from "@sema-agent/core";
+/** Leak backstop (codex review HIGH): core skips destroy on suspend/review paths and a crash may skip it
+ *  entirely — the suspendVM wrap covers the common case, this bound covers the rest. Far above any real
+ *  per-replica concurrency. 修6: at the cap the registry REFUSES the new registration instead of FIFO-evicting
+ *  the oldest entry — every entry here is live-until-destroy/suspend by construction, so there is no
+ *  "terminal/stale" liveness verdict to evict on, and silently breaking an EXISTING live task's send face to
+ *  admit a new one inverts the harm (the old FIFO victim's SendUserFile would report "no sandbox attached"
+ *  while its env kept executing). The refused task gets a TYPED capacity error at send time instead. */
 export const TASK_ENV_REGISTRY_MAX = 512;
+/** Replica-local taskId → live ExecutionEnv(s). Registered by the factory wrap, dropped on destroy/suspend.
+ *
+ *  修5 (concurrent-generation guard): deployments WITHOUT a run-store single-active-session claim can race
+ *  two legs of one session through the factory concurrently — previously the second registration silently
+ *  OVERWROTE the first, so leg A's later SendUserFile resolved to leg B's env (wrong-generation read/upload).
+ *  The registry now keeps EVERY live env per key and `get()` fail-louds on ambiguity: neither leg can silently
+ *  read the other's sandbox, and the moment one generation is destroyed/suspended the survivor resolves again.
+ *  (Rejecting the second factory call outright was considered and discarded: a stale never-destroyed entry —
+ *  crash/no-destroy path — would then brick every future leg of that task, and the factory seam must not fail
+ *  env creation for a send-face bookkeeping conflict. Deployments WITH the single-active-session claim
+ *  serialize legs upstream and never see this state.) */
 export class TaskEnvRegistry {
     map = new Map();
+    /** 修6: taskIds whose registration was refused at the cap — lets get() report the TRUE reason (typed
+     *  capacity error, not a misleading "no sandbox attached"). Bounded by the same cap (marker-only). */
     refusedAtCapacity = new Set();
     liveCount() {
         let n = 0;
@@ -9,6 +29,9 @@ export class TaskEnvRegistry {
             n += envs.length;
         return n;
     }
+    /** Resolve the ONE live env for a task. Throws typed errors on the two governed failure states:
+     *  ambiguity (修5 — concurrent generations both live) and capacity refusal (修6). Returns undefined when
+     *  the task simply has no registered env (caller reports "no sandbox attached"). */
     get(taskId) {
         if (taskId === undefined)
             return undefined;
@@ -23,14 +46,26 @@ export class TaskEnvRegistry {
         }
         return undefined;
     }
+    /** Wrap the deployment's own factory: register each minted env under the task's CANONICAL id — core hands
+     *  the factory the raw `spec.taskId` but gives tools `hostTaskId = spec.taskId ?? sessionId` (prepare-task
+     *  262/320/428; the sync `/v1/tasks` leg deliberately sets no spec.taskId), so the registry key MUST apply
+     *  the same fallback or every sync-leg lookup misses (codex review HIGH). Unregister when core calls
+     *  destroy() (identity guard: only the env's OWN entry is dropped — a replacement env for a reused key must
+     *  not be evicted by the old one's late destroy). core SKIPS destroy on durable suspend/review (runtask
+     *  keeps the env for the snapshot) — wrap suspendVM the same way so a suspended task doesn't pin its env
+     *  here forever; the bounded-size backstop covers any remaining no-destroy crash path. */
     wrapFactory(factory) {
         return async (ctx) => {
             const env = await factory(ctx);
             const taskId = ctx.taskId ?? ctx.sessionId;
             if (hasDestroy(env)) {
                 const existing = this.map.get(taskId);
+                // 修6: refuse NEW keys at the cap (never evict a live entry — see TASK_ENV_REGISTRY_MAX). A same-key
+                // additional registration is always admitted even at the cap: the 修5 ambiguity guard is a correctness
+                // fence and must not be dodgeable by arriving while the registry is full.
                 if (existing === undefined && this.liveCount() >= TASK_ENV_REGISTRY_MAX) {
                     if (this.refusedAtCapacity.size >= TASK_ENV_REGISTRY_MAX) {
+                        // marker set is itself bounded; beyond it the task degrades to the plain "no sandbox attached" report
                         const oldestMarker = this.refusedAtCapacity.values().next().value;
                         if (oldestMarker !== undefined)
                             this.refusedAtCapacity.delete(oldestMarker);
@@ -42,8 +77,10 @@ export class TaskEnvRegistry {
                         clearMarker();
                         return origDestroy();
                     };
-                    return env;
+                    return env; // env itself is untouched — only the send face is refused (typed error at get())
                 }
+                // 修5: append, never overwrite — a live sibling under the same key makes get() fail loud instead of
+                // silently handing one leg the other leg's sandbox.
                 if (existing === undefined)
                     this.map.set(taskId, [env]);
                 else
@@ -52,7 +89,7 @@ export class TaskEnvRegistry {
                     const envs = this.map.get(taskId);
                     if (envs === undefined)
                         return;
-                    const i = envs.indexOf(env);
+                    const i = envs.indexOf(env); // identity guard: drop only THIS env's entry
                     if (i >= 0)
                         envs.splice(i, 1);
                     if (envs.length === 0)
@@ -69,7 +106,7 @@ export class TaskEnvRegistry {
                     suspendable.suspendVM = async (...args) => {
                         const r = await origSuspend(...args);
                         if (r.ok)
-                            evict();
+                            evict(); // suspended env is dormant — the resume leg registers a fresh one
                         return r;
                     };
                 }
@@ -78,6 +115,22 @@ export class TaskEnvRegistry {
         };
     }
 }
+/**
+ * Which REMOTE_EXEC lanes may register the sandbox-send TaskEnvRegistry (and thus mount the sandbox-lane
+ * SendUserFile source), under which tenancy gate. The judgment per lane (2026-07-14 ssh backfill review):
+ *
+ *  - e2b / k8s: one task = one disposable sandbox; the sandbox filesystem IS the tenant's task workspace,
+ *    so a sandbox-scoped read is tenant-scoped by construction → open to any tenant.
+ *  - ssh: the peer is ONE persistent real machine SHARED across tasks (factory ignores ctx: every task
+ *    gets the same host+mountPath; destroy=disconnect only, files persist). Tenant A's task can read the
+ *    residue of tenant B's task → the isolation premise FAILS. Multi-tenant here would be an
+ *    arbitrary-host-path-read → public-URL exfil face, so the lane opens ONLY single-user
+ *    (`requirePrincipal !== true`), the exact gate the host lane uses. NOT a lane to "fix later with a
+ *    per-task workspace": tasks legitimately operate outside any workspace on a real host (design/61 —
+ *    batch deployment), so per-task dirs would not restore the boundary anyway.
+ *  - adb / local-docker / host / unset: no registry (host+unset use the local-fs source in main.ts;
+ *    adb/local-docker remain a follow-on).
+ */
 export function sandboxSendLaneEnabled(provider, requirePrincipal) {
     if (provider === "e2b" || provider === "k8s")
         return true;
@@ -85,9 +138,13 @@ export function sandboxSendLaneEnabled(provider, requirePrincipal) {
         return requirePrincipal !== true;
     return false;
 }
+/** Single-quote a path for POSIX sh (the only metacharacter inside '' is ' itself). */
 export function shq(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
+/** Strip the capability URL (and any SigV4 signature) from text before it reaches an error/log — including
+ *  the percent-encoded forms an adapter may echo (the k8s exec transport carries the command in a request
+ *  URI, so an error can quote the URL re-encoded; codex review MED). */
 export function redactPutUrl(text, url) {
     return text
         .split(url)
@@ -95,25 +152,45 @@ export function redactPutUrl(text, url) {
         .split(encodeURIComponent(url))
         .join("<presigned-put-url>")
         .replace(/X-Amz-Signature(=|%3D)[0-9a-f]+/gi, "X-Amz-Signature=<redacted>")
+        // A PARTIAL URL (adapter truncation/line-wrap) can survive the exact-match passes above — the SigV4
+        // Credential query param carries the ACCESS KEY ID, scrub it independently (defense in depth).
         .replace(/X-Amz-Credential(=|%3D)[^&\s"']+/gi, "X-Amz-Credential=<redacted>");
 }
+/**
+ * The sandbox-lane `send` seam for the SendUserFile tool: in-sandbox stat (existence + regular file +
+ * size cap, BEFORE any signing) → presign PUT → in-sandbox `curl -T` → finalize the user-facing link.
+ * Throws typed Errors (redacted) — the tool reports them per file.
+ */
 export function createSandboxFileSend(deps) {
     return async (path, ctx) => {
         const env = deps.registry.get(ctx.taskId);
         if (!env) {
             throw new Error("no sandbox is attached to this task yet — SendUserFile reads from the task sandbox; retry after the environment has started");
         }
+        // The path is model-controlled and rides a shell line: shq() covers every POSIX metacharacter, but
+        // control chars (NUL truncates argv in some transports; \n splits lines in naive adapters) buy nothing
+        // legitimate — reject outright rather than trust each adapter's quoting edge.
         if (/[\u0000-\u001f\u007f]/.test(path))
             throw new Error("file path contains control characters — not a valid sandbox path");
         if (path.length > 4096)
             throw new Error("file path exceeds 4096 characters — not a valid sandbox path");
+        // `curl -T -` means STDIN by convention — a relative path starting with '-' must ride as ./-name so all
+        // three sites (test operand / stat / curl) name the same real file.
         const q = shq(path.startsWith("-") ? `./${path}` : path);
+        // stat first: fail before minting any capability URL. `test -f` = regular file only (no dirs/devices);
+        // `stat -c %s` = GNU/busybox size (sandbox images are Linux; the ssh lane assumes a LINUX peer — the
+        // whole fleet is — a macOS peer would exit non-zero here and fail loud, see the module header).
+        // ExecutionEnv.exec timeout is SECONDS (e2b, k8s AND ssh adapters all multiply by 1000 — codex
+        // review MED caught ms here; ssh reading = remote-env-ssh.ts `options.timeout * 1000`).
         const stat = await env.exec(`test -f ${q} && stat -c %s -- ${q}`, { timeout: 30 });
         if (!stat.ok)
             throw new Error(`sandbox stat failed: ${stat.error.message}`);
         if (stat.value.exitCode !== 0) {
             throw new Error(`file not found in the sandbox (or not a regular file): ${path} — ls first; absolute paths are safest`);
         }
+        // Advisory pre-check only (the authoritative size accounting is server-side verifySize below — the
+        // sandbox owns its filesystem, so nothing it reports is binding): still worth failing early and cheap.
+        // Strict digit match, not bare parseInt — a digit-prefixed garbled line must fail loud, not truncate.
         const statOut = stat.value.stdout.trim();
         if (!/^\d+$/.test(statOut))
             throw new Error(`sandbox stat returned an unparsable size for ${path}: ${statOut}`);
@@ -123,7 +200,15 @@ export function createSandboxFileSend(deps) {
         }
         const filename = path.split(/[/\\]/).pop();
         const prepared = deps.prepare(filename, ctx.principal);
+        // Everything from here can echo the capability URL (adapter throws included, not just Result errors —
+        // codex review MED) — one redacting fence around the whole upload phase.
         try {
+            // -f: HTTP >= 400 → exit 22 (no silent half-uploads). NO -s: the progress meter on stderr feeds the
+            // e2b/k8s adapters' ~120s zero-output liveness watchdog — a silent multi-minute upload would be killed
+            // as a hang (the k8s snapshot lane solves this with livenessMs:0; a chatty meter is the seam-free way).
+            // The ssh adapter has NO idle-output watchdog on exec() (total-timeout bound only) — the meter is
+            // harmless noise there, so one shared command shape serves all three lanes.
+            // stderr may echo the URL → the redact fence below covers every throw out of this block.
             const up = await env.exec(`curl -f -T ${q} ${shq(prepared.putUrl)}`, { timeout: 300 });
             if (!up.ok)
                 throw new Error(`sandbox upload failed: ${up.error.message}`);
@@ -133,6 +218,9 @@ export function createSandboxFileSend(deps) {
                     throw new Error("sandbox upload failed: curl is not available in this sandbox image");
                 throw new Error(`sandbox upload failed (curl exit ${up.value.exitCode})${detail.length > 0 ? `: ${detail}` : ""}`);
             }
+            // Server-side accounting is authoritative (codex review HIGH: stat→curl is an exploitable TOCTOU —
+            // swap/grow the file between the two and the cap is bypassed with a stale size on the card): HEAD the
+            // real object; over-cap ⇒ deleted inside verifySize; the card carries the verified size.
             const verifiedSize = await prepared.verifySize(deps.maxBytes);
             return prepared.finalize(verifiedSize);
         }

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