@sema-agent/server 1.322.0 → 2.0.0

package/dist/trace/project.js

@@ -1,19 +1,32 @@
 import { redactSecrets, redactDeep } from "./redact.js";
+/** E8 (shell-host): drain the per-task model-usage accumulator into an append-only `model_usage` DELTA event.
+ *  Shared by BOTH durable-write legs (runInBackground + the resume leg) so the persisted shape never drifts; the
+ *  append-only deltas make a suspended/resumed run's total resume-safe (each leg appends its own, the echo sums). */
 export async function appendModelUsageDelta(append, modelUsage, taskId) {
     const delta = modelUsage?.drain(taskId);
     if (delta)
         await append("model_usage", { usage: delta });
 }
+/** [998]② drain the pending prompt-manifest records (whitelisted at RECORD time, budget.ts — ids/digests/
+ *  counts only, no prompt bodies by core's manifest contract) into durable `prompt_assembled` events, one per
+ *  prepare IN EMISSION ORDER (a cascade/verify leg re-prepares under one taskId — every rung's manifest
+ *  persists; release-review finding). Shared by both durable-write legs; a no-op when nothing is pending
+ *  (one Map.get), so callers fire it liberally. */
 export async function appendPromptManifest(append, tracker, taskId) {
     const records = tracker?.drain(taskId);
     if (records)
         for (const m of records)
             await append("prompt_assembled", m);
+    // [1301]③:config.assembled 同拍同门落 durable(config_assembled 事件)——与 prompt_assembled 完全同
+    // 生命周期(register 门/lease clear/所有 drain 落点自动覆盖:bg 首跑、resume 两径、verify 径);
+    // 逐条保序(codex F2:cascade 每 rung 的生效配置各自成帧,与其 prompt manifest 可配对)。
     const cfgs = tracker?.drainConfig?.(taskId);
     if (cfgs)
         for (const cfg of cfgs)
             await append("config_assembled", cfg);
 }
+/** E8: at a TERMINAL done — flush the final delta, then SUM all `model_usage` events (every process leg) into the
+ *  result's `stats.modelUsage` echo. Returns the result unchanged when no usage was tracked (shell soft-degrades). */
 export async function attachModelUsage(result, ctx) {
     if (!ctx.modelUsage)
         return result;
@@ -23,6 +36,10 @@ export async function attachModelUsage(result, ctx) {
         return result;
     return { ...result, stats: { ...result.stats, modelUsage: usage } };
 }
+/** E8 (shell-host contract): SUM the per-turn `model_usage` delta events in a run's durable event log into the
+ *  cumulative per-model total for `TaskStats.modelUsage`. The tracer drains deltas at each turn boundary
+ *  (append-only) → this is resume-safe: it sums across ALL process legs of a suspended/resumed run. Returns
+ *  undefined when the run logged no model usage (→ the shell soft-degrades to aggregate cost only). */
 export function aggregateModelUsage(events) {
     const total = {};
     let any = false;
@@ -45,15 +62,31 @@ export function aggregateModelUsage(events) {
     }
     return any ? total : undefined;
 }
+/** Identity fields core stamps on each content event (1.121.0 `TaskEventIdentity`, shell-host contract E2):
+ *  `eventId` (core-mint uuidv7, the stable handle for dedup / the E18 resume-at anchor) + `parentToolCallId`
+ *  (present only when the run is a sub-agent task spawned under a parent tool call). Both additive / tolerate-absent. */
 function identityFields(src) {
     return {
         ...(src.eventId ? { eventId: String(src.eventId) } : {}),
         ...(src.parentToolCallId ? { parentToolCallId: String(src.parentToolCallId) } : {}),
     };
 }
+/** The durable `tool_start` event payload, shared by BOTH append sites (runInBackground + the resume leg) so the
+ *  persisted shape never drifts: redacted args (UNTRUSTED) + E2 identity. `label`([1543]§三族B:durable 腿
+ *  此前剥掉——同一 run live 观看有展示名、replay/resume 退化成 wire 名):core 展示名 verbatim(tail 面
+ *  1.251 复审同裁,两腿同处理)。 */
 export function toolStartEventData(ev) {
     return { toolCallId: ev.toolCallId, toolName: ev.toolName, ...(ev.label !== undefined ? { label: ev.label } : {}), args: redactDeep(ev.args), ...identityFields(ev) };
 }
+/** The durable `tool_end` payload (shared by both append sites). E1: the model-facing `output` is UNTRUSTED RAW
+ *  from core (file/shell/API bodies) — core only SIZE-bounds it (`truncated`), REDACTION is ours (same contract as
+ *  `tool_start.args`); never re-fed to a model. E2: identity. Absent `output` ⇒ the tool produced no content body.
+ *  core 1.203: `structured` = the tool's CC-shaped `details` card (edit/create/bash/… — core
+ *  allowlists the card `type` and size-caps the whole card, omit-whole on overflow, so a subagent's child-TaskResult
+ *  can never appear here) — SAME UNTRUSTED RAW contract as `output` (a card carries `originalFile`/stdout bodies),
+ *  so it gets the same deep redaction before it is persisted or echoed. `label`(core 展示名,同 tool_start 的
+ *  label 待遇 verbatim)白名单排查(2026-07-24)补齐进函数本体——此前外包给调用点各自手动拼接,7 处只有
+ *  3 处记得拼,resume leg + ledger-sink 落盘两处漏了,持久化记录本身缺 label 一写盘就永久追不回来。 */
 export function toolEndEventData(ev) {
     return {
         toolCallId: ev.toolCallId,
@@ -62,41 +95,95 @@ export function toolEndEventData(ev) {
         isError: ev.isError,
         ...(ev.output !== undefined ? { output: redactDeep(ev.output) } : {}),
         ...(ev.truncated ? { truncated: true } : {}),
+        // core 1.442([1898] RB-210):截断诚实体量(各 block 真实大小之和,不含 JSON 包装开销)。
         ...(Number.isFinite(ev.totalChars) ? { totalChars: ev.totalChars } : {}),
         ...(ev.structured !== undefined ? { structured: redactDeep(ev.structured) } : {}),
         ...identityFields(ev),
     };
 }
+/** The `task_progress` payload (a subagent's live progress tick) — EXPLICIT WHITELIST shared by all
+ *  three legs (bg runs.ts + resume append + the sync live SSE frame): taskId/parent linkage/token rollup verbatim,
+ *  `name` UNTRUSTED (core sanitizes for rendering, does NOT secret-redact — a taskName can be secret-shaped) →
+ *  `redactSecrets`. Never the delegated objective/args. E2 identity rides (eventId/
+ *  parentToolCallId are core-mint uuidv7 identifiers, not content — consumers bind concurrent subagent ticks
+ *  exactly by them; the 1.72 whitelist dropped them, leaving a FIFO heuristic). */
 export function taskProgressEventData(ev) {
     return {
         taskId: ev.taskId,
         ...(ev.parentTaskId ? { parentTaskId: ev.parentTaskId } : {}),
         ...(ev.name ? { name: redactSecrets(ev.name) } : {}),
+        // core [1414]#3 settle 终态 tick("completed"/"failed"——[1543]§三族B:此前被剥,消费方只见最后
+        // 一拍 running 后行消失,恰是该 tick 要修的体验)。core enum verbatim。
         ...(ev.status !== undefined ? { status: ev.status } : {}),
         ...(ev.usage ? { usage: ev.usage } : {}),
+        // core 1.262.0: the child's most recent tool intent as one human line ("Bash npm
+        // test") — derived from the child's tool_start (tool name + argument head), so the ARGUMENT part is
+        // UNTRUSTED free text (a command line can be secret-shaped) → `redactSecrets`, same boundary as `name`.
         ...(ev.currentAction ? { currentAction: redactSecrets(ev.currentAction) } : {}),
+        // core 1.401.0([1611]→[1616]/[1617] 方案 B):后台 workflow 子代的 tick additive 带这两个字段,
+        // 让下游(cli)能把这条前台裸 uuid 行识别为"fleet 那边已有一份"从而跳过重复渲染。workflowRunId 是
+        // core-mint 的不透明 run id(不含用户内容)→ 同 identityFields 待遇直传;workflowAgentLabel 是脚本
+        // 作者可控的展示字符串(UNTRUSTED,同 name 的信任边界)→ redactSecrets。
         ...(ev.workflowRunId ? { workflowRunId: ev.workflowRunId } : {}),
         ...(ev.workflowAgentLabel ? { workflowAgentLabel: redactSecrets(ev.workflowAgentLabel) } : {}),
         ...identityFields(ev),
     };
 }
+/** The `task_notification` payload (core 1.202 design/115 P2: a background task finished — this event is the
+ *  LEDGER/display projection of the OBSERVED terminal state, emitted the moment core observes it. It does NOT
+ *  attest that the `<task-notification>` XML has entered the model context: core's steer targets the NEXT TURN
+ *  BOUNDARY (design/116 §7 — turn 在飞时不注入), so the frame can precede actual injection by minutes ([1818]
+ *  clay live: 3m54s; the previous wording here — "core already injected in-process" — was the same wrong
+ *  assumption that broke the shell's dedup). `injected: false` says exactly that on the wire: a consumer must
+ *  NOT treat this frame as an echo of model-context injection. EXPLICIT WHITELIST (never `{...ev}` — the 1.72 task_progress lesson: a
+ *  future core field must not ride raw): ids/status/usage verbatim; `summary`/`result`/`output_file` are UNTRUSTED
+ *  free text (core bounds+sanitizes for XML, does NOT secret-redact) → `redactSecrets` at OUR wire boundary. Shared
+ *  by all three legs (bg runs.ts + resume append + the sync live SSE frame) so the shape never drifts. Takes the
+ *  EVENT (not just the payload) so the E2 identity fields core stamps on it (eventId/parentToolCallId) ride the
+ *  frame like every other content event (review round 2: the payload-only version silently dropped them). */
 export function taskNotificationEventData(ev) {
     const n = ev.notification;
     return {
+        // [1818]§四 (b)案:显式判别位 —— 本帧=台账观测,不证已入模型上下文(见 docstring)。恒 false 是
+        // 如实声明:server 观测不到 core 的 turn 边界注入时刻;若未来 core 给出注入回声 seam,echo 帧以
+        // injected:true 骑同帧族。
         injected: false,
         task_id: n.task_id,
         task_type: n.task_type,
+        // core 1.238: the child's sessionId — the stable a*↔uuid cross-system anchor (the killed
+        // receipt renders off summary+sessionId). Optional (bash lane has none).
         ...(n.sessionId !== undefined ? { sessionId: n.sessionId } : {}),
         ...(n.toolUseId !== undefined ? { toolUseId: n.toolUseId } : {}),
         status: n.status,
+        // The design/135 Monitor + design/134 stoppedBy fields were MISSING
+        // from this whitelist — the shell had no dedup discriminator (`seq` is what keeps successive Monitor event
+        // batches from collapsing into one, per core's taskNotificationDedupKey) and no batched line text / stop
+        // attribution. `seq` is a core counter (verbatim); `lines` is watched-process stdout = UNTRUSTED free text
+        // (redact each line, same boundary as result); `stoppedBy` is core's OPEN enum (verbatim string — consumers
+        // tolerate unknown values by contract).
         ...(n.seq !== undefined ? { seq: n.seq } : {}),
         ...(n.lines !== undefined ? { lines: n.lines.map((l) => redactSecrets(l)) } : {}),
         ...(n.stoppedBy !== undefined ? { stoppedBy: n.stoppedBy } : {}),
+        // P1-3(core 1.452):完成幂等锚 verbatim(消费端跨通路去重;[1925] 一轮批)。
         ...(n.completionId !== undefined ? { completionId: n.completionId } : {}),
+        // [1543]§二 server①:白名单滞后 core payload 四键补齐——
+        //   source:external 通知来源标(caller 供 = UNTRUSTED)→ redactSecrets;
+        //   exitCode:数值 verbatim(bash 腿);
+        //   partial:boolean verbatim——**killed 残果诚实标**(缺它 cli 把残果渲染得像完整结果,core
+        //   特意打的标到不了用户面,本键是四键里的主案);
+        //   diagnostics:[1409] 教学文本 = UNTRUSTED 自由文本 → redactSecrets。
         ...(n.source !== undefined ? { source: redactSecrets(n.source) } : {}),
         ...(n.exitCode !== undefined ? { exitCode: n.exitCode } : {}),
         ...(n.partial !== undefined ? { partial: n.partial } : {}),
         ...(n.diagnostics !== undefined ? { diagnostics: redactSecrets(n.diagnostics) } : {}),
+        // core 1.262.0 五个补面——additive passthrough, same posture as
+        // lines/stoppedBy above. Fields PICKED (never spread — a future core field must not ride raw):
+        //   recentSteps: `tool` = core tool name (verbatim); `target` (file path / command / pattern) and
+        //   `outcome` (tool result first line) are UNTRUSTED free text (a command or output line can be
+        //   secret-shaped) → `redactSecrets`, same boundary as `result`/`lines`. Bounded upstream (≤10).
+        //   editedFiles: `path` is engine working-file derived but still crosses our wire → `redactSecrets`
+        //   (the compacted attachedFiles posture); `edits` numeric verbatim.
+        //   resumable: core boolean verbatim (E — parent decides continue-vs-restart without trial-and-error).
         ...(n.recentSteps !== undefined
             ? { recentSteps: n.recentSteps.map((s) => ({ tool: s.tool, target: redactSecrets(s.target), outcome: redactSecrets(s.outcome) })) }
             : {}),
@@ -109,6 +196,18 @@ export function taskNotificationEventData(ev) {
         ...identityFields(ev),
     };
 }
+/** The `compacted` payload — EXPLICIT WHITELIST shared by all three legs (bg runs.ts + resume append + the sync
+ *  live SSE frame; the 1.72 task_progress lesson: never `{...ev}`). trigger/tokensBefore (MF-18) verbatim;
+ *  `preserved_segment.firstKeptEntryId` verbatim (a core-mint entryId, the shell's compaction-divider anchor);
+ *  core 1.219 `attachedFiles` (attachWorkingFiles default-ON — the shell renders CC's post-compact `Read {path}`
+ *  cards from it): `path` is the engine's own working-file path (env-derived, not free text) but still crosses our
+ *  wire → `redactSecrets` (a project path can embed a secret-shaped dir name); chars/truncated are numeric/bool
+ *  verbatim. Absent fields stay absent (feature off / nothing attached / no kept-tail floor). */
+/** The `diagnostics` payload (core 1.220 design/121 — NEW LSP diagnostics drained at a turn boundary; the model
+ *  already got the `<new-diagnostics>` context message in-process, this frame is the shell's render source).
+ *  EXPLICIT WHITELIST shared by all three legs. UNTRUSTED RAW (§E1: language-server output over workspace files —
+ *  a diagnostic message can quote file content, a secret-shaped uri/source is possible) → `redactSecrets` on the
+ *  string fields; severity/range/code numbers verbatim. E2 identity rides. */
 export function diagnosticsEventData(ev) {
     return {
         files: (Array.isArray(ev.files) ? ev.files : []).map((f) => ({
@@ -125,6 +224,11 @@ export function diagnosticsEventData(ev) {
         ...identityFields(ev),
     };
 }
+/** The `steering_injected` payload([1550]/[1552] 裁定透传;core `TaskEvent` 联合臂 `type: "steering_injected"`,
+ *  shell 渲染源 = CC 的系统提醒条:core 在 turn 之间给模型注入一条系统提示[todo 提醒/文件变化/日期跨天/
+ *  技能列表变化…]时随手抛的展示投影,一附件一帧)。EXPLICIT WHITELIST(source=封闭枚举 verbatim;
+ *  preview=注入文本的展示摘录,UNTRUSTED[core 未做秘密脱敏]→ `redactSecrets`)。共享三腿(sync 实时 SSE +
+ *  bg/resume 落账,ledger-sink 同门)。 */
 export function steeringInjectedEventData(ev) {
     return {
         source: String(ev.source),
@@ -132,12 +236,22 @@ export function steeringInjectedEventData(ev) {
         ...identityFields(ev),
     };
 }
+/** The `workspace_changed` payload([1559]二 core 裁定:design/99 §E13 旧臂,L1 门本车首次撞见——非新增,
+ *  是本门扩 TaskEvent 臂集时第一次显式处置。语义 = bash `cd`/EnterWorktree 移动任务逻辑 cwd 后,在移动
+ *  它的工具结算后发一帧,给 shell/宿主 UI 一个路径提示行。cwd 与已展示的工具 args 同信任级[UNTRUSTED,
+ *  RAW 逻辑路径,symlink 不解析]→ `redactSecrets` + 长度 bound[300,与 brainStatusEventData.detail 同
+ *  惯例]。core 只在真变化时才发(不播初始 cwd);渲染面（cli）不得当持久态——跨 suspend/resume 重置为
+ *  根，这是消费端纪律，服务端只如实转发单帧不做状态缓存。 */
 export function workspaceChangedEventData(ev) {
     return {
         cwd: redactSecrets(String(ev.cwd)).slice(0, 300),
         ...identityFields(ev),
     };
 }
+/** S4 (SILENT-FALLBACK P0-a): the durable `brain_status` observation row, shared by the bg + resume append
+ *  sites. core marks the live `status` frame EPHEMERAL (never replayed by core on resume) — this row is the
+ *  SERVICE's own observation record (why a turn stalled: rate_limited/retrying/reconnecting/circuit_open),
+ *  not a core event replay. Whitelist: the closed phase union + neutral bounded detail (redacted) + retryInSec. */
 export function brainStatusEventData(ev) {
     return {
         phase: String(ev.phase),
@@ -147,7 +261,12 @@ export function brainStatusEventData(ev) {
     };
 }
 export function compactedEventData(ev) {
+    // Bounded-numeric guard for the 1.289 additive scalars: finite numbers verbatim, anything else absent
+    // (whitelist discipline — a malformed field must not ride the wire, same class as the 1.72 lesson).
     const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+    // core 1.289 `phaseDurations` (CompactionPhaseDurations: prepareMs/summaryMs?/persistMs/ptlRetries) — a
+    // CLOSED numeric struct rebuilt field-by-field (never `{...ev.phaseDurations}`: an unexpected extra key must
+    // not leak onto the wire); non-numeric members are dropped, an all-empty struct stays absent.
     const phaseDurations = (() => {
         const p = ev.phaseDurations;
         if (!p || typeof p !== "object")
@@ -161,6 +280,14 @@ export function compactedEventData(ev) {
         return Object.keys(out).length > 0 ? out : undefined;
     })();
     return {
+        // 🔴 2026-07-25:这三处此前**违反本函数注释自己写的那条不变量**(「畸形字段不得上线,与 1.72 同类」)——
+        //   ① `trigger`/`tokensBefore` 是**裸赋值**:`tokensBefore` 为 `NaN` 时 `JSON.stringify` 把它变成 **`null`**,
+        //      于是压缩面板渲染成「压缩前 0 tokens」而不是「未知」;裸赋值还会留下 present-with-undefined 的键
+        //      (JSON 会丢,但非 JSON 后端的进程内读者看得到)⇒ 统一走 `num()`/类型判据 + 条件 spread。
+        //   ② `attachedFiles` 的元素**逐字段照抄**:一个畸形元素(如 `{}`)会被**造成**
+        //      `{path:"undefined", chars:undefined, truncated:undefined}` —— 那是**编造值**,比丢弃更坏
+        //      (下游看到一个叫 "undefined" 的文件路径)。改成**逐元素校验后丢弃畸形项**,全丢光则整键省略
+        //      (与既有的 `length > 0` 同口径)。
         ...(typeof ev.trigger === "string" ? { trigger: ev.trigger } : {}),
         ...(num(ev.tokensBefore) !== undefined ? { tokensBefore: num(ev.tokensBefore) } : {}),
         ...(ev.preserved_segment?.firstKeptEntryId ? { preserved_segment: { firstKeptEntryId: ev.preserved_segment.firstKeptEntryId } } : {}),
@@ -173,16 +300,35 @@ export function compactedEventData(ev) {
                 .map((f) => ({ path: redactSecrets(f.path), chars: f.chars, truncated: f.truncated }));
             return files.length > 0 ? { attachedFiles: files } : {};
         })(),
+        // core 1.286 additive fields ([792]②b, design/145 compression batch): modelFallback/fallbackReason = the
+        // compaction summarizer fell back to a larger-window model; clampedRatio/clampReason = the keep ratio was
+        // clamped and why. Closed literal bool/enum/number — verbatim; absent stays absent.
         ...(ev.modelFallback === true ? { modelFallback: true } : {}),
         ...(ev.fallbackReason !== undefined ? { fallbackReason: ev.fallbackReason } : {}),
-        ...(num(ev.clampedRatio) !== undefined ? { clampedRatio: num(ev.clampedRatio) } : {}),
+        ...(num(ev.clampedRatio) !== undefined ? { clampedRatio: num(ev.clampedRatio) } : {}), // 同上:NaN 不得以 null 上线
         ...(ev.clampReason !== undefined ? { clampReason: ev.clampReason } : {}),
+        // core 1.289 additive fields (codex F7 — parity batch, same posture as [792]②b above): tokensAfter/
+        // triggerTokensBefore/durationMs are engine-derived scalars, verbatim when finite numbers; phaseDurations
+        // is the closed bounded struct built above. Absent stays absent on all three wire legs (bg runs.ts append,
+        // the resume append, and the sync live SSE frame — all funnel through THIS builder).
         ...(num(ev.tokensAfter) !== undefined ? { tokensAfter: num(ev.tokensAfter) } : {}),
         ...(num(ev.triggerTokensBefore) !== undefined ? { triggerTokensBefore: num(ev.triggerTokensBefore) } : {}),
         ...(num(ev.durationMs) !== undefined ? { durationMs: num(ev.durationMs) } : {}),
         ...(phaseDurations !== undefined ? { phaseDurations } : {}),
     };
 }
+/**
+ * `context_usage` 的白名单投影(core 1.414 新增一等 `TaskEvent` 分支;server [1669]⑥ 点名要的上下文用量面)。
+ *
+ * 🔴 两条 core 明确交代的口径,必须原样传下去、不要在服务端"聪明地"重算:
+ *  · `usedTokens > compactAtTokens` **就是引擎自己喂 `shouldCompact` 的谓词** —— 消费方直接用,别重新推导阈值。
+ *  · `windowTokens` 是 **autocompact 窗**,**不是**「模型上下文大小」(模型声明 `autoCompactTokens` 时物理请求
+ *    窗更大)。渲染成"模型上下文"会给用户一个错的分母。
+ * ⚠️ 它在**每个压缩边界**上报(不只压缩真发生时),所以一次任务里会有多条 —— 消费方按最后一条取当前值。
+ * ⚠️ 它**没有**挂在 `turn_end.usage` 上(core 解释:边界检查跑在 turn_end 之后、对 flush 后的消息集,
+ *    挂那儿会是"另一次更早的测量顶着同一个名字")。去 turn_end 找是找不到的。
+ * 三个字段都是引擎派生的有限数标量 ⇒ 走 finite 门(与 compacted 的 1.289 标量同姿势),非有限即缺席。
+ */
 export function contextUsageEventData(ev) {
     const n = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
     return {
@@ -191,6 +337,15 @@ export function contextUsageEventData(ev) {
         ...(n(ev.compactAtTokens) !== undefined ? { compactAtTokens: n(ev.compactAtTokens) } : {}),
     };
 }
+/**
+ * `turn_end` 的白名单投影 —— 🔴 2026-07-25 补:`turn_end` 此前是**唯一没有 builder 的内容臂**,两条持久化点
+ * (ledger-sink 与 resume 腿)各自手写 `{ usage }`,于是 core 的另两个字段被静默剥掉:
+ *   · `stopReason` —— **这一轮为什么停**(max_tokens / stop_sequence / …);
+ *   · `usageMissing: true` —— **用量不可信**的诚实标记。缺了它,"没有 usage"会被读成"用量是 0",
+ *     而不是"未知";这正是那种"回放后看起来一切正常"的丢失。
+ * 两者**在 live 腿看得见、durable 腿回放后永久消失** —— 与 [1622] 的 `label`、[1611] 的 workflowRunId 同一族
+ * (白名单没跟上 core 新增字段)。补 builder 的同时也就把它纳入了 `wire-whitelist-exhaustiveness` 的编译期差集门。
+ */
 export function turnEndEventData(ev) {
     return {
         ...(ev.usage ? { usage: ev.usage } : {}),
@@ -198,6 +353,8 @@ export function turnEndEventData(ev) {
         ...(typeof ev.stopReason === "string" ? { stopReason: ev.stopReason } : {}),
     };
 }
+/** Map core's `turn_end.usage` (1.76 / core [R59]: inputTokens/outputTokens/cacheReadTokens/cacheWriteTokens/
+ *  costMicroUsd) → the contract's `TraceTurn.tokens {in,out,cacheRead?,cacheWrite?}`. Absent/empty → undefined. */
 export function toContractTokens(usage) {
     if (!usage || typeof usage !== "object")
         return undefined;
@@ -211,6 +368,7 @@ export function toContractTokens(usage) {
         ...(u.cacheWriteTokens != null ? { cacheWrite: u.cacheWriteTokens } : {}),
     };
 }
+/** Project a per-task event slice (seq-ascending) into ordered `TraceTurn[]`. Pure + total (never throws). */
 export function projectEvents(events, opts = {}) {
     const turns = [];
     if (opts.objective) {
@@ -242,10 +400,16 @@ export function projectEvents(events, opts = {}) {
                 break;
             case "tool_end": {
                 const callId = String(d.toolCallId ?? "");
+                // E1: output is read straight off the (already-redacted-at-append) event — no session join. Absent ⇒ undefined.
+                // `structured` (core 1.203 CC card) was redacted at APPEND (toolEndEventData) — passthrough on the read
+                // path so a cold-replay/turns consumer renders the same rich card the live wire carried (additive field).
                 blocks.push({ type: "tool-result", callId, ...(typeof d.label === "string" ? { label: d.label } : {}), output: d.output, ...(d.isError ? { isError: true } : {}), ...(d.truncated ? { truncated: true } : {}), ...(Number.isFinite(d.totalChars) ? { totalChars: d.totalChars } : {}), ...(d.structured !== undefined ? { structured: d.structured } : {}), ...identityFields(d) });
                 break;
             }
             case "prompt_assembled":
+                // [998]②: whitelisted at APPEND (budget.ts promptManifestRecordOf — ids/digests/counts only);
+                // passthrough on the read path (the `structured` posture). Lands ahead of the turn's first content
+                // block, so the "Prompt 组成" card renders at the top of the turn it prepared.
                 firstTs ??= ev.ts;
                 blocks.push({
                     type: "prompt-assembled",
@@ -259,14 +423,17 @@ export function projectEvents(events, opts = {}) {
             case "turn_end":
                 flushTurn(ev.seq, ev.ts, toContractTokens(d.usage));
                 break;
+            // compacted / done / suspended / failed are lifecycle, not turn output — status comes from the run record.
         }
     }
+    // A trailing in-progress turn (events after the last turn_end — e.g. a live task mid-turn).
     if (blocks.length > 0) {
         const last = events[events.length - 1];
         flushTurn(last.seq, last.ts);
     }
     return turns;
 }
+/** Structured `lastStep` (contract 2.1) from the latest event — UI maps an icon, never free text. */
 export function lastStep(latestEventType, status) {
     if (status !== "running")
         return { type: "idle" };
@@ -281,6 +448,8 @@ export function lastStep(latestEventType, status) {
             return { type: "responding" };
     }
 }
+/** A run record → the cheap list summary (contract 2.1). Token/cost/turns come from the terminal result.stats;
+ *  scenario isn't denormalized on the run row (omitted — a later push-index/column refinement). */
 export function taskSummary(run, latestEventType) {
     const stats = (run.result?.stats ?? {});
     const terminal = run.status !== "running";
@@ -299,9 +468,23 @@ export function taskSummary(run, latestEventType) {
         lastStep: lastStep(latestEventType, run.status),
     };
 }
+/** design/158 B2(lens4 N8)—— 重放边界的**读旧**归一:把历史账本里的 `brain_status` 行改叫 `status`。
+ *
+ *  同一条「大脑存活性」观测曾在两条腿上叫两个名字:live 腿(`POST /v1/tasks/stream`)发 `type:"status"`,
+ *  durable 腿的账本行落 `brain_status`,而 SDK 的公开 `AgentEvent` 联合**只有** `status` —— 于是走
+ *  `GET /v1/runs/:id/events` 的消费端会收到一个公开联合之外的帧(穷举式 closed-oneOf 消费者当场抛)。
+ *
+ *  写入侧已经改叫 `status`(ledger-sink.ts 与 resume 腿的 append 两处),但**存量行救不了**:任何
+ *  <1.317 的部署账本里都躺着 `brain_status` 行,重放它们仍会漏出旧名。所以「写新」必须配一个「读旧」——
+ *  这个函数就是那个读边界,唯一调用点是 task_run SSE 的 `formatEvent`(routes/runs.ts)。
+ *
+ *  🔴 刻意**只**认这一个键,不做成映射表:帧名归一是历史包袱的一次性偿还,不是一条可以长胖的兼容层。
+ *  再有第二个名字对不齐,应当在源头修,而不是往这里加一行。 */
 export function normalizeRunEventType(type) {
     return type === "brain_status" ? "status" : type;
 }
+/** Map one durable event → a sema-registry SSE trace event (contract 2.3). null = not a client event. The
+ *  durable log is block-grained, so each block ships as one "delta" the client appends (stream mode = "delta"). */
 export function mapTraceEvent(type, seq, data) {
     switch (type) {
         case "reasoning":
@@ -311,21 +494,25 @@ export function mapTraceEvent(type, seq, data) {
         case "tool_start":
             return { event: "tool-call", data: { seq, id: data.toolCallId, name: data.toolName, ...(typeof data.label === "string" ? { label: data.label } : {}), input: data.args, ...identityFields(data) } };
         case "tool_end":
+            // E1: output/truncated are already redacted+bounded at append; pass through. E2: identity additive.
             return { event: "tool-result", data: { seq, callId: data.toolCallId, ...(typeof data.label === "string" ? { label: data.label } : {}), isError: Boolean(data.isError), ...(data.output !== undefined ? { output: data.output } : {}), ...(data.truncated ? { truncated: true } : {}), ...(Number.isFinite(data.totalChars) ? { totalChars: data.totalChars } : {}), ...(data.structured !== undefined ? { structured: data.structured } : {}), ...identityFields(data) } };
         case "turn_end": {
             const tokens = toContractTokens(data.usage);
             return { event: "turn", data: { seq, ...(tokens ? { tokens } : {}) } };
         }
         case "prompt_assembled":
+            // [998]②: whitelisted at append (ids/digests/counts, no prompt bodies) — passthrough, own event name.
             return { event: "prompt-assembled", data: { seq, ...data } };
         case "done":
             return { event: "done", data: { seq } };
         case "suspended":
             return { event: "done", data: { seq, suspended: true } };
         case "failed":
+            // BL-13: redact at the read boundary too (defense-in-depth) — covers any errorMessage that reached the
+            // log un-redacted via another write path; idempotent on the BL-12-redacted catch-path message.
             return { event: "error", data: { code: "WORKER_DOWN", message: redactSecrets(String(data.errorMessage ?? "run failed")) } };
         default:
-            return null;
+            return null; // compacted etc. — not a client trace event
     }
 }
 //# sourceMappingURL=project.js.map

package/dist/trace/redact.d.ts

@@ -1,5 +1,24 @@
 export declare function setRedactionObserver(fn: ((patternLabel: string, count: number) => void) | undefined): void;
 export declare function redactSecrets(text: string): string;
+/**
+ * 🔴 环 + 深度预算(2026-07-25 补)。原实现是纯递归、**既不记已访问节点也不限深度**,而它的调用位置是
+ * **最不可信的边界**:`toolStart`/`toolEnd` 把工具的 `args`/`output`/`structured` 直接喂进来。后果两条:
+ *   · **循环引用** ⇒ 无限递归 ⇒ `RangeError` **抛出构造函数**。在 sync 的 SSE 腿上那个 throw 就落在
+ *     `for await (…) res.write(…)` 的循环里 ⇒ **一个畸形工具输出能打死一条正在跑的流**;在 ledger-sink 腿上
+ *     则是那一帧 append 直接失败(事件永久不落盘)。
+ *   · 超深嵌套 ⇒ 同样爆栈。
+ * 同文件的 `redactedPreview` 的文档里早把这条记成"已复审的 MEDIUM"并**绕开** redactDeep ——
+ * 也就是说这个洞是知道的,只是没堵。现在堵在 redactDeep 本体:环与超深都换成**可见的标记**,
+ * 让下游看到"这里有东西被省略了",而不是丢一个空对象或炸掉整条流。
+ */
 export declare function redactDeep(value: unknown): unknown;
+/**
+ * A REDACTED, length-BOUNDED string preview of a structured value — for surfacing a pending tool call's `args`
+ * in the assistant inbox ("what is this ask about") WITHOUT leaking secrets or dumping an unbounded payload (a
+ * write_file `content` can be megabytes). {@link redactDeep} scrubs secret-shaped strings first; the result is
+ * JSON-stringified and capped (truncation is marked). `null`/`undefined` → `null` (nothing to preview). Defense
+ * in depth: the redaction is conservative (NOT exhaustive — see {@link redactSecrets}); the inbox is already
+ * owner-scoped, so this preview is only ever shown to the ask's own principal (or an operator inspecting it).
+ */
 export declare function redactedPreview(value: unknown, cap?: number): string | null;
 //# sourceMappingURL=redact.d.ts.map

package/dist/trace/redact.js

@@ -1,15 +1,33 @@
+/**
+ * Trace thinking-block redaction (service-side). Per core [R57]: the agent's reasoning/CoT is emitted on the
+ * live TaskEvent stream but DELIBERATELY kept out of the metadata Tracer because CoT may contain reasoned-about
+ * secrets (and is large / ToS-sensitive for some providers). Persisting it for the trace UI is the deployment's
+ * call — so when we DO persist it, redact unambiguous secret formats first. Conservative on purpose: only clear
+ * key/token shapes are redacted. ⚠️ It is NOT exhaustive: unrecognised secret formats (a free-text password,
+ * a JWT) pass through, and the broad `Bearer <20+ chars>` rule can over-match legitimate CoT (false positives
+ * tolerated — over-redacting trace text is safe). For sensitive deployments, disable thinking capture entirely
+ * via TRACE_THINKING=false. This is a seam — deployments can extend the patterns.
+ */
 const SECRET_PATTERNS = [
-    [/-----BEGIN[^-]+PRIVATE KEY(?: BLOCK)?-----[\s\S]{0,8192}?-----END[^-]+PRIVATE KEY(?: BLOCK)?-----/g, "«redacted:private-key»"],
-    [/\bsk-[A-Za-z0-9_-]{16,}\b/g, "«redacted:key»"],
-    [/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g, "«redacted:gh-token»"],
-    [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, "«redacted:slack-token»"],
-    [/\bAKIA[0-9A-Z]{16}\b/g, "«redacted:aws-key»"],
-    [/\b[Bb]earer\s+[A-Za-z0-9._~+/-]{20,}=*/g, "Bearer «redacted»"],
-    [/\bBasic\s+[A-Za-z0-9+/]{16,}={0,2}/g, "Basic «redacted»"],
+    [/-----BEGIN[^-]+PRIVATE KEY(?: BLOCK)?-----[\s\S]{0,8192}?-----END[^-]+PRIVATE KEY(?: BLOCK)?-----/g, "«redacted:private-key»"], // bounded body (council #8: avoid backtracking on fence-heavy input). `( BLOCK)?` covers PGP-armored keys `-----BEGIN PGP PRIVATE KEY BLOCK-----` where 'BLOCK' sits between 'PRIVATE KEY' and the dashes (L5 corpus caught the leak — same class as core's 1.108.1 PGP regression).
+    [/\bsk-[A-Za-z0-9_-]{16,}\b/g, "«redacted:key»"], // OpenAI / DeepSeek-style keys
+    [/\b(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}\b/g, "«redacted:gh-token»"], // GitHub tokens
+    [/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, "«redacted:slack-token»"], // Slack tokens
+    [/\bAKIA[0-9A-Z]{16}\b/g, "«redacted:aws-key»"], // AWS access key id
+    [/\b[Bb]earer\s+[A-Za-z0-9._~+/-]{20,}=*/g, "Bearer «redacted»"], // bearer auth tokens
+    [/\bBasic\s+[A-Za-z0-9+/]{16,}={0,2}/g, "Basic «redacted»"], // HTTP Basic auth (base64 creds)
+    // BL-5: credentials embedded in a clone/push URL (`scheme://user:PASS@host`) — keep scheme+user, drop the
+    // password. Port-only URLs (`host:9999/path`, no `@`) don't match (the userinfo `:pass@` is required).
     [/\b([A-Za-z][A-Za-z0-9+.-]*:\/\/[^/@\s:]+):[^/@\s]+@/g, "$1:«redacted»@"],
+    // BL-5: Gitea / PAT `Authorization: token <hex>` scheme (the Bearer/Basic rules don't cover the `token` keyword).
     [/\b[Tt]oken\s+[A-Za-z0-9._~+/-]{20,}/g, "token «redacted»"],
-    [/("(?:private_key|client_secret|password|api[_-]?key|secret|token)"\s*:\s*)"[^"\\]*(?:\\.[^"\\]*)*"/gi, '$1"«redacted»"'],
+    [/("(?:private_key|client_secret|password|api[_-]?key|secret|token)"\s*:\s*)"[^"\\]*(?:\\.[^"\\]*)*"/gi, '$1"«redacted»"'], // JSON secret-field VALUES (escaped-quote-safe)
 ];
+/** Redact unambiguous secret formats from reasoning/CoT before it is persisted to the durable trace log. */
+/** S24 (SILENT-FALLBACK P1): optional redaction observer — rewrites previously had zero fingerprint, so
+ *  over-redaction (mangling legit content) and under-redaction (a pattern that never fires) were both
+ *  invisible. main.ts wires this to `redactions_applied_total{pattern}`. Hot path: the observer only runs
+ *  when a pattern actually matched; the label is derived once per pattern at module load. */
 let onRedaction;
 export function setRedactionObserver(fn) {
     onRedaction = fn;
@@ -23,6 +41,10 @@ export function redactSecrets(text) {
             out = out.replace(re, repl);
             continue;
         }
+        // Count-then-replace (1.127.0): only the STRING form of `replace` expands `$1` capture refs —
+        // a function replacer returns its result verbatim, so the URL/JSON-field patterns emitted a literal `$1`
+        // instead of the preserved scheme/key prefix. The extra match() scan runs only when an observer is
+        // installed, on text that is already preview-capped.
         const n = out.match(re)?.length ?? 0;
         out = out.replace(re, repl);
         if (n > 0) {
@@ -30,12 +52,29 @@ export function redactSecrets(text) {
                 onRedaction(PATTERN_LABELS[i], n);
             }
             catch {
+                /* observability must never break redaction */
             }
         }
     }
     return out;
 }
+/** Recursively redact secret-shaped strings inside a structured value (e.g. tool-call `args`), preserving shape.
+ *  Tool arguments are persisted to the durable trace + replayed to any trace consumer, so a secret passed AS a
+ *  tool arg must be stripped too (council: redactSecrets covered only free reasoning text, not tool args). */
+/** 递归上限 —— 与「一条畸形输入不得打死流」这条目标匹配的量级:真实工具输出的嵌套远低于此,
+ *  而爆栈发生在数千层。超限的子树替换成一个**标记**,而不是抛错、也不是静默截断成 `{}`。 */
 const REDACT_MAX_DEPTH = 64;
+/**
+ * 🔴 环 + 深度预算(2026-07-25 补)。原实现是纯递归、**既不记已访问节点也不限深度**,而它的调用位置是
+ * **最不可信的边界**:`toolStart`/`toolEnd` 把工具的 `args`/`output`/`structured` 直接喂进来。后果两条:
+ *   · **循环引用** ⇒ 无限递归 ⇒ `RangeError` **抛出构造函数**。在 sync 的 SSE 腿上那个 throw 就落在
+ *     `for await (…) res.write(…)` 的循环里 ⇒ **一个畸形工具输出能打死一条正在跑的流**;在 ledger-sink 腿上
+ *     则是那一帧 append 直接失败(事件永久不落盘)。
+ *   · 超深嵌套 ⇒ 同样爆栈。
+ * 同文件的 `redactedPreview` 的文档里早把这条记成"已复审的 MEDIUM"并**绕开** redactDeep ——
+ * 也就是说这个洞是知道的,只是没堵。现在堵在 redactDeep 本体:环与超深都换成**可见的标记**,
+ * 让下游看到"这里有东西被省略了",而不是丢一个空对象或炸掉整条流。
+ */
 export function redactDeep(value) {
     return redactDeepInner(value, 0, new WeakSet());
 }
@@ -44,6 +83,7 @@ function redactDeepInner(value, depth, seen) {
         return redactSecrets(value);
     if (!value || typeof value !== "object")
         return value;
+    // 环:同一个对象在**当前这条路径上**再次出现 ⇒ 标记后停,不再往下走。
     if (seen.has(value))
         return "[circular]";
     if (depth >= REDACT_MAX_DEPTH)
@@ -58,16 +98,33 @@ function redactDeepInner(value, depth, seen) {
         return out;
     }
     finally {
+        // 出栈即移除:`seen` 记的是**当前路径**,不是"整棵树里出现过" —— 否则同一个对象被两个兄弟字段
+        // 各引用一次(DAG,完全合法)会被误标成 circular。
         seen.delete(value);
     }
 }
+/**
+ * A REDACTED, length-BOUNDED string preview of a structured value — for surfacing a pending tool call's `args`
+ * in the assistant inbox ("what is this ask about") WITHOUT leaking secrets or dumping an unbounded payload (a
+ * write_file `content` can be megabytes). {@link redactDeep} scrubs secret-shaped strings first; the result is
+ * JSON-stringified and capped (truncation is marked). `null`/`undefined` → `null` (nothing to preview). Defense
+ * in depth: the redaction is conservative (NOT exhaustive — see {@link redactSecrets}); the inbox is already
+ * owner-scoped, so this preview is only ever shown to the ask's own principal (or an operator inspecting it).
+ */
 export function redactedPreview(value, cap = 2000) {
     if (value === null || value === undefined)
         return null;
+    // A bare string arg → preview it directly (not JSON-quoted), redacted.
     if (typeof value === "string") {
         const r = redactSecrets(value);
         return r.length === 0 ? null : r.length > cap ? `${r.slice(0, cap)}…[truncated]` : r;
     }
+    // Structured value → cycle-safe, leaf-bounded JSON, THEN string-level redaction. We do NOT use redactDeep here
+    // (review MEDIUM): redactDeep has no cycle/depth/size budget, so a cyclic arg would recurse to a stack overflow
+    // BEFORE any try/catch, a BigInt would throw, and a huge leaf would be fully copied before truncation. The
+    // replacer below caps long string leaves up front (bounds the buffer), tags cycles, and stringifies BigInt;
+    // redactSecrets on the resulting JSON catches the same secret shapes (the standalone key patterns + the JSON
+    // secret-field rule both operate on the flat string — equivalent-or-better than per-leaf redaction).
     const seen = new WeakSet();
     let s;
     try {
@@ -86,7 +143,7 @@ export function redactedPreview(value, cap = 2000) {
             }) ?? "";
     }
     catch {
-        s = "[unserializable]";
+        s = "[unserializable]"; // last-resort (should be unreachable: cycles/BigInt are handled in the replacer)
     }
     if (s.length === 0)
         return null;

package/dist/usage-analytics.d.ts

@@ -1,7 +1,26 @@
+/**
+ * 用量统计查询面(registry AnalyticsSource id="service-usage" 槽位的数据源)。
+ *
+ * 数据源 = task_run 账本的 result JSON(E8 `stats.modelUsage` per-model echo:inputTokens/outputTokens/
+ * cacheReadTokens/cacheWriteTokens/costMicroUsd——costMicroUsd 是 authoritative micro-USD 记账非估算)。
+ * 架构 = store 侧薄扫窗(usageScan:SQL 只按时间窗过滤取四列,行内 JSON 提取在 store 完成)+ 本文件的
+ * 【纯函数】聚合(三后端同代码,零方言分叉;test 直接喂行)。
+ *
+ * 口径(回帖契约,2026-07-09):
+ *  - tokensIn = Σ(inputTokens + cacheReadTokens + cacheWriteTokens)(即"进模型的上下文 token 总量",
+ *    cache 命中也计——计费口径;cache 明细在 breakdown 的 cacheReadTokens 单列可见);
+ *  - tokensOut = Σ outputTokens;
+ *  - costUsd = Σ costMicroUsd / 1e6(authoritative);
+ *  - 旧行/无 modelUsage echo 的行(1.x 早期或非终态)fallback `stats.tokens` 整数计入 tokensOut 并置
+ *    `estimated:true` 于该聚合(诚实标注,契约要求"token 数标注估算与否");
+ *  - 扫窗有行数上限(store 侧 LIMIT)——触顶时结果携带 `truncated:true`(诚实截断,绝不静默)。
+ */
+/** store 侧 usageScan 的行投影(所有后端同形状;createdAtMs=epoch ms)。 */
 export interface UsageRow {
     owner: string | null;
     createdAtMs: number;
     status: string;
+    /** result.stats 摘要;result NULL/不可解析 ⇒ undefined(不计 token/cost,仍计 tasks)。 */
     stats?: {
         tokens?: number;
         modelUsage?: Record<string, {
@@ -18,19 +37,26 @@ export interface UsageTotals {
     tokensIn: number;
     tokensOut: number;
     costUsd: number;
+    /** 有行走了 stats.tokens fallback(无 per-model echo)——token 口径部分为估算。 */
     estimated: boolean;
 }
+/** GET /v1/usage/summary — 窗内总量。 */
 export declare function usageSummary(rows: UsageRow[]): UsageTotals;
 export type UsageMetric = "tasks" | "tokensIn" | "tokensOut" | "costUsd";
 export type UsageGranularity = "hour" | "day";
+/** GET /v1/usage/series — 时间序列(UTC 桶;空桶不发行,消费方按需补零)。 */
 export declare function usageSeries(rows: UsageRow[], metric: UsageMetric, granularity: UsageGranularity): Array<{
     t: string;
     v: number;
 }>;
 export type UsageDimension = "principal" | "model";
+/** GET /v1/usage/breakdown — 按维度分桶。dimension=model 时按 per-model echo 展开(一行可贡献多个 model 桶;
+ *  fallback 行归 "(unattributed)");dimension=principal 时 owner NULL 归 "(anonymous)"。 */
 export declare function usageBreakdown(rows: UsageRow[], dimension: UsageDimension): Array<{
     key: string;
 } & UsageTotals>;
+/** store 行投影 helper:result JSON(已 parse 或原始字符串)→ UsageRow.stats。所有后端复用(方言只在 SQL)。 */
 export declare function projectUsageStats(result: unknown): UsageRow["stats"];
+/** usageScan 的统一行数上限(触顶=结果 truncated:true;试点规模远在限内)。 */
 export declare const USAGE_SCAN_LIMIT = 50000;
 //# sourceMappingURL=usage-analytics.d.ts.map