@sema-agent/server 7.43.0 → 7.44.0

package/dist/degenerate-instrument.js

@@ -1,54 +1,10 @@
-/**
- * Degenerate-repetition instrument (a/b classifier).
- *
- * When a task fails with `errorCode === "output.degenerate"` (core 1.59), core hands back
- * `salvagedOutput` = the degenerate turn's text — **already tail-TRIMMED at the brain stream layer**.
- * 🔴 A-057.52 correction (this note used to claim "the **whole** text, good head + looped garbage tail";
- * that was true of core 1.59 and false of every engine that ships `trimDegenerateTail` — verified against
- * the installed dist, not against JSDoc): on the main path `assemble-result` fills the seat from the same
- * final message the brain already trimmed, so what arrives here is `head + exactly ONE copy of the
- * repeating unit` (unit ≤ `MAX_PERIOD` = 100 chars). Untrimmed text only reaches us on the narrow
- * fallbacks — the cut landed on the reasoning face, or `trimDegenerateTail` bailed (`reps < 2`, empty
- * unit, unit-loop period mismatch). Consequence for the numbers below: {@link repetitionTail} is a
- * **no-op** on the main-path input (one copy is not ≥ {@link MIN_REPEATS}), so `uniquePrefixLen`
- * collapses onto `salvagedLen` and the a/unknown split degrades to a pure length test. The a-vs-b
- * decision is unaffected (it is decided by `priorChars`, independently); the residual bias on a/unknown
- * is bounded by one unit ≤ 100 chars. Pin: the "已裁形" case in `test/degenerate-instrument.test.ts`
- * drives the REAL `inspectDegenerate` + `trimDegenerateTail` and asserts the tail measures 0.
- * Core's *salvage ②* — recovering the "last substantive turn" instead of the current one — is being
- * gated on REAL data: how often is the useful answer actually in an EARLIER turn vs. in the degenerate
- * turn itself? This instrument answers that, per event, without changing any behaviour.
- *
- * Classification (since the last user message = this task's own turns):
- *  - **a** good+garbage SAME turn — the degenerate turn carries a substantive unique head before the
- *    loop. Whole-turn salvage ① + a tail-trim is enough; ② would add nothing.
- *  - **b** good EARLIER / degenerate LATER — a substantive assistant turn already exists before the
- *    degenerate one. ② ("last-substantive-turn") would recover it; ① (current turn) throws it away.
- *  - **unknown** — degenerate from the start, nothing substantive anywhere (neither ① nor ② helps).
- *
- * Output is measurement only: a `degenerate_total{class}` counter (→ `/metrics/summary`) plus one
- * structured log line carrying the raw signals. The aggregate a/b/unknown frequencies are what gets
- * reported back to the core AI to decide whether ② is worth building. The repetition-boundary estimate
- * here is for *measuring* the unique head — it is NOT the production tail-trim (that lives in core).
- */
-// 🔴 core 1.403 迁移(2026-07-25):runtime 构造用法,`Session` → `StoredSession`(见 audit.ts 同款注释)。
 import { StoredSession } from "@sema-agent/core";
 import { TiDBSessionStorage } from "./plugins/tidb-session-storage.js";
-/** A "real" answer is at least this many non-looping chars (after the degenerate tail is stripped). */
 const SUBSTANTIVE_CHARS = 200;
-/** Loops live at the end — only inspect this much of the tail when hunting the repeating unit. */
 const REP_WINDOW = 8192;
-/** Need at least this many contiguous copies to call a periodic suffix a degenerate loop. */
 const MIN_REPEATS = 3;
-/** Longest repeating unit we look for (a sentence-ish block); bounds the scan. */
 const MAX_UNIT = 256;
-/** Two assistant turns are "the same turn" if their heads match (a degenerate head is distinctive). */
 const TURN_MATCH_HEAD = 120;
-/**
- * Length of the longest periodic suffix of `text` (≥ {@link MIN_REPEATS} contiguous copies of some
- * unit ≤ {@link MAX_UNIT}). 0 when no qualifying loop is found. Bounded to the last {@link REP_WINDOW}
- * chars. This estimates where the degenerate repetition begins — a measurement aid, not a trimmer.
- */
 export function repetitionTail(text) {
     const n = text.length;
     if (n < 2)
@@ -57,7 +13,6 @@ export function repetitionTail(text) {
     const maxUnit = Math.min(MAX_UNIT, Math.floor((n - start) / MIN_REPEATS));
     let best = 0;
     for (let p = 1; p <= maxUnit; p++) {
-        // How many times does the final p-char block repeat contiguously, walking backwards?
         let reps = 1;
         for (;;) {
             const blockStart = n - p * (reps + 1);
@@ -79,26 +34,20 @@ export function repetitionTail(text) {
     }
     return best;
 }
-/** Substantive (non-looping) length of one assistant turn's text. */
 function substantiveLen(text) {
     return Math.max(0, text.length - repetitionTail(text));
 }
-/**
- * Classify a degenerate failure from its salvaged text + the substantive content of the assistant
- * turns that preceded it (since the last user message). Pure — unit-tested directly.
- */
 export function classifyDegenerate(salvaged, priorChars, turnsSinceUser) {
     const salvagedLen = salvaged.length;
     const repeatedTailLen = repetitionTail(salvaged);
     const uniquePrefixLen = Math.max(0, salvagedLen - repeatedTailLen);
     const cls = priorChars >= SUBSTANTIVE_CHARS
-        ? "b" // a substantive answer already existed in an earlier turn → ② would recover it
+        ? "b"
         : uniquePrefixLen >= SUBSTANTIVE_CHARS
-            ? "a" // the degenerate turn itself carries the answer before looping → ① + tail-trim suffices
-            : "unknown"; // degenerate from the start, nothing substantive anywhere
+            ? "a"
+            : "unknown";
     return { class: cls, turnsSinceUser, priorChars, salvagedLen, uniquePrefixLen, repeatedTailLen };
 }
-/** Concatenated text-block content of one (assistant) message; "" for a tool-call-only turn. */
 function turnText(msg) {
     if (msg.role !== "assistant" || !Array.isArray(msg.content))
         return "";
@@ -107,7 +56,6 @@ function turnText(msg) {
         .map((b) => b.text)
         .join("");
 }
-/** Heads match → treat as the same turn (core may or may not persist the failed degenerate turn). */
 function sameTurn(a, b) {
     if (!a || !b)
         return false;
@@ -116,12 +64,6 @@ function sameTurn(a, b) {
     const k = Math.min(TURN_MATCH_HEAD, a.length, b.length);
     return k > 0 && a.slice(0, k) === b.slice(0, k);
 }
-/**
- * Read this task's assistant turns (since the last user message) and total the substantive text that
- * preceded the degenerate turn. The degenerate turn is located by head-matching `salvaged`; if it was
- * not persisted, every persisted assistant turn in the window counts as prior (and the degenerate turn
- * is added to the count). Best-effort — returns zeros if the session can't be read.
- */
 async function readPriorTurns(pool, sessionId, salvaged) {
     const storage = await TiDBSessionStorage.wake(pool, sessionId);
     if (!storage)
@@ -148,15 +90,9 @@ async function readPriorTurns(pool, sessionId, salvaged) {
     }
     const priorTexts = degenIdx >= 0 ? assistantTexts.slice(0, degenIdx) : assistantTexts;
     const priorChars = priorTexts.reduce((a, t) => a + substantiveLen(t), 0);
-    // turnsSinceUser counts the degenerate turn too; add 1 when it wasn't found among persisted turns.
     const turnsSinceUser = degenIdx >= 0 ? assistantTexts.length : assistantTexts.length + 1;
     return { priorChars, turnsSinceUser };
 }
-/**
- * Build the fire-and-forget instrument. Returns a sync `(result) => void` so the hot result paths
- * (`recordTaskResult` / `recordDone`) stay unblocked; the session read + classification run in the
- * background and never throw into the response. No-op for non-degenerate results.
- */
 export function makeDegenerateInstrument(pool, metrics, logger) {
     return (result) => {
         if (result.errorCode !== "output.degenerate")

package/dist/deployment-governance.js

@@ -1,38 +1,6 @@
-/**
- * design/181 件一:**部署治理链的单一构造口**。
- *
- * 三条腿要装同一条「部署 ⊇ 操作员」治理链 —— HTTP 的 `resolveSpec`(boot/resolve-spec.ts)、durable park
- * 的赎回腿(main.ts 的父约束重建)、`run-local`。此前只有第一条腿真装,另外两条各自手拼一小截,于是
- * 「同一个部署旋钮在这条腿上生效、在那条腿上不存在」成了结构性可能。本文件把**构造**收成单一属主。
- *
- * 🔒 **折叠属主不在这里**:合成仍是 core 的 `tightenTaskSpec`,经由既有的 `applyRuntimeGovernance`
- * (src/runtime-governance.ts)。本口**只产入参与基线**,一条 policy 都不合成 —— 折叠有六条规则
- * (excludeTools/deferTools 并集、handsReadOnly/shellGate 放松即 throw、onAsk/hooks 冲突、键存在性
- * profile),且 `applyRuntimeGovernance` 的 shellGate delete 臂读的是 `base.shellGate`、`governanceForced`
- * 观察器包在其内部 —— 一个 base-free 的「已折好」新口复现不了这些,照抄=在 server 侧重写 core 的折叠。
- *
- * ⚠️ **禁 memoize**:`autonomy` / `commandPolicy` / `manualModeShellGate` / `sensitiveWritePatterns` 都是
- * 热改字段(registry 热应用换 config 引用,resume 腿按**当前** config 重折 —— 与审批基线读活
- * `config.approvalRequire` 同一姿势)。每次调用现取,boot 期缓存一份 = 把热改静默冻住。
- */
 import { posix } from "node:path";
 import { FileError, StubExecutionEnv, combinePolicies, createAllowDenyPolicy, createDurableQuestionPolicy, createSensitivePathPolicy, err, ok, } from "@sema-agent/core";
 import { createDurableAskPolicy } from "./approval.js";
-/**
- * #152([2703] 案二):durable 部署上的 AskUserQuestion 门。活体面(QuestionCoordinator)缺席 ⇒ 原形
- * `createDurableQuestionPolicy()`(恒 ask ⇒ 恒 durable park)。在场 ⇒ **判决时**按活流上下文分腿:
- * 活流腿(bg/SSE,coordinator.runWithContext 包裹且投递面此刻可达,ALS 判)allow——工具执行落到
- * RunnerDeps.onQuestion 的 coordinator,问正在 tail 流的活人;无活流腿(sync /v1/tasks、verify/cascade、
- * durable resume 驱动、断连后的 detach 腿)ask——durable park 原语义逐字保留(#166 后无活流腿放行执行
- * 也不会产出空答:coordinator 无 ALS ctx ⇒ 冻结 `{kind:"unavailable"}`(src/question.ts),永不悬挂;
- * park 仍是把问题送到人面前的唯一那条腿,正当性不变、只是反事实前提换了)。
- * 工具名字面量与 server.ts 的 pre-CAS 守卫同源("AskUserQuestion",core 未根导出常量)。
- * ⚠️ **单一属主**(复审 A2):AskUserQuestion 的 durable 判决只有这一处。任何需要「同参重建」这条判决的
- * 地方(main.ts 的 parkedReviveInheritedGate 父约束链)必须调本工厂,不得自折 core 原形——两份拷贝里
- * 只改一份正是本条 finding 的成因。**登记豁免一处**:leader worker 腿(src/leader/wire.ts provisionWorker)
- * 自折 core 原形——该腿无活体问答面可装且 leader 不 import boot 层(分层),core 原形+sentinel 即其完整
- * 语义;豁免注在彼处互指,接活体面之日必须并回本工厂。
- */
 export function createDurableQuestionGate(live) {
     if (live === undefined)
         return createDurableQuestionPolicy();
@@ -46,69 +14,17 @@ export function createDurableQuestionGate(live) {
         },
     };
 }
-/**
- * 沙箱 lane 上**相对形**写目标的守卫补层用 env(codex 对抗复审 round1 finding 1,红先复现)。
- *
- * 缺口:沙箱 lane 的守卫策略拿不到 `rootPath`(沙箱 cwd 不是 server 能猜的,#165 裁定 1),而
- * `DeferredSandboxPathEnv.absolutePath` 对相对形一律报错。core 的 `canonicalizeTarget` 在
- * **absolutePath 失败**这一支不置 `unresolvedSymlink`,于是守卫策略走的是
- * 「判不了就弃权」的 `allow`(dist 亲读)。写门在场时这条腿被门的 `ask` 兜住;而
- * `bypassPermissions` / settings 缺席这几形**根本没有门**,于是 `Write(file_path: ".env")` 一路放行——
- * 而 core 的结构化写工具会把相对形按 engine 跟踪的 cwd 解析后真写下去(fs-write.js `resolveKey`)。
- *
- * 补法:**同一只**守卫策略工厂再铸一个实例,只把「路径→canonical key」这一步换成
- * 纯词法基准(本 env)。判定与提取(哪个参数是写目标、NotebookEdit 的 notebook_path 优先、段匹配)
- * 全部仍是 core 的,server 侧零复刻——复刻 core 的裁决逻辑正是「同源谎」那一类错误。
- *
- * 三条不可动的边界:
- *  · **绝对形一律弃权**(absolutePath 报错 ⇒ canon 失败且非 unresolvedSymlink ⇒ core 判 allow):
- *    绝对形归真身裁决那一层,#165「真身胜过名字」的裁定(域内良性软链名叫 `.ssh` 只 ask)不受影响。
- *  · **只会 deny,不会放行**:相对形自身拼写里出现的段,解析成绝对路径后仍在,所以词法命中即真命中;
- *    反过来一条名叫 `.env` 而真身良性的相对软链会被误 deny —— 方向是 fail-closed,与守卫集语义同向。
- *  · **覆盖面(2026-08-08 按 core 5.19.0 #108 校正;旧文见下方「历史」段)**:本层只在
- *    `ToolCallRequest.cwd` **缺席**那一形上说话。core 5.19.0 起每条路径解析型守卫按 `req.cwd ?? rootPath`
- *    解析写目标(dist `core/sensitive-path-policy.js`),而 `canonicalizeTarget` 拿到 baseCwd 后会先把
- *    相对形**拼成绝对形**再交给 env(dist `tools/fs/safety.js` 的 `baseCwd && !isAbsolutePathForm(...)`
- *    分支)—— 本层的 `absolutePath` 对绝对形一律报错弃权 ⇒ **有戳时本层自动让位**,由真身那一层
- *    (沙箱 `DeferredSandboxPathEnv` / host `NodeExecutionEnv`)按活 cwd 裁决,cwd 里的守卫段现在真看得见。
- *    ⇒ 本层今天的射程 = 「引擎没盖戳」的调用:相对形**自身拼写**里带守卫段的那一类(`Write(".env")`、
- *    `Write("cfg/.ssh/id_rsa")`),仍由本层 fail-closed 兜住。**不删臂**:让位与冗余不是一回事——
- *    删掉它等于把「缺戳即无守卫」写死,而缺戳形在契约上是 core 明确保留的回落语义(直接调用形)。
- *    两处特征化钉现在各带两臂(带戳 deny / 缺戳 allow):test/task-settings.test.ts 与
- *    test/run-local.test.ts(后者是真引擎端到端,已翻成 🔴 正控)。
- *
- *    📜 **历史(留档,别当现状读)**:2026-08-08 之前本层的覆盖面到「cwd 里的守卫段看不见」为止——
- *    本层把相对形挂在 `/` 上,而工具挂在 engine 活 cwd 上,`cd .git` 后 `Write("config")` 真写
- *    `<root>/.git/config` 而本层只看得到 `/config` ⇒ 弃权。design/181 刀3 的口径更正查明这条残余面
- *    **不是沙箱 lane 局部的**:host 腿虽供了 `rootPath`,那也是装配期的静态值,一样追不上被 Bash `cd`
- *    就地改写的 `cwdRef.current`(run-local 端到端真复现:`cd .git/hooks` 后 `Write("pre-commit")` 真落盘)。
- *    当年判定属主是引擎那条缝(不是任何一条消费腿——在消费腿里自己拿静态 cwd 追 `cd`,是拿会漂的复制品
- *    追引擎的真值,本文件反复点名的病),并把两条钉写成「引擎缝落地后一起翻面」。**该缝即 core backlog
- *    #108,已在 5.19.0 到货**,两条钉按上述翻面完毕。另一条备选收口(守卫集开启即把沙箱 lane 相对写
- *    一律 deny,有真受损方且无对应旋钮)因此作废,无需部署方拍板。
- */
 export class RelativeTargetLexicalEnv extends StubExecutionEnv {
-    /** 相对形 → `/<词法归一>`;绝对形 / 空串 / 含 NUL 一律报错(= 弃权,见类注)。 */
     absolutePath(path) {
         if (path.length === 0 || path.startsWith("/") || path.includes("\u0000")) {
             return Promise.resolve(err(new FileError("not_supported", "this guard layer only adjudicates RELATIVE write targets (absolute forms are adjudicated against the real sandbox filesystem)", path)));
         }
         return Promise.resolve(ok(posix.normalize(`/${path}`)));
     }
-    /** 恒「不存在」⇒ core 的 `canonicalizeNewPath` 逐级回退,最终把词法归一形当 canonical key 交给段匹配。
-     *  这里绝不能报错:报错会被 core 读成 `unresolvedSymlink` 而对**每一个**相对目标 deny(含普通文件)。 */
     exists(_path, _abortSignal) {
         return Promise.resolve(ok(false));
     }
 }
-/**
- * boot 期的守卫集**可编译性**门(#177 收口①,随 design/181 件一搬进本口 —— 三条消费腿同得)。
- *
- * 守卫集的编译发生在**每个请求**上。core 的 `compilePatterns` 对「一个路径段都没有」的模式(`"/"`、
- * `"//"`)THROW,那条 throw 会变成**每一个任务一条 500**,且运维从错误里看不出是自己的 env 写错了。
- * 消费腿在装配期先编译一次:非法旋钮值当场炸在启动上(与 config.ts 的 env fail-loud 同族),指名键与
- * core 的原因。env 只是编译期的占位(compilePatterns 不碰它),真裁决用的是每请求按 lane 铸的那一个。
- */
 export function assertGuardPatternsUsable(config) {
     if (config.sensitiveWritePatterns.length === 0)
         return;
@@ -119,20 +35,6 @@ export function assertGuardPatternsUsable(config) {
         throw new Error(`SENSITIVE_WRITE_PATTERNS is not a usable guard set: ${e instanceof Error ? e.message : String(e)}`);
     }
 }
-/**
- * UNGATED 信号的**补偿**(design/181 件一收编 / 件三三腿同得)。
- *
- * 审批基线铺开之后 core 的 `hasEffectAwareGate` 恒真,于是它那条 "write-capable hand tools are present
- * but UNGATED" 的 onError 不再触发(判据是 `policyLayers.length > 0`,prepare-task dist 亲读)。那条信号
- * 此前是「这个部署一个门都没接」这个 misconfig 的**唯一**提示,而守卫集只挡那二十来个路径段、其余写
- * 目标照旧无裁决 —— 信号不能因为我们铺了基线就静默消失,所以由我们自己按同一判据说一次。
- *
- * 判据(与信号消失的条件逐字互补):守卫集在场 ∧ 两条产**真**门的腿都不在场(durable 门关 ∧ 单用户
- * auto-accept 基线不适用)。三个量都是部署常量 ⇒ 消费腿在 boot 期说一次,不是每任务一次。
- *
- * ⚠️ 单一属主(design/181 件三):HTTP 腿与 run-local 腿共用本判据与文案。两处各写一份 = 一处改了另一处
- * 没改,而两份都长得像对的 —— 那正是本文件存在的理由。
- */
 export function buildOnlySensitiveBaselineWarning(config, seat) {
     if (config.sensitiveWritePatterns.length === 0 || seat.durableEnabled || seat.singleUserAutoAcceptBaseline)
         return undefined;
@@ -145,13 +47,6 @@ export function buildOnlySensitiveBaselineWarning(config, seat) {
         },
     };
 }
-/**
- * `applyRuntimeGovernance` 的 governance 实参预铸(design/181 件一)。
- *
- * 键存在性 profile 逐字保持消费腿原样:`autonomy`/`commandPolicy` 恒在场(值可为 `undefined`),
- * `manualModeShellGate`/`sensitivePathPolicy` 按在场性条件展开 —— `applyRuntimeGovernance` 的
- * `!== undefined` 判据对两者等价,但 profile 是折叠面的可观测字节,搬家不许顺手改。
- */
 export function createDeploymentGovernanceInputs(config, pathAdjudication) {
     const sensitivePathPolicy = config.sensitiveWritePatterns.length > 0
         ? (() => {
@@ -160,9 +55,6 @@ export function createDeploymentGovernanceInputs(config, pathAdjudication) {
                 patterns: config.sensitiveWritePatterns,
                 ...(pathAdjudication.cwd !== undefined ? { rootPath: pathAdjudication.cwd } : {}),
             });
-            // cwd 在场(host 形)⇒ 相对形已被 core 按 rootPath 解析进真身裁决,一层就够。
-            // cwd 缺席(沙箱形)⇒ 相对形在真身那一层是「判不了 ⇒ 弃权 allow」,而写门恰恰在
-            // bypass/settings 缺席这几形不在场 ⇒ 补一层纯词法的相对形守卫(见 RelativeTargetLexicalEnv)。
             if (pathAdjudication.cwd !== undefined)
                 return realTarget;
             return combinePolicies(realTarget, createSensitivePathPolicy({ env: new RelativeTargetLexicalEnv(), patterns: config.sensitiveWritePatterns }));
@@ -175,22 +67,6 @@ export function createDeploymentGovernanceInputs(config, pathAdjudication) {
         ...(sensitivePathPolicy ? { sensitivePathPolicy } : {}),
     };
 }
-/**
- * 审批基线 —— `applyRuntimeGovernance` 那个 base 的 `toolPolicy` 座(design/181 件一)。**恒非
- * `undefined`**:治理层是 tighten-only 的叠加层,没有基线可叠时它自己也产不出「门在场」这件事。
- *
- * 两形:
- *  · `durable` 在场 ⇒ durable 轴 = AskUserQuestion 判决门 + F4 高危写审批门(deny/neverAuto/预算/
- *    会话豁免全在 `createDurableAskPolicy` 里)。gated `ask` 由 core 变成 durable checkpoint suspend。
- *  · `durable` 缺席 ⇒ **adjudicated allow-all**(`createAllowDenyPolicy({})`):一条**在场的**、
- *    effect-aware 的策略。CC 的信任模型是 auto-accept,但门**机制**必须在场(core 原则「机制留、默认
- *    可更宽」)—— 满足 core 的 `hasEffectAwareGate`,恢复可观测性与 hook/tighten 点,而运维照旧用
- *    `AUTONOMY`/`commandPolicy` 收紧不可逆操作(由 `applyRuntimeGovernance` tighten-only 叠上)。
- *
- * ⚠️ 「零门意图才铺 allow-all」这条准入判据**不在本口**:它是消费腿的部署形判断(单用户/多租户、
- * 有无 checkpoint 店),属主是 `hasOperatorGateIntent`/`assertGateIntentServiceable`(src/approval.ts)。
- * 本口只按调用方给的形铸策略,绝不替它判「这个部署该不该有门」。
- */
 export function createApprovalBaselinePolicy(config, durable) {
     if (durable === undefined)
         return createAllowDenyPolicy({});

package/dist/digest-form.js

@@ -1,15 +1,3 @@
-/**
- * design/158 R12 收编叶子 — the sha256 content-address SHAPE constants, single-sourced. A neutral leaf (no
- * imports of its own) so both `security.ts`-adjacent modules and prompt/image/session-sync consumers can
- * depend on it without a layering edge. Six call sites across the tree each ran their OWN literal copy of one
- * of these two regexes (a bare-hex form and a scheme-qualified form) — same shape, independently typed out.
- * This module is the single point of truth for the SHAPE; each consumer's accept POLICY (prefix-stripping,
- * case-folding order) is UNCHANGED by this collection — those policies differ across call sites (a real,
- * pre-existing divergence, not introduced here) and are tracked for a follow-up cross-repo alignment, not
- * unified in this refactor.
- */
-/** A bare sha256 content-address: exactly 64 lowercase-hex characters, no scheme prefix. */
 export const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
-/** A scheme-qualified sha256 content-address: `sha256:` followed by 64 lowercase-hex characters. */
 export const SHA256_DIGEST_RE = /^sha256:[0-9a-f]{64}$/;
 //# sourceMappingURL=digest-form.js.map

package/dist/elicitation.js

@@ -1,37 +1,7 @@
-/**
- * E23 (shell-host contract) — inbound-MCP-elicitation HITL flow, the SERVICE side of core 1.124.0's live-only
- * `RunnerDeps.onElicit` seam (design/99 §E23).
- *
- * An opted-in MCP server (`McpServerSpec.elicitation === true`) may, MID-tool-call, ask the END USER for input.
- * core hands that request to `onElicit` and awaits the answer SYNCHRONOUSLY on the still-open task-scoped
- * connection (it replies to the server with whatever the promise resolves to). There is NO durable suspend —
- * a crash/replica-change loses an in-flight elicitation (acceptable for an interactive shell; a durable variant
- * waits on the deferred E22 longer-lived connection). So this whole flow is LIVE-ONLY + same-replica, the
- * `steer()`-class of HITL, NOT the durable approval/checkpoint class.
- *
- * The service is pure WIRE glue (the abstraction is core's, §0.1): forward the request to whoever is tailing the
- * run's stream (an `elicitation` SSE frame), park a promise, and resolve it from `POST /v1/elicitations/:id/respond`.
- * Three responsibilities are explicitly the deployment's (core delegates them):
- *   1. THROTTLE — core imposes no rate/count cap; an over-eager or hostile server could flood the human. We bound
- *      concurrency + total + per-server burst per run; a breach fail-closes to `decline`.
- *   2. FENCING — `message`/`requestedSchema` are server-controlled UNTRUSTED text; `message` is `delimitUntrusted`-
- *      fenced + secret-redacted before it reaches a human (the shell must also fence `requestedSchema` on display).
- *   3. FORM-MODE ONLY — v1 advertises form mode; url-mode (a phishing surface) is defensively rejected.
- *
- * ROUTING: `onElicit` lives on the SINGLETON runner's `RunnerDeps` and the request carries no taskId, so the run's
- * executor establishes a per-run context (AsyncLocalStorage, like `withPrincipal`) carrying the taskId (throttle
- * key), the owner (respond owner-gate), and an `emit` closure (durable append for background/resume legs; `res.write`
- * for the synchronous stream leg). `node:async_hooks` propagates it through every await, so `onElicit` — invoked deep
- * inside core's `callTool` — recovers it. No context ⇒ fail-closed `decline`.
- */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { uuidv7, delimitUntrusted } from "@sema-agent/core";
 import { redactSecrets, redactDeep } from "./trace/redact.js";
 import { recordFailOpen } from "./observability/fail-open.js";
-/** Size bounds on the UNTRUSTED server-controlled payload (the throttle bounds COUNT, these bound SIZE — an
- *  opted-in-but-hostile server otherwise amplifies a multi-MB prompt/schema into the durable log + SSE socket).
- *  The message is a human-facing prompt (a few KB is ample); a requestedSchema over the cap is dropped (the form
- *  can't render an abusive schema — fail-safe to no-schema). */
 const MAX_ELICIT_MESSAGE_CHARS = 4096;
 const MAX_ELICIT_SCHEMA_BYTES = 8192;
 export const DEFAULT_ELICITATION_THROTTLE = {
@@ -40,9 +10,6 @@ export const DEFAULT_ELICITATION_THROTTLE = {
     minIntervalMsPerServer: 1_000,
     ttlMs: 5 * 60_000,
 };
-/** Validate the respond body = core's `McpElicitResponse`. `content` is accept-only OPAQUE passthrough (core never
- *  validates it against `requestedSchema`); we validate only the outer shape (a flat record of scalars / string[]),
- *  never the schema. A non-accept drops content (MCP convention). */
 export function parseElicitationResponse(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
         return { ok: false, error: "body must be an object" };
@@ -66,10 +33,6 @@ export function parseElicitationResponse(body) {
     }
     return { ok: true, value: { action: b.action } };
 }
-/** redactDeep + size-bound an UNTRUSTED `requestedSchema` before it is persisted to the durable log / streamed
- *  (the same redact-at-write contract every other untrusted structured field honors, e.g. tool_end.output). A JSON
- *  Schema's free-text carriers (description/title/default/enum) can smuggle a secret. Over the byte cap ⇒ undefined
- *  (drop — an abusive schema can't render a form); unserializable (circular) ⇒ undefined. */
 function boundSchema(schema) {
     if (schema === undefined)
         return undefined;
@@ -83,12 +46,6 @@ function boundSchema(schema) {
     }
     return redacted;
 }
-/**
- * Coordinates inbound MCP elicitations for one server instance. Process-local + same-replica (the pending map is in
- * memory, like `steerableRuns`): a respond that lands on another replica finds nothing → 404. Present (passed into
- * `RunnerDeps.onElicit` + the respond route) ONLY when `MCP_ELICITATION_ENABLED` — absent ⇒ core advertises no
- * elicitation capability to any server (doubly fail-closed with the per-server `McpServerSpec.elicitation` default OFF).
- */
 export class ElicitationCoordinator {
     als = new AsyncLocalStorage();
     pending = new Map();
@@ -99,16 +56,12 @@ export class ElicitationCoordinator {
         this.throttle = throttle;
         this.now = now;
     }
-    /** Run `fn` with the per-run elicitation context ambient. On exit, cancel any still-pending elicitation for this
-     *  run (a live-only elicitation cannot outlive its leg) and drop the run's counters (no leak). The cancel covers
-     *  the case where the leg ends/throws while an elicitation is parked but the leg's own loop has already drained. */
     runWithContext(ctx, fn) {
         return this.als.run(ctx, async () => {
             try {
                 return await fn();
             }
             finally {
-                // Snapshot first — settle() mutates this.pending.
                 for (const [, p] of [...this.pending]) {
                     if (p.taskId === ctx.taskId)
                         p.settle({ action: "cancel" });
@@ -117,42 +70,26 @@ export class ElicitationCoordinator {
             }
         });
     }
-    /** `RunnerDeps.onElicit`. Core calls this when an opted-in server elicits the END USER mid-tool-call; the resolved
-     *  value is sent back to the server on the still-open connection. Fail-closed (`decline`/`cancel`) in every
-     *  uncertain case. Arrow property so it can be passed as `onElicit: coordinator.elicit` with `this` bound. */
     elicit = async (req, signal) => {
         const ctx = this.als.getStore();
-        // No run context to route to a human (a leg not wrapped by runWithContext — synchronous /v1/tasks, verify/cascade,
-        // or a leader sub-task) ⇒ fail-closed decline. NB on SUB-TASKS: subagent/team run on the SAME runner inside the
-        // parent's ALS frame, so a sub-task's elicitation INHERITS the top-level run's ctx — by design it routes to the
-        // top-level stream + owner and shares the per-run-tree throttle budget (one human, one budget); the frame's
-        // `mcpServerName` attributes which server asked. (Same tenant: a sub-task inherits the parent principal.)
         if (!ctx)
             return { action: "decline" };
-        // v1 FORM-MODE ONLY: defensively reject url-mode. core advertises form-only so `url` is never populated today;
-        // this is defense-in-depth so a future/hostile url can never reach a human as a phishing link.
         if (typeof req.url === "string" && req.url.length > 0)
             return { action: "decline" };
         if (signal?.aborted || ctx.abortSignal?.aborted)
             return { action: "cancel" };
-        // THROTTLE (service's job — core imposes none): bound concurrency + total + per-server burst. Breach ⇒ decline.
         const rc = this.countersFor(ctx.taskId);
         const t = this.now();
-        const last = rc.lastByServer.get(req.server); // undefined ⇒ first elicitation from this server (no interval gate)
+        const last = rc.lastByServer.get(req.server);
         if (rc.inflight >= this.throttle.maxConcurrentPerRun ||
             rc.total >= this.throttle.maxTotalPerRun ||
             (last !== undefined && t - last < this.throttle.minIntervalMsPerServer)) {
             return { action: "decline" };
         }
         const id = uuidv7();
-        rc.inflight += 1; // reserve a concurrency slot for the await; total/interval are charged only on a successful emit
-        // FENCE + secret-redact + SIZE-bound the untrusted human-facing prompt: delimitUntrusted neutralizes
-        // <system-reminder>/fence break-out on BOTH the body and the server-name label; redactSecrets strips a secret the
-        // server echoed; the slice bounds storage/CPU. requestedSchema is redactDeep'd + size-bounded (it is persisted to
-        // the durable log + streamed, served to trace readers — fencing-on-display alone does not contain secrets).
+        rc.inflight += 1;
         const message = delimitUntrusted(req.server, redactSecrets((typeof req.message === "string" ? req.message : "").slice(0, MAX_ELICIT_MESSAGE_CHARS)));
         const requestedSchema = boundSchema(req.requestedSchema);
-        // Deferred answer promise + idempotent settle (resolved by respond, the TTL timer, or an abort).
         let done = false;
         let timer;
         let resolveAnswer;
@@ -169,58 +106,38 @@ export class ElicitationCoordinator {
             rc.inflight = Math.max(0, rc.inflight - 1);
             resolveAnswer(r);
         };
-        // Both signals: the MCP per-request signal AND the run's own cancel signal (the former may not be chained to a
-        // run abort, which would otherwise leave a cancelled run parked here for the full TTL).
         const onAbort = () => settle({ action: "cancel" });
         timer = setTimeout(() => settle({ action: "decline" }), this.throttle.ttlMs);
         timer.unref?.();
         signal?.addEventListener("abort", onAbort, { once: true });
         ctx.abortSignal?.addEventListener("abort", onAbort, { once: true });
-        // Register BEFORE emitting so a (fast) respond can never miss the entry.
         this.pending.set(id, { settle, owner: ctx.owner, taskId: ctx.taskId });
-        // Emit the OPEN frame AWAITED so its durable append is ORDERED ahead of the answer/completion/terminal appends —
-        // a fire-and-forget append can commit out of seq order and be permanently skipped by the monotonic events-tail
-        // cursor (an invisible prompt that then TTL-declines). On a successful emit, charge the per-run-tree budget; a
-        // FAILED emit declines (nobody can answer) and must NOT burn maxTotal / the per-server interval.
         try {
             await ctx.emit({ type: "elicitation", elicitationId: id, mcpServerName: req.server, message, ...(requestedSchema !== undefined ? { requestedSchema } : {}), mode: "form", serverNowMs: this.now() });
             rc.total += 1;
             rc.lastByServer.set(req.server, t);
         }
         catch {
-            // #157:投递失败 ⇒ decline。方向已是 fail-closed(问不到人就是拒),缺的只是留痕。
             recordFailOpen("server.elicitation.open-frame-undelivered", `elicitation=${id} server=${req.server}`);
-            settle({ action: "decline" }); // inflight rolled back in settle
+            settle({ action: "decline" });
         }
         const answer = await answerP;
-        // Completion breadcrumb (dialog dismiss) — FIRE-AND-FORGET so a slow/hung durable append can NEVER delay
-        // returning the answer to core (which replies to the MCP server on the still-open connection). Best-effort +
-        // ordering-uncritical: the shell already has the answer via respond; a late/lost dismiss is cosmetic.
         void Promise.resolve()
             .then(() => ctx.emit({ type: "elicitation_complete", elicitationId: id, mcpServerName: req.server, action: answer.action, serverNowMs: this.now() }))
-            // #157:F 类兜底,与 question.ts 的孪生面同形同 tag 形(丢收尾渲染,不丢答案)。
             .catch(() => recordFailOpen("server.elicitation.complete-breadcrumb-dropped", `elicitation=${id}`));
         return answer;
     };
-    /** `POST /v1/elicitations/:id/respond` — resolve a parked elicitation with the shell's answer. Owner-gated with a
-     *  404 (no existence oracle): a non-owner AND an unknown id (answered / expired / wrong replica) both get 404.
-     *  Returns the HTTP {status, body}; the HTTP layer owns auth (gatedPrincipal + REQUIRE_PRINCIPAL) before calling. */
     respond(id, principal, body) {
-        // Validate the body BEFORE the lookup (steer parity): a bad body is the caller's error regardless of run state,
-        // so 400 is existence-independent (a malformed respond to ANY id → 400, never an existence oracle via 400-vs-404).
         const parsed = parseElicitationResponse(body);
         if (!parsed.ok)
             return { status: 400, body: { error: parsed.error, errorCode: "request.body_shape" } };
         const entry = this.pending.get(id);
-        // Owner-gate with 404 (no existence oracle): a non-owner AND an unknown id (answered / expired / wrong replica)
-        // both get 404, so a good-body caller can't tell another tenant's id from a nonexistent one.
         if (!entry || (entry.owner !== null && entry.owner !== principal)) {
             return { status: 404, body: { error: "no pending elicitation for this id (answered, expired, or not on this replica)", errorCode: "elicitation.not_pending" } };
         }
         entry.settle(parsed.value);
         return { status: 200, body: { elicitationId: id, delivery: "applied", action: parsed.value.action } };
     }
-    /** Test/observability hook: number of currently-parked elicitations. */
     pendingCount() {
         return this.pending.size;
     }