@qjp88995/agent-runtime 0.0.0-stage → 0.1.0

package/src/turn/tool-input-preview.ts

@@ -0,0 +1,223 @@
+import { extractJsonStringField } from './json-string-field.js';
+
+/**
+ * 工具入参流式构建的**内容预览器**。
+ *
+ * 与 `tool-input-progress.ts` 分工：那条 tracker 答「写了多少」（字数，
+ * 不看内容），这条答「写了什么」——只对白名单工具实时抽出它入参里那个正文
+ * 字段（`Write.content`）的累计前缀，外加解析完整了的 `path`，供对话页的稿栏
+ * 边写边显示文件名与正文。
+ *
+ * 两个 tracker 各管一条事件（`tool-input-progress` / `tool-input-preview`），
+ * 互不知道对方；`chunk-projection.ts` 在同一处 `tool-input-delta` 分支里
+ * 各喂一遍。
+ *
+ * ## 成本（这一条决定了下面两道闸的形状）
+ *
+ * 每次 `delta` 都得**从头**重扫一遍累计的 `raw` 才能抽出字段值
+ * （`extractJsonStringField` 是线性扫描，没有可续跑的状态：转义与代理对的
+ * 收尾判定依赖上下文）。模型吐一篇长文约 120 块入参增量，若每块都扫一遍
+ * 就是 O(n²) 的字符比对，且每帧还要把整段前缀再发一次。
+ *
+ * 两道闸把它压回可接受：
+ * 1. **扫描前先看 `raw` 涨了多少**——解码后的字符数**恒不大于**原始 JSON 的
+ *    字符数（转义只会更长、代理对只会更多），所以「raw 涨的还不够一个阈值」
+ *    是「正文涨的也不够」的**必要条件**，此时连扫都不必扫。唯一例外是 `path`
+ *    还没解析完整那一段：第一帧必须尽早带上路径（稿栏靠它先开栏显示文件名），
+ *    那几块一律照扫。
+ * 2. **阈值随正文长度自适应**（`previewThreshold`）：短文里每 80 码点发一条
+ *    才看得出「在写」；长文里正文本身已经几千字，再按 80 发就是每帧重发一份
+ *    越来越大的全量前缀。载荷语义仍是**累计前缀**（幂等，断线重放/去重下不会
+ *    拼错），只是发得更疏。
+ *
+ * 零依赖纯函数式实现，同一套单测风格（本仓既有做法：`tool-input-progress.ts`）。
+ */
+
+/**
+ * 阈值下限，也是短正文期间的实际阈值：每积累这么多字符发一条预览。
+ *
+ * 按「界面上正文多久长一截」定：模型出中文大约 100+ 字符/秒，80 约等于每秒
+ * 一次。再密只是徒增事件（每条都带全量前缀），再疏就开始像卡住了。
+ */
+export const TOOL_INPUT_PREVIEW_CHARS = 80;
+
+/**
+ * 阈值上限。一篇 8000 字的稿子按 400 发也有 20 帧，够看出它在长；再放宽就
+ * 变成「写了半天才蹦一大段」。
+ */
+export const TOOL_INPUT_PREVIEW_CHARS_MAX = 400;
+
+/**
+ * 已经发出 `chars` 个字符之后，下一条预览要等正文再涨多少。
+ *
+ * `chars / 8` 意味着「每帧最多把正文推进八分之一」——发出的总字节量随正文
+ * 长度线性（而不是平方）增长，界面上的推进感又与正文长度无关（短文每秒一
+ * 帧、长文每几秒一大段，都是「一直在长」）。
+ *
+ * @param floor 阈值下限，默认 `TOOL_INPUT_PREVIEW_CHARS`；测试用它把节流拨快。
+ */
+export function previewThreshold(
+  chars: number,
+  floor: number = TOOL_INPUT_PREVIEW_CHARS
+): number {
+  return Math.max(
+    floor,
+    Math.min(Math.floor(chars / 8), TOOL_INPUT_PREVIEW_CHARS_MAX)
+  );
+}
+
+/**
+ * 白名单：只有登记在这里的工具才会被追踪，且只认这两个字段名。
+ *
+ * `path` 用来给稿栏定位文件；`text` 是要显示的正文字段，**为 `null` 表示这个
+ * 工具没有可预览的正文**——`Edit` 的入参是替换对（`old_string`/`new_string`）
+ * 而不是整篇，半截的替换对画不出任何东西。它仍然登记在这里，是因为稿栏需要
+ * 在 `Edit` 落盘之前就知道「agent 正在改哪份文件」（栏头显示「生成改动中」，
+ * 而不是等几十秒后才跳出一份改好的稿）。
+ */
+export const TOOL_INPUT_PREVIEW_FIELDS: Record<
+  string,
+  { path: string; text: string | null }
+> = {
+  Write: { path: 'path', text: 'content' },
+  Edit: { path: 'path', text: null },
+};
+
+export interface ToolInputPreviewEvent {
+  toolCallId: string;
+  toolName: string;
+  /** 只有 `path` 字段解析**完整**了才不是 null（首次完整立刻发一条）。 */
+  path: string | null;
+  /** 正文字段的累计前缀（可能是 `''`；无正文字段的工具恒 `''`）。 */
+  text: string;
+  /** 至此 `text` 的码点数（与 `tool-input-progress` 同一判据）。 */
+  chars: number;
+}
+
+export interface ToolInputPreviewTracker {
+  /** 模型开始吐某次调用的参数。不在白名单的工具直接忽略，不建账。 */
+  start(toolCallId: string, toolName: string): void;
+  /**
+   * 收到一块入参增量。返回非 null 表示「该发一条预览了」。
+   *
+   * **未 `start` 过（或起手时就不在白名单）的 toolCallId 一律返回 null**。
+   */
+  delta(toolCallId: string, text: string): ToolInputPreviewEvent | null;
+  /** 这次调用的参数收齐了，丢掉它的累计。 */
+  done(toolCallId: string): void;
+}
+
+/** 按码点数，不是 UTF-16 code unit —— 与 tool-input-progress 同一判据。 */
+function countCodePoints(text: string): number {
+  return Array.from(text).length;
+}
+
+export function createToolInputPreviewTracker(
+  fields: Record<
+    string,
+    { path: string; text: string | null }
+  > = TOOL_INPUT_PREVIEW_FIELDS,
+  thresholdChars: number = TOOL_INPUT_PREVIEW_CHARS
+): ToolInputPreviewTracker {
+  const entries = new Map<
+    string,
+    {
+      toolName: string;
+      pathKey: string;
+      textKey: string | null;
+      raw: string;
+      /**
+       * `raw` 至今的码点数。**逐块累加而不是每次量整段**：量整段本身就是又一次
+       * O(n) 扫描，正是这道闸要省掉的东西。跨块劈开的代理对会被两半各算一个
+       * （多算一个），偏差方向是「以为涨得更多 → 提前扫一次」，只多花一次扫描，
+       * 不会漏发。
+       */
+      rawChars: number;
+      path: string | null;
+      /** 上次发出时的正文码点数。 */
+      emittedChars: number;
+      /** 上次发出时的 `rawChars`。 */
+      emittedRawChars: number;
+    }
+  >();
+
+  return {
+    start(toolCallId, toolName) {
+      const field = fields[toolName];
+      if (field === undefined) return; // 不在白名单，不建账——delta 恒 null
+      entries.set(toolCallId, {
+        toolName,
+        pathKey: field.path,
+        textKey: field.text,
+        raw: '',
+        rawChars: 0,
+        path: null,
+        emittedChars: 0,
+        emittedRawChars: 0,
+      });
+    },
+    delta(toolCallId, text) {
+      const e = entries.get(toolCallId);
+      if (e === undefined) return null;
+      e.raw += text;
+      e.rawChars += countCodePoints(text);
+
+      // `path` 一旦完整就不会再变（同一个 JSON 里只有一个顶层 `path`），不必
+      // 重扫；而它还没完整时**每块都要扫**——第一帧要尽快把路径带出去。
+      if (e.path === null) {
+        const pathResult = extractJsonStringField(e.raw, e.pathKey);
+        // 路径都还没齐，正文更不可能过阈值（正文在 JSON 里排在后面）。
+        if (pathResult === null || !pathResult.complete) return null;
+        e.path = pathResult.value;
+        // 「首次拿到完整 path」是独立于字数阈值的触发点——稿栏靠它在正文
+        // 到来之前先打开并显示文件名，晚了就是「先写了半天字才冒出标题」。
+        // 正文多半还是空串，但同一块里就带上了正文时也要如实发出去。
+        const seed = readText(e);
+        return emit(e, toolCallId, seed.text, seed.chars);
+      }
+
+      // 没有正文字段的工具（`Edit`）：路径那一条发完就再没有可发的了。
+      if (e.textKey === null) return null;
+
+      // 见头注释「成本」①：raw 涨得还不够一个阈值 → 正文必然也不够，不扫。
+      const threshold = previewThreshold(e.emittedChars, thresholdChars);
+      if (e.rawChars - e.emittedRawChars < threshold) return null;
+
+      const next = readText(e);
+      if (next.chars - e.emittedChars < threshold) return null;
+
+      return emit(e, toolCallId, next.text, next.chars);
+    },
+    done(toolCallId) {
+      entries.delete(toolCallId);
+    },
+  };
+
+  /** 当前累计的正文前缀；无正文字段的工具恒 `('', 0)`。 */
+  function readText(e: { raw: string; textKey: string | null }): {
+    text: string;
+    chars: number;
+  } {
+    if (e.textKey === null) return { text: '', chars: 0 };
+    const result = extractJsonStringField(e.raw, e.textKey);
+    const text = result !== null ? result.value : '';
+    return { text, chars: countCodePoints(text) };
+  }
+
+  function emit(
+    e: {
+      toolName: string;
+      path: string | null;
+      rawChars: number;
+      emittedChars: number;
+      emittedRawChars: number;
+    },
+    toolCallId: string,
+    text: string,
+    chars: number
+  ): ToolInputPreviewEvent {
+    e.emittedChars = chars;
+    e.emittedRawChars = e.rawChars;
+    return { toolCallId, toolName: e.toolName, path: e.path, text, chars };
+  }
+}

package/src/turn/tool-input-progress.ts

@@ -0,0 +1,76 @@
+/**
+ * 工具入参流式构建的**进度节流器**。
+ *
+ * **为什么需要它**：`emit('tool-call', …)` 发生在整个 step 的流被消费完之后
+ * （`runTurn` 里 `emit('text-end')` 之后那个 `for (const tc of toolCalls)`
+ * 循环），而模型吐这次调用参数的那段时间——写一篇长文时就是绝大部分时间——
+ * 界面上一片死寂：`tool-input-delta` 在 depth 0 从不投影，用户看到的是一个
+ * 停住的界面，只能当它卡了。
+ *
+ * **为什么不直接把 `tool-input-delta` 投出去**：那条流是**有消费方的**——
+ * `parts-from-events.ts` 的 abort 兜底靠累积它的原始 JSON 片段，在中断时重建
+ * 半截的 tool-call。它必须保持逐块、不节流、原样。而它作为 UI 信号又太碎
+ * （实测一次调用约 120 块），且投影层根本没有 `delta` 字段可透。
+ *
+ * 所以这里另发一条**只服务于界面**的进度事件：累积到一定字数才发一次，
+ * 载荷是「已经收到多少字符」而不是内容本身。
+ *
+ * 零依赖纯函数，便于单测（本仓既有做法：`running-nodes.ts`/`autosave-scheduler.ts`）。
+ */
+
+/**
+ * 每积累这么多字符发一条进度。
+ *
+ * 按「界面上那个数字多久动一次」定：模型出中文大约 100+ 字符/秒，故 120 约等于
+ * 每秒一次。再密只是徒增事件，再疏就又开始像卡住了。
+ */
+export const TOOL_INPUT_PROGRESS_CHARS = 120;
+
+export interface ToolInputProgressEvent {
+  toolCallId: string;
+  toolName: string;
+  /** 至此累计收到的入参字符数（不是内容）。 */
+  chars: number;
+}
+
+export interface ToolInputProgressTracker {
+  /** 模型开始吐某次调用的参数。 */
+  start(toolCallId: string, toolName: string): void;
+  /**
+   * 收到一块入参增量。返回非 null 表示「该发一条进度了」。
+   *
+   * **未 `start` 过的 toolCallId 一律返回 null**：没有 `tool-input-start` 就
+   * 没有 toolName，发一条不知道是什么工具的进度，界面上无从落位。
+   */
+  delta(toolCallId: string, text: string): ToolInputProgressEvent | null;
+  /** 这次调用的参数收齐了，丢掉它的累计（一个 turn 可以跑很多步）。 */
+  done(toolCallId: string): void;
+}
+
+export function createToolInputProgressTracker(
+  thresholdChars: number = TOOL_INPUT_PROGRESS_CHARS
+): ToolInputProgressTracker {
+  const entries = new Map<
+    string,
+    { toolName: string; chars: number; emittedAt: number }
+  >();
+
+  return {
+    start(toolCallId, toolName) {
+      entries.set(toolCallId, { toolName, chars: 0, emittedAt: 0 });
+    },
+    delta(toolCallId, text) {
+      const e = entries.get(toolCallId);
+      if (e === undefined) return null;
+      // 按**码点**数，不是 UTF-16 code unit：中文一字一码点，而 `.length`
+      // 对 emoji 之类会翻倍——这个数字是给人看的「已经写了多少字」。
+      e.chars += Array.from(text).length;
+      if (e.chars - e.emittedAt < thresholdChars) return null;
+      e.emittedAt = e.chars;
+      return { toolCallId, toolName: e.toolName, chars: e.chars };
+    },
+    done(toolCallId) {
+      entries.delete(toolCallId);
+    },
+  };
+}

package/src/turn/turn-envelope.ts

@@ -0,0 +1,185 @@
+import type { ModelMessage } from 'ai';
+
+import type { MessagePart } from '../schema/index.js';
+
+export interface TurnEnvelope {
+  /** agent 的 id（同 `AgentDefinition.id`）。 */
+  agentId: string;
+  /**
+   * 本轮实际用的模型与推理等级，记进跑次（`RunStore.open` 的 `model`）。取自模型句柄，内核不解释。
+   */
+  modelUsed: { modelId: string; label: string; reasoningEffort: string };
+  /** 用户输入。 */
+  parts: MessagePart[];
+  /** 根 turn 的 id；同时是 StreamBus 的 streamId。 */
+  streamId: string;
+  /** 根会话 id（观测/产物树级作用域键；pre-1b 根 tick = sessionId）。 */
+  rootSessionId: string;
+  /** 当前 loop 的会话 id。 */
+  sessionId: string;
+  /** 本次执行的 run id（根 turn 与 streamId 可相同，子 agent 各自不同）。 */
+  runId: string;
+  parentRunId?: string | null;
+  depth?: number;
+  /**
+   * 宿主给这个跑次的不透明附加列（跑的是哪个 agent、发布版号、账本序号……），原样交给
+   * `RunStore.open` 的 `attrs`。内核不解释。
+   */
+  runAttrs?: Readonly<Record<string, unknown>>;
+  /**
+   * 会话上的不透明附加信息，原样进 `ToolContext.sessionMetadata`（派子 Agent 时子会话继承）。
+   * 省略 = 空对象。
+   */
+  sessionMetadata?: Readonly<Record<string, unknown>>;
+  userId?: string | null;
+  /**
+   * 本轮模型标了哪些能力（模型句柄的 `capabilities`）。内核只透传进
+   * `ToolContext.agent.modelCapabilities`。省略 = 空数组。
+   */
+  modelCapabilities?: readonly string[];
+  /**
+   * 子 run 的宿主 agent 名（Plan 3 子 agent 用）。供前端画子轨道标题
+   * （Task 9）；内核本身不消费。根 run 不传。
+   */
+  agentName?: string;
+  /**
+   * 父写给子的 task prompt（Plan 3 子 agent 用）。供 run-start 事件
+   * 携带、UI 展示；内核本身不消费。根 run 不传。
+   */
+  prompt?: string;
+  /**
+   * 子 run 的一句话任务标题（spawn 时模型显式提供，落在子会话 `title`）。
+   * 供 run-start 事件携带、前端子 Agent 卡做标题；内核本身不消费。根 run 不传。
+   */
+  title?: string;
+}
+
+/**
+ * loop 从 inbox 领到的一条消息——内核只认 parts，不认 inbox 行结构。
+ * `metadata` 是可选的宿主级附加信息（当前唯一用途：tool_result 里程碑回投时
+ * 携带 `{ source }`，供 `onUserMessages` 落进 `chat_message.metadata`，供前端
+ * 未来渲染来源角标；内核本身不消费）。
+ */
+export interface DrainedTurnMessage {
+  /** 预生成的落库 id（root 的用户消息经 start() 预生成、inbox 透传）；无则落库自生 uuid。 */
+  id?: string;
+  /** **落库的那份**——数据本身。`onUserMessages` 写的就是它。 */
+  parts: MessagePart[];
+  /**
+   * **注入模型的那份**——同一条消息的呈现形态，缺省即 `parts`。
+   *
+   * 当前唯一用途：子 Agent 回执要包进 `<subagent-result …>` 围栏（不可信外部
+   * 输入需要一条字节层面可判定的边界，见 `milestone-body.ts#wrapSubagentResult`），
+   * 而围栏是给模型看的、不该落进 `chat_message`——否则前端渲染回执气泡时还得
+   * 把标签剥回去，等于把一个自己刚拼上的格式再解析一遍。
+   *
+   * 内核对这层区分一无所知，只负责「push 进 messages 时优先用它」。
+   */
+  modelParts?: MessagePart[];
+  metadata?: Record<string, unknown>;
+}
+
+/** 壳提供的宿主能力。内核对"消息存哪、怎么投递"一无所知。 */
+export interface TurnHost {
+  /** 历史从哪来。必须返回 ModelMessage[]，不许退化成 {role,content:string}[]。 */
+  loadContext(): Promise<ModelMessage[]>;
+  /** system prompt 拼装（可在 agent.systemPrompt 之上追加时间块等）。 */
+  assembleSystem(agentPrompt: string): Promise<string>;
+  /**
+   * 取出本会话 inbox 里排队的消息。**实现方必须在取出的同一个事务里落库**
+   * —— 取出是 DELETE，拆成「先取后写」两步的话，中间失败就两边都没有了。
+   * 内核因此不再有 `onUserMessages` 钩子（那正是被忘掉的第二步）。
+   *
+   * **一轮只调一次**（本轮第一次迭代），之后改用 `hasPendingInbox` 探测并
+   * 换轮，见那个方法。缺省（裸 host）视为恒空。
+   */
+  drainInbox?(): Promise<DrainedTurnMessage[]>;
+  /**
+   * 探一眼 inbox 还有没有排队的消息 —— **只探不取**。
+   *
+   * 内核用它决定「换轮」：本轮第一次迭代照常 `drainInbox` 真取，之后每次调
+   * 模型前只探这一下，见货就收尾这一轮，把消息留给**下一个 tick** 的首次
+   * drain。新 runId / 新 `agent_run` / 新 assistant 行 / 新流全由既有的
+   * re-wake 白拿（`LoopDriverService.onWake` 释放锁后本来就查一次 inbox）。
+   *
+   * 这样插话在 `created_at` 上天然落在它引发的那段文字**之前**，不必再在
+   * 宿主里封口当前段落、把后续输出切到新的一行 —— 那套分段连同它散在六处
+   * 的判据（`persist` 盖哪一行、前端按 runId 聚合/收段…）由此整块消失。
+   *
+   * **第一次为什么不能也只探不取**：那样会话空闲时用户发一条消息就会
+   * 收尾 → re-wake → 又探到有货 → 收尾 …… 永远没人取走它。判据是 `TurnRun`
+   * 内部的一个局部标志（`drainedOnce`），投递方什么都不用知道。
+   *
+   * 缺省（不实现）= 恒 false = 永不换轮，裸 host 的行为因此不变。
+   */
+  hasPendingInbox?(): Promise<boolean>;
+  /**
+   * 本轮又产出了这一截 parts（从事件账本重建，见 `TurnRun.flushStep`）——增量
+   * 落库。**只交增量**：调用方带着游标，同一条 part 不会交第二次。
+   *
+   * **不带 usage**：本轮的 usage 累加到终态一次性交给 `persist`，而这里曾经那个
+   * 参数从来没有实现方读过（宿主写的一直是 `usageAcc`）。一个没人读的参数迟早
+   * 会有人以为它写进了库。
+   *
+   * `uptoSeq`：这批 parts 覆盖到的最后一个事件的 seq（见
+   * `partsFromEventBufferWithBoundary`）。宿主把它与 parts 一起落库
+   * （`metadata.flushedSeq`），再据此让会话流退役 seq ≤ 它的事件。
+   */
+  onAssistantStep?(parts: MessagePart[], uptoSeq: number | null): Promise<void>;
+  /**
+   * 收尾：盖终态。**不再交 parts** —— 这一轮产出过什么，`onAssistantStep` 已经
+   * 逐段交过了（终态路径也一样：内核在 `finish()` 里先把账本里剩下的那一截交
+   * 出去，再调这里）。宿主因此不必再判「这一轮到底落过库没有」，那套
+   * `wroteAnyStep` 分流随之消失。
+   */
+  persist(result: TurnResult): Promise<void>;
+  /**
+   * 宿主为本轮**预置**的插件状态（键 = 插件的 `name`，取用见 `turnStateOf`）。
+   * 不给就是一张空表，插件各自懒建自己那一份。
+   *
+   * **这是个数据字段，不是能力方法**，存在的理由只有一条：有些 per-turn 对象
+   * 天生同时服务骨架与插件，而它必须是**同一个实例**。上下文预算的
+   * `ContextBudgetTracker` 就是——`loadContext()` 用它投影历史并留下轮初那批行
+   * 的快照，`beforeModelCall` 插件用同一份快照算切点、只替换 `messages` 的头部，
+   * 终态又用它落 `contextThreshold`。三方各建一个的话，`ContextRelief.replaces`
+   * 与内存里真实的头部长度就不是一回事，`splice` 会把尾部整体错位一格——**而那
+   * 是静默的**（历史与围栏消息一起被吃掉，没有任何报错）。
+   *
+   * 所以由**建它的那一方**（宿主，`loadContext` 的实现者）顺手挂在这里，而不是
+   * 让插件在切点上懒建：切点跑在第一次 `drainInbox` **之后**，那时本轮的用户
+   * 消息已经进库，懒建出来的快照会把它们算进可裁剪的阴影区。
+   */
+  turnState?: Map<string, unknown>;
+}
+
+export type TurnStatus = 'completed' | 'aborted' | 'rejected' | 'failed';
+
+/**
+ * 一轮的终态。**没有 `parts` 字段是有意的**（阶段 3）：本轮产出过什么由
+ * `onAssistantStep` 逐段交出去，终态只回答「怎么结束的、花了多少」。
+ *
+ * 曾经它带着整轮重建出来的 parts，宿主再按「这一轮落过库没有」分流：落过就只
+ * 盖终态、没落过就拿这份补落一条。那套分流有两个已知漏洞（多步中途 abort、
+ * reviewOutput 改写：两者的 parts 都会在首步已落库之后才出现，于是被丢掉），
+ * 而漏洞的根在「同一批内容有两条落库路径」。现在只剩一条。
+ */
+export interface TurnResult {
+  streamId: string;
+  runId: string;
+  status: TurnStatus;
+  /** 最终文本（reviewOutput 改写后的）。 */
+  text: string;
+  usage?: Record<string, number>;
+  stopReason?: string;
+  error?: string;
+  /**
+   * **这一轮结束时上下文有多大** = 末步 provider 报的 `inputTokens` + 那一步的
+   * `outputTokens`（那条回复此刻已经在历史里，下一轮就是输入的一部分）。宿主
+   * 落进 `chat_message.metadata`，供下一轮开头当压力基线 —— 那一刻还没调过模型，
+   * 没有别的办法知道这个会话的上下文有多大。
+   *
+   * **与 `usage.inputTokens` 不是一回事**：后者是整轮各 step 的累加和（账单
+   * 口径，单步轮相等、多步轮按步数放大）。这个是一次快照。
+   */
+  contextTokens?: number;
+}

package/src/turn/turn-journal.ts

@@ -0,0 +1,102 @@
+import type { Logger } from '../ports/logger.js';
+import type { AgentEvent, AgentEventType } from '../schema/agent-event.js';
+import type { TurnEnvelope } from './turn-envelope.js';
+
+/**
+ * 一轮的事件账本。**同步 append、可回读**——事件流不只是对外广播，它同时是
+ * 内核自己的兜底状态源：`eventsToSteps` 靠它落 `agent_run.steps`，abort 与
+ * 失败路径靠 `partsFromEventBuffer(entries())` 重建这一轮已经产出的 parts。
+ *
+ * **绝不要把它改成异步或 fire-and-forget**：那两条路径会就此失去唯一的依据，
+ * 症状是「被中断的那一轮，已经打出来的字没了」。
+ */
+export interface TurnJournal {
+  /** 记一条并投递出去。**同步**，且在调用点的原位置调用。 */
+  append(type: AgentEventType, payload: unknown): void;
+  /** 回读：`eventsToSteps` / `partsFromEventBuffer` 的输入。 */
+  entries(): readonly AgentEvent[];
+  /**
+   * 把 `mark`（= 某一刻的 `entries().length`）之后的条目**物理删掉**，返回
+   * 被删的那些。
+   *
+   * 账本原则上只增不改——这是它唯一的例外，且只有一个合法调用方：一步的
+   * 模型调用在响应中途断连、内核要作废这一步的半截产出重发时
+   * （`turn-run.ts#settleStep`）。合法的前提是**被删的条目没有一条交给过宿主**：
+   * 从 `startInference` 到 `settleStep` 之间不会有任何 `flushStep`，所以这一
+   * 段账本还没有投影成任何落库 part，删掉它不会让库里出现「已经写进去又消失」
+   * 的东西。反过来说，删掉已经 flush 过的条目会让 `flushedParts` 游标指向一个
+   * 不再存在的前缀——那种错误不会报，只会让下一次 flush 把同一批 part 再落
+   * 一次。**别在别处调它。**
+   *
+   * 已投递出去的事件收不回来，这是刻意的：由调用方紧接着 append 一条
+   * `step-retract` 告诉订阅者「这一段作废」，seq 单调不复用，作废段与重发段
+   * 在流里天然可分。
+   */
+  discardAfter(mark: number): AgentEvent[];
+}
+
+export interface TurnJournalDeps {
+  envelope: TurnEnvelope;
+  /** 该 stream 的 seq 分配器（由壳 open 时取得）。 */
+  nextSeq: () => number;
+  /**
+   * 事件往哪去。**内核对此一无所知**：壳传本轮 recorder 的 `emit`（消息中心，
+   * 见 `TurnRecorder.emit`），单测传一个数组的 push。
+   */
+  sink: (event: AgentEvent) => void;
+  /** sink 抛错时记一条 warn。缺省不记。 */
+  logger?: Logger;
+}
+
+export function createTurnJournal(deps: TurnJournalDeps): TurnJournal {
+  const { envelope, nextSeq, sink, logger } = deps;
+  const entries: AgentEvent[] = [];
+
+  return {
+    append(type, payload) {
+      const event: AgentEvent = {
+        seq: nextSeq(),
+        streamId: envelope.streamId,
+        rootSessionId: envelope.rootSessionId,
+        sessionId: envelope.sessionId,
+        runId: envelope.runId,
+        // **恒等于 runId**：一轮一行，本轮 assistant 输出全部归属那一条。
+        //
+        // 曾经这里每次 append 都重新问一次宿主的 `assistantMessageId()`——软
+        // 插话会在轮中途封口当前段、把后续输出切到新的一行，缓存一次就等于把
+        // 插话之后的全部增量继续投递到已经封口的那条气泡上。那套分段随「换轮」
+        // 一起拆掉了（见 `TurnHost.hasPendingInbox`），宿主不再需要被问。
+        //
+        // **字段本身保留**：它是前端把流式增量路由到气泡的键（`chunk.id`），
+        // wire 形状因此逐字不变。
+        messageId: envelope.runId,
+        parentRunId: envelope.parentRunId ?? null,
+        depth: envelope.depth ?? 0,
+        ts: Date.now(),
+        type,
+        payload,
+      };
+      // **先记账后投递**：账本是承重的（abort 路径靠它重建 parts），sink 不是。
+      entries.push(event);
+      try {
+        sink(event);
+      } catch (err) {
+        // 观测非承重：投递抛错绝不能把一轮成功的生成变成 failed。
+        // `RedisStreamBus.publish` 已经自己吞了序列化异常（那里有判据），但
+        // 账本不该假设每个 sink 都这么守规矩——这是最后一道。
+        //
+        // **不去重、不静默计数**：sink 抛错是 bug 不是常态，压掉只会让它更难
+        // 被发现。
+        logger?.warn(
+          `event sink threw for run ${envelope.runId} (${type}), event still recorded: ${String(err)}`
+        );
+      }
+    },
+    entries() {
+      return entries;
+    },
+    discardAfter(mark) {
+      return entries.splice(mark);
+    },
+  };
+}