@sema-agent/server 1.322.0 → 2.0.0

package/dist/trace/ledger-sink.js

@@ -4,9 +4,19 @@ import { NotifiedKeys, taskNotificationStreamKey } from "../orchestration/workfl
 export function createLedgerSink(opts) {
     const keys = opts.notifiedKeys ?? new NotifiedKeys();
     let seq = 0;
+    // [1.211 codex H2] 单写串行链:seq 的「分配」在链步内发生 ⇒ 分配序 == durable 提交序。没有它,
+    // onForwardEvent 的 fire-and-forget 写与主循环的 awaited 写交错时,高 seq 可先落盘对 events tail 可见,
+    // 迟到的低 seq 在读方游标(afterSeq)前进后被永久遗漏。链上一步失败不断链(catch → undefined),
+    // 调用方拿到的是自己那步的真实结果(await 者照常收到 reject)。
     let chain = Promise.resolve();
     let text = "";
     let reasoning = "";
+    // E18 resume-at: the turn's FIRST text_delta eventId = the message's stable per-message resume handle,
+    // stamped on the durable `text` event (ONE handle per message even when a mid-turn tool_start flushes the
+    // text early). Latched on the first DEFINED eventId of the turn (`??=` — a later part after a tool must not
+    // re-latch), cleared at turn_end — the exact `TurnAnchorCapture.firstTextEventId` semantics. (The bg leg's
+    // anchor tracks the same value for its own anchor-put; both latches see the same events in the same order,
+    // so the stamps agree byte-for-byte — the anchor's extra `turnHadTool` state never feeds the stamp.)
     let textEventId;
     const append = (type, data) => {
         const step = chain.then(() => opts.appendEvent(++seq, type, data));
@@ -14,12 +24,14 @@ export function createLedgerSink(opts) {
         return step;
     };
     const flush = async () => {
+        // Thinking precedes content within a turn → flush a buffered reasoning block FIRST (redacted).
         if (reasoning) {
             await append("reasoning", { text: redactSecrets(reasoning) });
             reasoning = "";
         }
         if (text) {
-            await append("text", { text, ...(textEventId ? { eventId: textEventId } : {}) });
+            // E18: stamp the turn's first-text eventId as the per-message resume handle (additive; tolerate-absent).
+            await append("text", { text, ...(textEventId ? { eventId: textEventId } : {}) }); // persist first; clear only on success so a failed write doesn't drop it
             text = "";
         }
     };
@@ -32,45 +44,85 @@ export function createLedgerSink(opts) {
                 break;
             }
             case "reasoning_delta":
+                // Persist the agent's thinking for the trace UI (core [R57]: reasoning IS on the live stream but NOT in
+                // the metadata Tracer — capturing it is the service's call). Gated by TRACE_THINKING; redacted on flush.
                 if (opts.persistThinking)
                     reasoning += ev.delta;
                 break;
             case "tool_start":
                 await flush();
+                // E1+E2 (shell-host contract): redacted args + identity via the shared whitelist builder — identical
+                // persisted shape across every leg.
                 await append("tool_start", toolStartEventData(ev));
                 break;
             case "tool_end":
                 await flush();
+                // E1: redacted model-facing output (+truncated, core size-bound) + E2 identity, via the shared builder.
                 await append("tool_end", toolEndEventData(ev));
                 break;
             case "status":
+                // S4 (SILENT-FALLBACK P0-a): persist the brain-layer liveness observation. core marks the live frame
+                // EPHEMERAL (it never replays it) — this durable row is OUR observation record so async/replay readers
+                // can attribute a stalled turn. flush() first (review MED-2): a reconnect can fire MID-TEXT — without
+                // the flush the already-streamed text lands AFTER this row and the durable timeline inverts.
+                // design/158 B2: durable row type aligned to the live frame name ("status", not "brain_status") — the
+                // two legs were emitting the SAME logical event under two different `type` strings, and the SDK's
+                // public `AgentEvent` union only declared "status" (a durable-leg reader saw a frame outside its own
+                // public type). 写新读旧:这里只管写新;**存量行救不了**(任何旧部署的账本里都躺着 `brain_status`
+                // 行),所以重放边界配了一次性归一 —— `normalizeRunEventType`(trace/project.ts),唯一调用点是
+                // task_run SSE 的 `formatEvent`(routes/runs.ts)。两半缺一不可:只改写入侧的话,存量行重放时
+                // 仍会漏出公开联合之外的名字。无 migration、无回填(读边界归一比改历史行便宜且不可逆风险为零)。
                 await flush();
                 await append("status", brainStatusEventData(ev));
                 break;
             case "context_usage":
+                // core 1.414 一等分支(server [1669]⑥ 要的上下文用量面)。每个压缩边界上报一次 ⇒ 一次任务多条,
+                // 消费方取最后一条为当前值。两条口径见 `contextUsageEventData` 旁注(别把 windowTokens 当模型上下文)。
                 await flush();
                 await append("context_usage", contextUsageEventData(ev));
                 break;
             case "compacted":
                 await flush();
+                // MF-18 (1.149) trigger/tokensBefore + core 1.219 attachedFiles/preserved_segment via the SHARED
+                // whitelist builder — the shell renders CC's post-compact `Read {path}` cards + the divider from these.
                 await append("compacted", compactedEventData(ev));
                 break;
             case "diagnostics":
+                // core 1.220 (design/121): NEW LSP diagnostics at a turn boundary — the shell's render source for CC's
+                // "Found N new diagnostic issues" row. §E1: language-server output is UNTRUSTED RAW → builder redacts.
                 await flush();
                 await append("diagnostics", diagnosticsEventData(ev));
                 break;
             case "steering_injected":
+                // [1550]/[1552]: core's mid-run system-reminder injection (todo/file-change/date-roll/skills-delta/…) —
+                // the shell's render source for CC's steering-attachment row. §E1: preview is UNTRUSTED free text →
+                // builder redacts. Host/self-session only — NOT mirrored into onForwardEvent (a delegated child's own
+                // reminders are its internal bookkeeping, not host-relevant progress like tool_start/task_progress).
                 await flush();
                 await append("steering_injected", steeringInjectedEventData(ev));
                 break;
             case "workspace_changed":
+                // [1559]二 core 裁定:design/99 §E13 旧臂,L1 门扩臂时首次撞见。durable 记账与其余内容型臂
+                // 同处置(轨迹回放时「何时 cd 到了哪」是合法历史事实,「不当持久态渲染」是 LIVE 消费端纪律,
+                // 不是不许落账)——共享白名单构造器 + §E1 redact。
                 await flush();
                 await append("workspace_changed", workspaceChangedEventData(ev));
                 break;
             case "task_progress":
+                // core breakpoint⑤: a subagent's live progress tick → an INLINE "subagent working" card for the tailing
+                // client (S2-a). Shared whitelist+redact builder (+ E2 identity for the exact concurrent-tick binding).
                 await append("task_progress", taskProgressEventData(ev));
                 break;
             case "task_notification": {
+                // core 1.202 (design/115 P2): a background task finished while this harness was live — persist the
+                // display projection so a tailing client renders it (summary/result are UNTRUSTED free text → shared
+                // builder redacts). core [784]④a+④b: seq-folded shared key + skip keys this leg already delivered
+                // (start-of-leg inbox drain or observer arm) — core's pend-drain replays a double-parked idle arrival
+                // as a stream event; appending it again doubles the frame in the durable tail. codex F1: a key claimed
+                // by a fire-and-forget arm may have FAILED to land — await the claim's outcome; false ⇒ write anyway
+                // (this stream replay is the notification's last copy on this leg) and promote the key with THIS
+                // write's outcome. The claim promise is registered before the awaited append so a concurrent observer
+                // callback can't double-claim mid-write.
                 await flush();
                 const tn = ev.notification;
                 const tnKey = tn?.task_id ? taskNotificationStreamKey({ task_type: tn.task_type, task_id: tn.task_id, status: String(tn.status), seq: tn.seq }) : undefined;
@@ -78,21 +130,26 @@ export function createLedgerSink(opts) {
                 if (tnPrior === undefined || !(await tnPrior)) {
                     const write = append("task_notification", taskNotificationEventData(ev));
                     if (tnKey !== undefined)
-                        keys.set(tnKey, write.then(() => true, () => false));
+                        keys.set(tnKey, write.then(() => true, () => false)); // the stream delivered this key
                     await write;
                 }
                 break;
             }
             case "turn_end": {
                 await flush();
+                // core 1.76 (service [41]/core [R59]): per-turn usage rides turn_end.usage — persist it for TraceTurn.tokens.
                 const usage = ev.usage;
-                await append("turn_end", turnEndEventData(ev));
-                textEventId = undefined;
+                await append("turn_end", turnEndEventData(ev)); // 白名单 builder(此前手写 {usage},剥掉了 stopReason/usageMissing)
+                textEventId = undefined; // next turn latches its own first-text handle (TurnAnchorCapture parity)
                 break;
             }
+            // `done` / `message_committed` / unknown: deliberate no-ops — see the interface doc.
         }
     };
     const onForwardEvent = (e) => {
+        // 1.78 (review HIGH) + C1 (core 1.219, spec.forwardSubagentEvents): a delegated child's lifecycle rides the
+        // forward sink (each stamped parentToolCallId — the shell nests them under the delegation card). Same
+        // shared builders as the top stream; fire-and-forget (`++seq` is sync → unique seqs vs the awaited loop).
         const t = e.type;
         if (t === "task_progress") {
             void append("task_progress", taskProgressEventData(e)).catch(() => undefined);
@@ -104,7 +161,9 @@ export function createLedgerSink(opts) {
             void append("tool_end", toolEndEventData(e)).catch(() => undefined);
         }
     };
-    const appendParked = (kind, result) => append(kind, { gate: result?.checkpointGate ?? null });
+    const appendParked = (kind, result) => 
+    // Never the capability checkpointToken — only the non-secret gate (search [18] Q1b).
+    append(kind, { gate: result?.checkpointGate ?? null });
     const appendDone = (result) => append("done", { result });
     const onDone = async (result) => {
         await flush();

package/dist/trace/project.d.ts

@@ -1,19 +1,47 @@
+/**
+ * Task Trace projection (S1): the durable run event log → sema-registry's `TraceTurn[]` contract.
+ *
+ * The event log (src/runs.ts) is a flat per-task seq stream: reasoning / text / tool_start / tool_end /
+ * turn_end / compacted / done / suspended / failed. sema-registry renders an ORDERED `blocks[]` transcript
+ * (CC-style thinking↔tool interleave), grouped into turns. This is pure presentation/projection = the
+ * SERVICE layer (core [R57] adversarial: do NOT push this shape into core — different consumer, different shape).
+ *
+ * Per core [R57] corrections: there is no `suspended` event (suspend = the run row's status); per-turn tokens ride
+ * on `turn_end.usage` (core additive). As of core 1.121.0 (design/99 §E1) `tool_end` ALSO carries the model-facing
+ * `output` (+ `truncated`) — redacted + size-bounded at append (runs.ts) and read straight off the event here (the
+ * old session-join `toolOutput` hook is gone, there's a real source now); `eventId`/`parentToolCallId` (§E2) ride
+ * each content event, additive / tolerate-absent.
+ */
 import type { TaskResult } from "@sema-agent/core";
 import type { RunEvent, RunRecord } from "../plugins/store-contracts.js";
 import type { ModelUsageDelta, ModelUsageTracker, PromptManifestRecord } from "../budget.js";
 type AppendFn = (type: string, data: unknown) => Promise<void>;
 type GetEventsFn = (taskId: string, afterSeq: number) => Promise<RunEvent[]>;
+/** 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 declare function appendModelUsageDelta(append: AppendFn, modelUsage: ModelUsageTracker | undefined, taskId: string): Promise<void>;
+/** [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 declare function appendPromptManifest(append: AppendFn, tracker: {
     drain(taskId: string): PromptManifestRecord[] | undefined;
     drainConfig?(taskId: string): Array<Record<string, unknown>> | undefined;
 } | undefined, taskId: string): Promise<void>;
+/** 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 declare function attachModelUsage<T extends TaskResult>(result: T, ctx: {
     append: AppendFn;
     getEvents: GetEventsFn;
     modelUsage: ModelUsageTracker | undefined;
     taskId: string;
 }): Promise<T>;
+/** 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 declare function aggregateModelUsage(events: RunEvent[]): Record<string, ModelUsageDelta> | undefined;
 export type TraceBlock = {
     type: "thinking";
@@ -48,6 +76,10 @@ export type TraceBlock = {
     sections?: unknown;
     tools?: unknown;
 };
+/** 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 declare function toolStartEventData(ev: {
     toolCallId: string;
     toolName: string;
@@ -56,6 +88,15 @@ export declare function toolStartEventData(ev: {
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;
+/** 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 declare function toolEndEventData(ev: {
     toolCallId: string;
     toolName: string;
@@ -68,6 +109,12 @@ export declare function toolEndEventData(ev: {
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;
+/** 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 declare function taskProgressEventData(ev: {
     taskId: string;
     parentTaskId?: string;
@@ -80,6 +127,18 @@ export declare function taskProgressEventData(ev: {
     workflowRunId?: string;
     workflowAgentLabel?: string;
 }): Record<string, unknown>;
+/** 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 declare function taskNotificationEventData(ev: {
     notification: {
         task_id: string;
@@ -113,6 +172,18 @@ export declare function taskNotificationEventData(ev: {
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;
+/** 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 declare function diagnosticsEventData(ev: {
     files: Array<{
         uri: string;
@@ -128,17 +199,32 @@ export declare function diagnosticsEventData(ev: {
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;
+/** 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 declare function steeringInjectedEventData(ev: {
     source: string;
     preview: string;
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;
+/** 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 declare function workspaceChangedEventData(ev: {
     cwd: string;
     eventId?: string;
     parentToolCallId?: string;
 }): Record<string, unknown>;
+/** 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 declare function brainStatusEventData(ev: {
     phase: string;
     detail?: string;
@@ -172,6 +258,7 @@ export declare function compactedEventData(ev: {
     };
 }): Record<string, unknown>;
 export interface TraceTurn {
+    /** per-task seq = the turn's terminating event seq (so history-up-to-H splices with stream seq>H). */
     seq: number;
     ts: string;
     role: "system" | "user" | "assistant" | "tool";
@@ -183,21 +270,47 @@ export interface TraceTurn {
         cacheWrite?: number;
     };
 }
+/**
+ * `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 declare function contextUsageEventData(ev: {
     usedTokens?: unknown;
     windowTokens?: unknown;
     compactAtTokens?: unknown;
 }): Record<string, unknown>;
+/**
+ * `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 declare function turnEndEventData(ev: {
     usage?: unknown;
     usageMissing?: true;
     stopReason?: string;
 }): Record<string, unknown>;
+/** 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 declare function toContractTokens(usage: unknown): TraceTurn["tokens"] | undefined;
 export interface ProjectOpts {
+    /** Prepend the user turn (the objective is not in the event log; the endpoint supplies it). */
     objective?: string;
 }
+/** Project a per-task event slice (seq-ascending) into ordered `TraceTurn[]`. Pure + total (never throws). */
 export declare function projectEvents(events: RunEvent[], opts?: ProjectOpts): TraceTurn[];
+/** Structured `lastStep` (contract 2.1) from the latest event — UI maps an icon, never free text. */
 export declare function lastStep(latestEventType: string | undefined, status: string): {
     type: "thinking" | "tool-call" | "responding" | "idle";
     label?: string;
@@ -206,9 +319,13 @@ export interface TaskSummary {
     id: string;
     status: string;
     scenario?: string;
+    /** Work-view correlation id (optional) — lets the client group a list into logical tasks. */
     jobId?: string;
+    /** Credential-derived submitting system (oa/cc-mcp/portal…) — per-door attribution. */
     source?: string;
+    /** Redacted first ~120 chars of the objective — the "what is this task" glance. */
     objectivePreview?: string;
+    /** The run's owner principal — the operator/boss view needs "whose task". */
     owner?: string;
     startedAt: string;
     endedAt?: string;
@@ -220,8 +337,24 @@ export interface TaskSummary {
         label?: string;
     };
 }
+/** 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 declare function taskSummary(run: RunRecord, latestEventType?: string): TaskSummary;
+/** 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 declare function normalizeRunEventType(type: string): string;
+/** 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 declare function mapTraceEvent(type: string, seq: number, data: Record<string, unknown>): {
     event: string;
     data: Record<string, unknown>;