@sema-agent/server 1.323.0 → 2.0.1

package/dist/tool-approval.js

@@ -1,31 +1,103 @@
+/**
+ * [816]/[820]② tool-approval bridge — the SERVICE side of core's `RunnerDeps.onAsk` seam (core `tool-policy.ts`
+ * `resolveAsk`, 1.290's sync-ask leg). The SIBLING of {@link import("./question.js").QuestionCoordinator}: onQuestion
+ * routes the agent's AskUserQuestion tool to a live human; THIS routes a policy `ask` DECISION (e.g. the
+ * `createFsWriteGatePolicy` fs-write gate, an ask-list rule, or a non-durable safety ask) to the live human as a
+ * CC-parity three-choice card (Yes / Yes-allow-all-session / No).
+ *
+ * Wire shape (mirrors question end to end): core adjudicates a tool call `ask` → `resolveAsk(req, onAsk)` calls this
+ * coordinator's `ask` → we mint a pending entry + emit a `tool_approval` SSE frame on the run's live stream → the
+ * shell renders the three-choice card → `POST /v1/tool-approvals/:id/respond` settles the parked promise →
+ * `resolveAsk` maps our boolean to allow/deny. RESPOND BODY selection rationale: the question precedent's body is
+ * core's own QuestionAnswer (a structured multi-answer object) because core FENCES its semantics; an approval has no
+ * core-side answer object — `OnAsk` resolves to a BARE boolean — so the wire body is a minimal closed enum
+ * `{decision: "allow" | "allow_session" | "deny"}` mapping 1:1 onto the CC card's three choices (no free text = no
+ * fence needed; "allow_session" carries the Yes-allow-all intent that a boolean cannot).
+ *
+ * Session state ([820]② "桥内会话态"): `allow_session` remembers a per-CAPABILITY grant keyed by
+ * `[owner, sessionId, category]` — every LATER ask in that (owner, session) whose tool maps to the SAME category
+ * auto-allows WITHOUT a card (CC 207: "Yes, allow all edits during this session"). The category collapses the
+ * fs-WRITE tool family (Write/Edit/NotebookEdit, canonical space) into ONE bucket `"fs-write"`; any OTHER tool is
+ * its OWN bucket `"tool:<canonical>"`. 🔴 A `allow_session` on a NON-fs-write ask (an irreversible-Bash safety ask,
+ * an ask-list rule on another tool) therefore unlocks ONLY that same tool for the session — it must NEVER unlock the
+ * fs-write family (the "approve a cheap ask once → all future Write/Edit auto-allowed" escalation, 三路复审 A 组 修2).
+ * The key is scoped to the VERIFIED owner too, so a session id shared across principals cannot inherit another's
+ * grant. This is the cheapest mid-task implementation; a mode SWITCH (default → acceptEdits) still goes through the
+ * shell's intent on the next task ([820] table).
+ *
+ * 🔒 FAIL-CLOSED everywhere (the inverse of question's headless default — an unanswered QUESTION lets the model
+ * proceed; an unanswered APPROVAL must NOT let the write proceed): TTL expiry ⇒ false; run abort / client
+ * disconnect ⇒ false. Since [879] G1 (core 1.295 OnAsk 三值化) the "no reachable human" class returns
+ * "unavailable" instead of false — no ALS context AND no bound-closure broker hit(1.258 起 bg/嵌套子代经
+ * spec.onAsk 的 bound 闭包 + streams broker 直达宿主活流,「无 ctx」只剩 durable-submit/headless resume
+ * 残余腿)and emit failure
+ * (card never delivered, and only when this catch is the first settler — a human verdict that raced in during the
+ * await keeps its boolean) ⇒ "unavailable" → core durable-parks (or fail-closed denies without a checkpoint). core's
+ * `resolveAsk` maps false to a deny WITH the ask message, so the model can re-route (deny + continue turn, [819]⑤).
+ * Owner gate on respond = the VERIFIED principal (gatedPrincipal at the HTTP layer), 404 without an existence oracle
+ * — same posture as question/elicit. The frame's model-authored surfaces (message + args) are secret-REDACTED and
+ * size-bounded before they are streamed (same redact-at-write contract as question; the args are shown to a human,
+ * never re-fed to a model). No throttle (unlike question): an approval breach-default would be a DENY (task failure),
+ * and asks are turn-blocking by construction — the TTL bounds the human-side exposure instead.
+ */
 import { AsyncLocalStorage } from "node:async_hooks";
 import { uuidv7, canonicalToolName } from "@sema-agent/core";
 import { redactDeep, redactSecrets } from "./trace/redact.js";
+/** Size bound on the redacted args payload in a `tool_approval` frame (parity with question's MAX_QUESTIONS_BYTES).
+ *  Over the cap ⇒ the frame still goes out WITHOUT args (`argsOmitted: true`) — unlike a question (undisplayable ⇒
+ *  headless default is safe), an approval must still reach the human: toolName+message suffice to decide, and the
+ *  fail-safe decision on blind args is the human's No. */
 const MAX_APPROVAL_ARGS_BYTES = 16384;
+/** How long an unanswered approval waits before it DENIES (fail-closed — the human walked away; don't hold core). */
 const DEFAULT_APPROVAL_TTL_MS = 5 * 60_000;
+/** Bound on the remembered allow-all grants (insertion-order evict — a long-lived worker must not grow unbounded). */
 const MAX_ALLOW_SESSIONS = 4096;
+/** The fs-write tool family the session allow-all collapses into ONE capability bucket (canonical space — a
+ *  legacy-alias rule or a durable-resume replay carrying a pre-rename toolName still matches; MultiEdit canonicalizes
+ *  to Edit). Mirrors core's PATH_WRITE_TOOLS + NotebookEdit (the same set `createFsWriteGatePolicy` gates); NOT
+ *  exported by core's index, so the names are pinned here deliberately. */
 const FS_WRITE_TOOLS = new Set(["Write", "Edit", "NotebookEdit"].map(canonicalToolName));
+/** The session allow-all CAPABILITY CATEGORY for a tool (修2): the fs-write family shares one bucket ("fs-write" —
+ *  a yes-to-edits covers Write/Edit/NotebookEdit alike, CC 207 semantics); every other tool is its OWN bucket
+ *  ("tool:<canonical>") so an allow_session on it never grants anything beyond that same tool — a low-risk ask must
+ *  not become a session-wide write unlock. Canonical space in, category out. */
 function sessionAllowCategory(toolName) {
     const canonical = canonicalToolName(toolName);
     return FS_WRITE_TOOLS.has(canonical) ? "fs-write" : `tool:${canonical}`;
 }
+/** The allow-all grant key (修2): owner + sessionId + capability category, JSON-tuple-encoded so no segment can
+ *  ambiguate the boundary with the next (an owner or sessionId containing a separator can't forge another key).
+ *  Owner rides VERBATIM (null = auth-off/anonymous, its own scope) so a session id shared across principals never
+ *  leaks a grant across tenants. */
 function sessionAllowKey(owner, sessionId, category) {
     return JSON.stringify([owner, sessionId, category]);
 }
+/** Validate the respond body — the closed three-choice enum (rationale in the module header). */
 export function parseToolApprovalResponse(body) {
     if (body === null || typeof body !== "object" || Array.isArray(body))
         return { ok: false, error: "body must be an object" };
     const d = body.decision;
     if (d === "allow" || d === "allow_session" || d === "deny") {
+        // [1458] ctrl+g 编辑放行:allow 族可带 updatedInput(编辑后的 args 整体替换形,durable /decide 腿
+        // 同名位既有语义);deny 带=无意义,忽略不 400(宽收)。
         const u = body.updatedInput;
         return { ok: true, value: d, ...(d !== "deny" && u !== undefined ? { updatedInput: u } : {}) };
     }
     return { ok: false, error: 'decision must be one of "allow" | "allow_session" | "deny"' };
 }
+/** @deprecated design/158 N22: renamed to {@link parseToolApprovalResponse} — unifies the HITL trio's parse-fn
+ *  vocabulary (`parseQuestionResponse` / `parseElicitationResponse` / `parseToolApprovalResponse`, all "the
+ *  human's reply body"; `ToolApprovalDecision` itself is unchanged — it names the allow/deny VALUE, not the
+ *  parse function). Kept as a compat alias. */
 export const parseToolApprovalDecision = parseToolApprovalResponse;
+/** [1550] RB-39② 兑现:判别式换 core 1.378 显式键 `fromSubagent`(委派子代 gate 发起的 ask 恒带,受信
+ *  internals 事实——worker 不可伪造/不可抑制)。取代 [1546] MED-1 的「在场 ∧ ≠ 宿主 sessionId」权宜式
+ *  (旧判别式靠 ctx.sessionId 参与推导,sessionless adhoc 场景无法区分;显式键不依赖 ctx,恒定准确)。 */
 function isChildAsk(req) {
     return req.fromSubagent === true;
 }
+/** redactDeep + size-bound the UNTRUSTED tool args before they are streamed. Over the cap / unserializable ⇒
+ *  undefined (frame rides argsOmitted — see MAX_APPROVAL_ARGS_BYTES). */
 function boundArgs(args) {
     const redacted = redactDeep(args);
     try {
@@ -37,19 +109,55 @@ function boundArgs(args) {
     }
     return { args: redacted, omitted: false };
 }
+/**
+ * Coordinates the live tool-approval HITL for the singleton runner. Process-local + same-replica (the pending map is
+ * in memory, like QuestionCoordinator): a respond that lands on another replica finds nothing → 404. Present (passed
+ * into `RunnerDeps.onAsk` + the respond route) ONLY when `TOOL_APPROVAL_ENABLED` — absent ⇒ core's `resolveAsk`
+ * keeps its headless auto-deny for every ask ([819]⑤ fail-closed default, zero behavior change).
+ *
+ * G1 interplay (core 1.290 sync-ask knob, prepare-task): with an onAsk present, a NON-safety ask with NO per-task
+ * `durableApproval` skips the durable park and resolves on this sync leg (zero checkpoint, CC-interactive latency).
+ * A durable-approval deployment (`DURABLE_APPROVAL=true` sets spec.durableApproval on every task) keeps parking every
+ * ask durably — this bridge then only serves legs where the park machinery is absent. Safety asks (irreversible/
+ * egress) always keep the durable park when a checkpointStore exists (core's condition, not ours).
+ */
 export class ToolApprovalCoordinator {
     als = new AsyncLocalStorage();
     pending = new Map();
+    /** Per-capability session grants — keys = sessionAllowKey(owner, sessionId, category) (修2; bounded). */
     allowAllSessions = new Set();
+    /** [1546] HIGH-1(broker)→[1559]四 core 产品裁定「多活集合+广播+首决胜出」:per-(owner, host-session)
+     *  的**当前活跃连接集合**——boundAsk 闭包只携身份,emit 时广播给该 key 下**全部**活连接(宿主重连/
+     *  attach 新 SSE 时 runWithContext 各自注册进同一集合,谁也不覆盖谁);查无活连接 = "unavailable"
+     *  (G1 回路)。旧单指针形的缺口(file-backed local mode 无单活跃 run 409 守卫时,两个真正并发的
+     *  runWithContext 会让后到者的指针覆盖先到者,先到连接的卡静默不可达——core 点名与「1.334 标已告知
+     *  须以投递确认为前提」同族)已随本集合改造解:后到者只是加入集合,不挤走先到者。首个 respond()
+     *  经 `pending` map 天然 CAS 胜出(第二个 respond() 撞 id 已被删 → 404),其余连接靠 completion 帧
+     *  收 dismiss 通知(见 askBroadcast)。 */
     streams = new Map();
     ttlMs;
     constructor(ttlMs = DEFAULT_APPROVAL_TTL_MS) {
         this.ttlMs = ttlMs;
     }
+    /** Broker key:宿主 session 优先(retained/续聊子代跨 SSE 找得到新流),sessionless adhoc 退 taskId。
+     *  并发审查加固:显式维度前缀(`"session"`/`"adhoc"`)分隔两个取值域,不再靠 `task:` 字符串前缀"祈祷"
+     *  不会跟一个真实 sessionId 字面重合——此前形式 `sessionId ?? "task:"+taskId` 里,若某会话的
+     *  sessionId 恰好等于另一条 adhoc 流的 `"task:"+taskId`,两者会算出同一把 key(现网因 taskId 由
+     *  服务端 uuidv7 铸造、请求到达前不可预知而几乎不可达,但维度未加标签是编码层面的真实缺口)。 */
     streamKey(owner, sessionId, taskId) {
         return sessionId !== undefined ? JSON.stringify(["session", owner, sessionId]) : JSON.stringify(["adhoc", owner, taskId]);
     }
+    /** Run `fn` with the per-run approval context ambient. On exit, notify every pending broadcast ask that this
+     *  ctx is no longer a live target — an ask only dies once ALL its targets are gone (fail-closed backstop, the
+     *  inverse of question's release-unanswered — but no longer a blunt "any one target exits ⇒ kill it" rule,
+     *  see {@link PendingApproval.onTargetGone}).
+     *  [1535] 注意([1539] core 点名的火):委派子代的 ask 经 {@link boundAsk} 落 pending 时不带
+     *  `targetCtxs`/`onTargetGone`(只有 `originTaskId === undefined` 的宿主自身条目才带)——session-scoped
+     *  bg 子代活过宿主 turn 时其未决卡不被这里触碰(TTL/abortSignal 仍兜底)。 */
     runWithContext(ctx, fn) {
+        // broker 注册([1559]四 多活集合):本流加入该 (owner, session) 的活跃连接集合;退出时只摘除自己
+        // ——同 key 下真正并发的其余连接不受影响(这正是本车要修的「单指针后到覆盖先到」缺口:旧形
+        // `streams.set(key, ctx)` 会让后到者的注册整个替换掉先到者,先到连接从此收不到任何卡)。
         const key = this.streamKey(ctx.owner, ctx.sessionId, ctx.taskId);
         let set = this.streams.get(key);
         if (!set) {
@@ -66,6 +174,11 @@ export class ToolApprovalCoordinator {
                 liveSet.delete(ctx);
                 if (liveSet.size === 0)
                     this.streams.delete(key);
+                // [1559]四独立复审①(HIGH)修:不再拿单个 `originCtx === ctx` 当清扫判据——多活集合下 `originCtx`
+                // 只是广播目标里任意一个成员,跟"这次 ask 到底是不是这条连接的执行栈在等它"没有必然关系,单独
+                // 靠它判死会误杀仍有其他活连接(甚至真正在等应答的那条)在场的未决卡。改为:只通知那些把本 ctx
+                // 列为广播目标之一的条目(`targetCtxs?.has(ctx)`——子代 ask 从不设 targetCtxs,天然免疫),
+                // 由 `askBroadcast` 内部的 liveConnections 倒计时决定是不是"全体目标都没了"才真正判死。
                 for (const [, p] of [...this.pending]) {
                     if (p.targetCtxs?.has(ctx))
                         p.onTargetGone?.(ctx);
@@ -73,15 +186,31 @@ export class ToolApprovalCoordinator {
             }
         });
     }
+    /** 测试/可观测性钩子:该 (owner, session/taskId) broker key 下当前活跃连接数——断言多连接注册/清扫
+     *  行为时用,免得伸手进私有内部状态。 */
     liveConnectionCount(owner, sessionId, taskId) {
         return this.streams.get(this.streamKey(owner, sessionId, taskId))?.size ?? 0;
     }
+    /** `RunnerDeps.onAsk`. core's resolveAsk calls this for each policy `ask` on the sync leg. [879] G1 三值化
+     *  (core 1.295):boolean = 人的决定;`"unavailable"` = 本 ask 到达时刻判无活人可同步送达 —— core 以
+     *  approverUnavailable 回路把这只 ask 交回 suspendAsk 走 durable park(park 设施缺席的部署 core 自己
+     *  fail-closed deny)。1.199 的「durable 部署不 wire onAsk」止血就此撤除:恒 wire,park 与 live 卡两全。
+     *  Arrow property so it can be passed as `onAsk: coordinator.ask` with `this` bound. */
     ask = async (req, signal) => {
         const ctx = this.als.getStore();
+        // No run context (background/workflow/headless/durable-submit leg — [820]④) = nobody to render the card ⇒
+        // "unavailable"(交 durable park),不再把「无人可问」翻译成 deny(1.295 前无三值只能 fail-closed)。
         if (!ctx)
             return "unavailable";
         return this.askBroadcast([ctx], req, signal);
     };
+    /** [1535] server 半场(审批链战役,[1539] 定谳断点①的修;[1546] HIGH-1 broker 形):宿主 sync
+     *  streaming 腿在装配点以本闭包挂 `spec.onAsk`;core 继承链(parentConstraints 冻结
+     *  `spec.onAsk ?? deps.onAsk`,1.294 起)把它逐 ancestor 冻给每个委派子代——子代(bg/嵌套孙代)的
+     *  权限 ask 不再依赖 ALS,直达宿主 live 流的审批卡。**闭包只携身份**(owner/taskId/sessionId),
+     *  emit 时经 broker 取该 (owner, session) 的「当前」活跃流(宿主重连/续聊的新 SSE 自动接卡;
+     *  internalsSnapshot 冻结的闭包因此永不携死流)。查无活流 = "unavailable"(G1 回路:durable 部署
+     *  park;inherited plain-ask 的 park 回路 = core RB-39①,落地前该臂 = deny,与 1.257 前行为一致)。 */
     boundAsk = (identity) => {
         return (req, signal) => {
             const set = this.streams.get(this.streamKey(identity.owner, identity.sessionId, identity.taskId));
@@ -91,13 +220,31 @@ export class ToolApprovalCoordinator {
             return this.askBroadcast(live, req, signal);
         };
     };
+    /** 广播版裁决路径——`ask()`(ALS,恒单元素数组)与 `boundAsk`([1559]四多活集合,可能多元素)共用。
+     *  全体 `ctxs` 保证同一 (owner, sessionId)(streamKey 分组不变式;单元素数组平凡成立)。
+     *
+     *  [1559]三 emit-race 加固(回黑板 [1558]三1,core 确认方向):「等 emit 完成」与「等
+     *  TTL/abort/respond 三选一落定」显式 race——`emit` 的类型契约允许异步实现(durable-append 目标),
+     *  若挂死,旧形 `await ctx.emit(...)` 会让整条 ask 乃至调用方 turn 一起卡死,TTL/abort 定时器虽已
+     *  触发也无人读取其结果。核心不变式:race 由非人类结局(TTL/abort)先赢、且 emit 广播尚未有任何一路
+     *  确认完成时,不可扣一个武断的「deny」终局(不知道卡是否曾送达任何人)——按 G1 回路交
+     *  "unavailable"。人类 respond() 落地的裁决永远照旧信任、不受本判据影响:它只可能在 approvalId 已经
+     *  送达某个客户端之后发生(respond 需要客户端手上有这个 id),这是 outcome==="allowed"/"denied" 与
+     *  "expired"(TTL/abort/run-exit-cleanup/emit 广播全灭四类共用)的天然分野。 */
     async askBroadcast(ctxs, req, signal) {
         if (signal?.aborted)
             return false;
+        // 连接级存活过滤:单连接(ask() 的 ALS 语义,今日 100% 生产流量)沿用「这条连接已经死了 ⇒ false」的
+        // 原判(entry 时刻检查,零行为变化)。多活集合(boundAsk 广播)下,entry 时已死的目标不计入广播——
+        // 若全体目标 entry 时已死,同样直接 false(单连接场景的自然推广:数组退化成 1 个已死 ctx 时结果
+        // 相同)。
         const aliveCtxs = ctxs.filter((c) => !c.abortSignal?.aborted);
         if (aliveCtxs.length === 0)
             return false;
         const primary = aliveCtxs[0];
+        // Session allow-all (CC "Yes, allow all edits during this session"): keyed [owner, sessionId, category] — the
+        // asking tool's OWN capability category must have been granted in THIS owner's session (修2; module header).
+        // 多活集合下 owner/sessionId 对全体 ctxs 恒同(streamKey 分组保证),primary 取值代表整个集合安全。
         if (primary.sessionId && this.allowAllSessions.has(sessionAllowKey(primary.owner, primary.sessionId, sessionAllowCategory(req.toolName)))) {
             return true;
         }
@@ -129,6 +276,18 @@ export class ToolApprovalCoordinator {
             signal.addEventListener("abort", onTaskAbort, { once: true });
             abortListeners.push([signal, onTaskAbort]);
         }
+        // 目标存活倒计时(single source of truth):单连接沿用「这条连接死 = 无人可送达 = 判死」的今日语义
+        // (数组退化成 1 时,一路"消失"即到零);多活集合改「全体目标都消失才判死」——any-of(哪一条先掉线
+        // 就杀)会重现 core 点名的「单指针覆盖」同族 bug:一条连接消失不该杀死仍有其他活连接在场、可能仍会
+        // 被响应的卡。**[1559]四独立复审①(HIGH)修**:「消失」现在统一有两条喂入路径——(a)该 ctx 自己的
+        // abortSignal 触发(下方监听器),(b)该 ctx 的 `runWithContext` 作用域退出,不论是正常返回还是抛出
+        // (`runWithContext` 的 finally 经 `targetCtxs`/`onTargetGone` 回调这里,见下方 pending.set)——此前
+        // 两条路径完全独立、互不知情:(b)是靠 `originCtx === ctx` 单独判定,而 `originCtx` 在多活集合下只是
+        // 目标数组里任意一个成员(通常是最先注册的那条),跟"是不是这条连接的执行栈真的在等这次 ask"没有
+        // 必然关系——一条完全不相关、只是恰好也在同一 (owner,session) 广播集合里的连接,处理完它自己另一个
+        // 无关的请求正常退出,就会单独触发把整条 ask 误杀,即便真正在等它的那条连接分毫未动、仍然存活。
+        // `goneCtxs` 去重:同一个 ctx 理论上可能同时/先后触发 (a)(b) 两条路径(abort 通常伴随其作用域跟着
+        // 退出),避免重复扣减。
         let liveConnections = aliveCtxs.length;
         const goneCtxs = new Set();
         const onTargetGone = (c) => {
@@ -146,6 +305,10 @@ export class ToolApprovalCoordinator {
             c.abortSignal.addEventListener("abort", onCtxAbort, { once: true });
             abortListeners.push([c.abortSignal, onCtxAbort]);
         }
+        // Register BEFORE emitting so a (fast) respond can never miss the entry. 子代 ask 的生存期挂子代
+        // (originTaskId 在场 = 不被宿主 finally 清扫烧;[1539] 注意事项,判别式 = isChildAsk 顶注)——同理,
+        // 子代 ask 从不设 targetCtxs/onTargetGone(任何宿主 ctx 的 runWithContext 退出都不该碰它,只有它
+        // 自己的 TTL/abortSignal 才作数;上面的 aliveCtxs abort 倒计时仍照常适用于它自己的连接级 abort)。
         const child = isChildAsk(req);
         this.pending.set(id, {
             settle,
@@ -161,7 +324,11 @@ export class ToolApprovalCoordinator {
             type: "tool_approval",
             approvalId: id,
             toolName: req.toolName,
+            // [1939]:core 的 tool-call id 逐字透传(AskRequest.toolCallId 是必填);理由见字段顶注。
             ...(typeof req.toolCallId === "string" && req.toolCallId !== "" ? { toolCallId: req.toolCallId } : {}),
+            // 帧上 sourceTaskId/fromSubagent/sourceAgentName 只出**子代** ask(server 侧判别收口,现判别
+            // 键 = req.fromSubagent[core RB-39② 显式受信键]——sourceTaskId 仍旁随传但不再是判别式,复审
+            // F2 案:core 对宿主 ask 也恒填 sourceTaskId=宿主 sessionId,裸透传会让每张宿主卡被误判子代)。
             ...(child
                 ? {
                     sourceTaskId: req.sourceTaskId,
@@ -172,6 +339,10 @@ export class ToolApprovalCoordinator {
             message: typeof req.message === "string" ? redactDeep(req.message) : "",
             ...(bounded.omitted ? { argsOmitted: true } : { args: bounded.args }),
         };
+        // 每路 emit 独立兜底(catch 而非任其抛出/reject 冒泡)——一路失败不拖垮整个广播的判定;`emitOne`
+        // 因此**永不** reject(同时吸收同步 throw 与异步 rejection),`Promise.all` 也就永不 reject,
+        // 下面的 `Promise.race` 才能安全地把它当"正常完成"的一端,不会把某一路的失败错误地冒泡成
+        // askBroadcast 自身的未捕获异常。
         const emitOne = async (c) => {
             try {
                 await c.emit(frame);
@@ -181,33 +352,66 @@ export class ToolApprovalCoordinator {
                 return false;
             }
         };
+        // 🔴 [1575] F2 修(cli 复查,红先行确认真红):旧形完成帧广播是"调用序"跟着 `await allowedP`
+        // 走,不是"落盘序"——respond() 可能在某条连接自己的 OPEN emit 尚未落盘完成时就已经 settle(TTL/
+        // abort/emit-race 三选一显式 race 就是为了让这成为可能),而 complete 帧当时是立即 fire-and-forget
+        // 广播给全体 aliveCtxs,不等每条连接自己的 OPEN 是否已经落盘——异步/durable-append 型 emit 目标
+        // (本改造自述要服务的场景)下,慢连接会看到 complete 先于 open 落盘,回放/转录面呈现「永不 dismiss
+        // 的悬卡」或「丢失的 dismiss」。修复:**每条连接的 complete 帧显式排在该连接自己的 OPEN emit 落定
+        // 之后**(用 per-ctx 的 openP 建 Map,不是笼统一个 aliveCtxs.map)——旧注释钉过的「Emit the OPEN
+        // frame AWAITED (ordering ahead of the completion frame...)」不变式对多活广播的每一条连接分别成立,
+        // 不因为广播整体不再阻塞返回就失效。
         const openByCtx = new Map(aliveCtxs.map((c) => [c, emitOne(c)]));
         const emitAllP = (async () => {
             const results = await Promise.all(openByCtx.values());
             const anySucceeded = results.some(Boolean);
+            // ⚠️ 竞态门(cross-review 抓获,原单连接形已有的不变式,广播形延续):respond/abort 可能在 emit
+            // 广播完成前已经 settle(entry 先于 emit 注册)。emit 随后才判定全灭时,已有的人类 boolean 裁决/
+            // abort 终局必须保持——只有本判定是第一个 settle 者(done 仍 false)才算「卡从未送达任何人」。
             if (!anySucceeded && !done) {
                 emitFailed = true;
                 settle(false, "expired");
             }
             emitSettled = true;
         })();
+        // [1559]三:emit 完成 vs TTL/abort/respond 三选一落定——显式 race,不让挂死的 emit 独占执行权。
         await Promise.race([emitAllP, allowedP]);
         const settled = await allowedP;
+        // Completion breadcrumb (card dismiss) — fire-and-forget to every target that actually got the OPEN frame
+        // (aliveCtxs — a ctx filtered out at entry as already-dead never saw `tool_approval` in the first place, so
+        // it has nothing to dismiss), so a slow/hung emit never delays returning to core AND every connection in
+        // the set learns the card resolved elsewhere([1559]四「其余连接收 resolved/dismissed 通知」的直接落点——
+        // 单连接场景退化为原来的一次 emit)。**per-ctx 链在该 ctx 自己的 openP 之后**(F2 修的落点)——
+        // `openByCtx.get(c)!` 永不 reject(emitOne 内部已吸收),所以不需要额外 `.catch` 才能继续链下去;
+        // `.then(() => c.emit(...))` 包一层是必须的:该 ctx 的 complete emit 若同步 throw,要先转成
+        // rejection 才能被后面的 `.catch` 接住,否则会在此处同步抛出、跳过 catch。
         for (const c of aliveCtxs) {
             void openByCtx
                 .get(c)
                 .then(() => c.emit({ type: "tool_approval_complete", approvalId: id, outcome: lastOutcome }))
                 .catch(() => undefined);
         }
+        // emit 全灭 = 卡从未送达任何人(≠人拒绝/TTL 走人)——同属「无活人可达」类 ⇒ "unavailable" 交 durable
+        // park。
         if (emitFailed)
             return "unavailable";
+        // emit 广播尚未有任何一路确认完成(既非成功也非已知失败)就被 TTL/abort 抢先判定 ⇒ 无法确认卡是否
+        // 曾送达任何人,不可扣一个武断的「deny」终局——按 G1 回路交 "unavailable"(同 emit 失败同一处置,
+        // core [1559]三 确认方向)。respond() 落地的人类裁决(outcome allowed/denied)不受影响,原因见本
+        // 方法顶注。
         if (!emitSettled && lastOutcome === "expired")
             return "unavailable";
+        // [1458] updatedInput 前向兼容形:allow+编辑到位 → 以 `{allow:true, updatedInput}` 对象形返回——
+        // 旧 core(≤1.356 resolveAsk 折叠 `ok ? ALLOW`)把对象当 truthy=allow(行为=现状,编辑忽略,壳侧
+        // 版本门挡假 UI);core 放宽 OnAsk 认对象臂后(黑板转单)编辑即生效。deny 恒返 false(falsy 纪律)。
         if (settled.allowed && settled.updatedInput !== undefined) {
             return { allow: true, updatedInput: settled.updatedInput };
         }
         return settled.allowed;
     }
+    /** `POST /v1/tool-approvals/:id/respond` — settle a parked approval with the shell's decision. Owner-gated with a
+     *  404 (no existence oracle), body validated first (400 is existence-independent) — question/steer parity. The HTTP
+     *  layer owns auth (gatedPrincipal + REQUIRE_PRINCIPAL) before calling. */
     respond(id, principal, body) {
         const parsed = parseToolApprovalResponse(body);
         if (!parsed.ok)
@@ -216,10 +420,18 @@ export class ToolApprovalCoordinator {
         if (!entry || (entry.owner !== null && entry.owner !== principal)) {
             return { status: 404, body: { error: "no pending tool approval for this id (settled, expired, or not on this replica)", errorCode: "tool_approval.not_pending" } };
         }
+        // PAIR-REVIEW [1392]②:ack 带 rememberApplied 诚实回显——allow_session 且**真记了**(sessionId 在,
+        // grant 落桥内店)= true;allow_session 但无 sessionId(adhoc 无会话,记不了)= false(壳不得渲染
+        // 「本 session 全放行」);普通 allow/deny 不涉 remember = 字段省略。durable decide 腿的同名回显
+        // (server.ts:4326)语义对齐。
         let rememberApplied;
         if (parsed.value === "allow_session")
             rememberApplied = Boolean(entry.sessionId);
         if (parsed.value === "allow_session" && entry.sessionId) {
+            // Bounded remember (insertion-order evict). 修2 scope: the grant is keyed by THIS ask's own capability
+            // category — a Write/Edit-family ask unlocks the fs-write family for the (owner, session); ANY other tool's
+            // allow_session unlocks only that same tool. A cheap non-write ask can therefore never become a session-wide
+            // write unlock (the pre-fix behavior: bare-sessionId key + remember-regardless-of-tool).
             if (this.allowAllSessions.size >= MAX_ALLOW_SESSIONS) {
                 const oldest = this.allowAllSessions.values().next().value;
                 if (oldest !== undefined)
@@ -229,8 +441,11 @@ export class ToolApprovalCoordinator {
         }
         const allowed = parsed.value !== "deny";
         entry.settle(allowed, allowed ? "allowed" : "denied", parsed.updatedInput);
+        // updatedInputForwarded=server 已透传(是否被引擎消费取决于 core OnAsk 对象臂是否在——诚实措辞,
+        // 不称 applied;cli 版本门+core 单落地后全链生效)。
         return { status: 200, body: { approvalId: id, delivery: "applied", decision: parsed.value, ...(rememberApplied !== undefined ? { rememberApplied } : {}), ...(parsed.updatedInput !== undefined && allowed ? { updatedInputForwarded: true } : {}) } };
     }
+    /** Test/observability hooks. */
     pendingCount() {
         return this.pending.size;
     }

package/dist/trace/artifacts.d.ts

@@ -1,15 +1,24 @@
 import type { RunEvent } from "../plugins/store-contracts.js";
 export interface TraceArtifact {
+    /** Stable within the task: `<taskId>:<n>` in first-seen order — safe as a UI key + dedupe handle. */
     id: string;
     taskId: string;
+    /** Work-view correlation (omitted when the run has none) — lets the client group a job's artifacts. */
     jobId?: string;
     kind: "file" | "git-push";
+    /** file: the workspace-relative path. git-push: the refspec tail (e.g. "origin HEAD:branch") or the command. */
     ref: string;
     summary?: string;
+    /** file only (additive, P2 workspace "what changed how much"): HUNK-level line counts summed over the
+     *  successful contributing calls — write_file counts its content lines as additions; edit_file counts
+     *  new_string lines as additions + old_string lines as deletions. NOT a git diff (no patch bodies in the
+     *  log); when a real patch store lands these move to the reserved `diff` kind with a patchRef. */
     additions?: number;
     deletions?: number;
+    /** ts of the LAST successful contributing tool call. */
     createdAt: string;
 }
+/** Project the durable event log into artifacts. Events must be in seq order (getEvents guarantees it). */
 export declare function projectArtifacts(events: readonly RunEvent[], run: {
     taskId: string;
     jobId?: string | null;

package/dist/trace/artifacts.js

@@ -1,12 +1,30 @@
+/**
+ * trace.artifacts (M2) — project "what the agent produced" from the durable event log.
+ *
+ * Deterministic projection, no new write path: artifacts are DERIVED from the already-persisted
+ * tool_start/tool_end pairs (S2 log), so they exist for every historical run and cannot drift from execution.
+ * v1 produces two kinds:
+ *  - `file`     — a successful `Write` / `Edit` call (deduped per path; the summary counts edits).
+ *  - `git-push` — a successful `bash` call whose command contains `git push` (ref = the parsed refspec tail).
+ * `diff` is declared in the wire schema but NOT produced in v1 (we don't capture patch bodies in the log) —
+ * consumers must treat kinds as an open set. Args in the log are already secret-redacted at persist time.
+ */
 import { canonicalToolName } from "@sema-agent/core";
+/** Line count of a tool-arg string ("" = 0; no trailing-newline inflation). */
 function lines(v) {
     if (typeof v !== "string" || v.length === 0)
         return 0;
     return v.split("\n").length;
 }
+// Q6 (core 1.161) CC names, CANONICAL only — this projection runs over HISTORICAL event logs, so `canonicalToolName`
+// folds persisted pre-rename rows (a 1.171-era "MultiEdit" start) onto their canonical spelling ("Edit") at read time.
+// core 1.202 retired MultiEdit into an Edit alias; Edit itself now carries an optional `edits[]` batch.
 const FILE_TOOLS = new Set(["Write", "Edit", "NotebookEdit"]);
 const GIT_PUSH_RE = /\bgit\b[^;|&]*\bpush\b\s*(.*)/;
+/** Project the durable event log into artifacts. Events must be in seq order (getEvents guarantees it). */
 export function projectArtifacts(events, run) {
+    // Pair tool_start args with the matching tool_end by toolCallId — only a SUCCESSFUL call (isError false)
+    // produces an artifact (a failed write/push produced nothing).
     const starts = new Map();
     const byKey = new Map();
     for (const ev of events) {
@@ -20,25 +38,32 @@ export function projectArtifacts(events, run) {
         const start = starts.get(d.toolCallId);
         if (!start)
             continue;
-        starts.delete(d.toolCallId);
-        const toolName = canonicalToolName(start.toolName);
+        starts.delete(d.toolCallId); // each call contributes at most once
+        const toolName = canonicalToolName(start.toolName); // fold persisted pre-rename rows (e.g. "MultiEdit") onto CC canonical
         if (FILE_TOOLS.has(toolName)) {
+            // Write/Edit key the write target on `file_path` (core 1.169 batch-B renamed `path`→`file_path`, dual-accept) —
+            // try it FIRST, fall back to `path` (a pre-1.169 emit or durable checkpoint still carries the old name), then
+            // NotebookEdit's `notebook_path` (core 1.163; unchanged by batch-B). Missing all three → not a path-bearing call.
             const path = typeof start.args["file_path"] === "string" ? start.args["file_path"] : typeof start.args["path"] === "string" ? start.args["path"] : typeof start.args["notebook_path"] === "string" ? start.args["notebook_path"] : undefined;
             if (!path)
                 continue;
+            // Hunk-level line stats from the call args themselves (zero new storage; args already redacted).
+            // Edit is batch-capable (core 1.202: an `edits[]` array — also the shape of a persisted legacy MultiEdit
+            // row, folded onto "Edit" above): with a batch, sum each edit's new_string/old_string lines; a single
+            // edit keeps the flat new_string/old_string fields.
             const edits = Array.isArray(start.args["edits"]) ? start.args["edits"] : [];
             const add = toolName === "Write" ? lines(start.args["content"])
                 : toolName === "NotebookEdit" ? lines(start.args["new_source"])
                     : edits.length > 0 ? edits.reduce((s, e) => s + lines(e["new_string"]), 0)
-                        : lines(start.args["new_string"]);
-            const del = toolName !== "Edit" ? 0
+                        : lines(start.args["new_string"]); // Edit (single)
+            const del = toolName !== "Edit" ? 0 // Write/NotebookEdit carry no old_string (NotebookEdit delete-mode → 0 add 0 del = a touched count)
                 : edits.length > 0 ? edits.reduce((s, e) => s + lines(e["old_string"]), 0)
                     : lines(start.args["old_string"]);
             const key = `file:${path}`;
             const prev = byKey.get(key);
             byKey.set(key, { kind: "file", ref: path, count: (prev?.count ?? 0) + 1, ts: ev.ts, add: (prev?.add ?? 0) + add, del: (prev?.del ?? 0) + del });
         }
-        else if (toolName === "Bash") {
+        else if (toolName === "Bash") { // Q6 (core 1.161): was "bash"; canonical fold above is identity for it today
             const command = typeof start.args["command"] === "string" ? start.args["command"] : "";
             const m = GIT_PUSH_RE.exec(command);
             if (!m)

package/dist/trace/core-keyset-guard.d.ts

@@ -1,4 +1,22 @@
+/**
+ * L1 键集机器门([1549] 方法论倡议 server 认领件;clay 令 2026-07-23「不能永远编码有限→复审补漏」)。
+ *
+ * 病族:**投影白名单剥键**——core 给源类型加 additive 新键,server 的列投影/白名单静默丢,直到穿透
+ * 审查才被人肉抓。已四案:RosterEntry.model([1532])、task_progress.status / TaskNotificationPayload
+ * 四键 / BackgroundChildEvent.usage+transcriptId([1543] 族B)、SDK 0.0.72 fleet meta 剥键。
+ *
+ * 机制:对每个「core 源类型 → server 投影」面声明**已处置键集** = PROJECTED(真透传)∪ EXCLUDED
+ * (显式记账不透传,理由必写)。`Exclude<keyof 源, 已处置>` 约束为 never——**升 core 后源类型出新键
+ * ⇒ 本文件 tsc 红**(新键必须被「透传」或「记账排除」二选一处置,不再有静默第三态)。
+ *
+ * ⚠️ 执行点 = `tsc --noEmit`(发车门 1):vitest 走 esbuild 转译不查类型、test/ 不在 tsc project——
+ * 所以本文件必须留在 src/ 下。写作时自证过:临时从 PROJECTED 删一键 → tsc 红。
+ *
+ * 维护:core 新键到来时,transparently 透传的加进对应 PROJECTED 并去实现投影;有意不上 wire 的加进
+ * EXCLUDED 并写一行理由。谁改投影(project.ts / fleet-bus.ts / roster-store-sql.ts)谁同步本文件。
+ */
 import type { TaskNotificationPayload, BackgroundChildEvent, RosterEntry, AskRequest, TaskEvent } from "@sema-agent/core";
+/** 编译期断言:T 必须收敛到 never(有残余键 = tsc 红)。 */
 type AssertAllKeysHandled<T extends never> = T;
 type NotificationProjected = "task_id" | "task_type" | "toolUseId" | "status" | "summary" | "result" | "output_file" | "usage" | "sessionId" | "seq" | "lines" | "stoppedBy" | "source" | "exitCode" | "partial" | "diagnostics" | "recentSteps" | "editedFiles" | "resumable" | "completionId";
 type _GuardNotification = AssertAllKeysHandled<Exclude<keyof TaskNotificationPayload, NotificationProjected>>;

package/dist/trace/ledger-sink.d.ts

@@ -1,22 +1,65 @@
 import { NotifiedKeys } from "../orchestration/workflow-completion-inbox.js";
+/**
+ * LedgerSink — the SINGLE "stream event → durable runs-ledger" projection, shared by the background leg
+ * (runs.ts `runInBackground`) and the sync `/v1/tasks/stream` detach lane (server.ts, `x-detach-on-disconnect`).
+ *
+ * [900]①/[906]③: the sync leg historically persisted only createRun+setTerminal — its events ledger stayed
+ * EMPTY, so after a detach the shell could only poll the terminal row. Feeding the same sink on the detach
+ * lane makes `GET /v1/runs/:id/events` replay the full stream in the EXACT bg-leg vocabulary (the ledger
+ * consumer binds to these type/data shapes — a second copy of this switch would drift into a false ledger,
+ * so never fork it).
+ *
+ * Scope: only the PURE transform lives here — text/reasoning coalescing, redaction, the per-run monotone
+ * `seq`, and the type/data whitelist shapes. Everything leg-specific stays with the caller: rewind anchors,
+ * fleet rows, metrics, model-usage deltas (E8), checkpoint parking and run-row settles. `done` and
+ * `message_committed` are deliberately NO-OPS in {@link LedgerSink.onEvent} — the bg leg must interleave
+ * model-usage writes between the text flush and the terminal event (it drives {@link LedgerSink.appendParked}
+ * / {@link LedgerSink.appendDone} itself), and message_committed is a session-tree concern (replay walks the
+ * persisted tree; it is never a ledger row).
+ */
 export interface LedgerSink {
+    /** Seq-stamped raw append — for a leg's out-of-band rows (elicitation/question frames, model_usage deltas,
+     *  suggestions, `failed`) that must share this run's single seq counter. Redaction is the CALLER's duty on
+     *  this raw door (every existing site already redacts); the typed doors below redact internally. */
     append(type: string, data: unknown): Promise<void>;
+    /** Flush the buffered turn text/reasoning. Thinking precedes content within a turn → a buffered reasoning
+     *  block flushes FIRST (redacted; core [R57]: CoT may carry reasoned-about secrets — TRACE_THINKING gates
+     *  capture). The `text` row is stamped with the turn's first text eventId (E18 per-message resume handle,
+     *  additive/tolerate-absent). Buffers clear only AFTER a successful write (a failed write drops nothing). */
     flush(): Promise<void>;
+    /** The shared stream-switch projection (all non-terminal events). `done` / `message_committed` / unknown
+     *  future types are no-ops (whitelist discipline — never a raw spread into the ledger). */
     onEvent(ev: {
         type: string;
     }): Promise<void>;
+    /** Forward-sink (subagent) events → ledger, bg-leg posture: fire-and-forget with SYNCHRONOUS seq allocation
+     *  (sink-vs-loop appends get unique seqs), same whitelist+redact builders (forwarded events are UNTRUSTED
+     *  RAW — §E1). Child text/reasoning deltas are deliberately NOT persisted per-chunk (a child's turn text has
+     *  no durable turn row; the tool cards + task_progress ticks are the durable projection). */
     onForwardEvent(e: {
         type?: string;
     }): void;
+    /** Park event (durable F4 suspend / design/80 D-B review pause): ONLY the non-secret `checkpointGate` is
+     *  persisted — never the capability `checkpointToken` (search [18] Q1b). */
     appendParked(kind: "suspended" | "needs_review", result: unknown): Promise<void>;
+    /** Terminal `done` event. `result` must already be checkpoint-token-stripped (and, on the bg leg,
+     *  model-usage-attached) by the caller. */
     appendDone(result: unknown): Promise<void>;
+    /** Convenience for the sync detach lane (no model-usage interleave there): flush, then project the result
+     *  to its park/terminal event exactly like the bg leg's done case. `result` must already be stripped. */
     onDone(result: {
         status?: string;
     }): Promise<void>;
 }
 export declare function createLedgerSink(opts: {
+    /** The seq-stamped durable append — typically `(seq, type, data) => runStore.appendEvent(taskId, seq, type, data)`. */
     appendEvent: (seq: number, type: string, data: unknown) => Promise<void>;
+    /** TRACE_THINKING gate: reasoning deltas are buffered (later redacted+persisted) only when true (core [R57] —
+     *  persisting CoT is a deployment decision). Both legs pass the SAME config source (`config.traceThinking`). */
     persistThinking: boolean;
+    /** task_notification dedup ledger (core [784]④a seq-folded keys). The bg leg passes its per-leg instance
+     *  (shared with its observer/drain arms so no arm double-appends a key another arm delivered); a leg with no
+     *  other durable arms (sync detach lane) omits it and gets a private instance. */
     notifiedKeys?: NotifiedKeys;
 }): LedgerSink;
 //# sourceMappingURL=ledger-sink.d.ts.map