@qjp88995/agent-runtime 0.0.0-stage → 0.1.1

package/src/turn/nul-safe.ts

@@ -0,0 +1,22 @@
+/**
+ * 把文本里的 NUL（U+0000）换成 U+FFFD。
+ *
+ * **为什么要有它**：Postgres 的 jsonb 不收 `\u0000`（「\u0000 cannot be
+ * converted to text」），而 `chat_message.parts` 是 jsonb——一段带 NUL 的工具
+ * 输出（`Bash` 里 `cat` 一个二进制文件、沙箱按 UTF-8 解码的 stdout 原样带着
+ * NUL）会让这一轮的落库失败，`agent_run` 也跟着收不了尾，最后被孤儿清扫标成
+ * 「服务中断（进程重启）」——一个与真实原因毫不相干、会把排查带偏的结论。
+ *
+ * **换在哪里是这条的全部要点**：必须在「喂给模型」与「进事件账本（→ 落库、
+ * SSE）」分叉**之前**（`TurnRun.recordToolResult`）。在 `MessageHub` 落库前换
+ * 就晚了：本轮模型看到的是带 NUL 的原文，库里存的却是替换过的，下一轮重放
+ * 与本轮逐字不同——违反「模型看得见的一切都必须能从库里重建」，而且前缀缓存
+ * 从这一条起整段 miss。
+ *
+ * 换成 U+FFFD 而不是删掉：模型能看出「这里原本有东西、不是文本」，与 UTF-8
+ * 解码非法字节时的做法一致；删掉会把 `a\0b` 拼成 `ab`，造出一段文件里并不
+ * 存在的文本。
+ */
+export function replaceNul(text: string): string {
+  return text.includes('\0') ? text.replaceAll('\0', '\uFFFD') : text;
+}

package/src/turn/parts-from-events.ts

@@ -0,0 +1,248 @@
+import { z } from 'zod';
+
+import type { AgentEvent } from '../schema/agent-event.js';
+import {
+  type MessagePart,
+  PartProviderMetadataSchema,
+  ToolResultImageSchema,
+} from '../schema/index.js';
+
+/** `ref` 只接受对象形态（`MessagePart.ref` 是 `Record<string, unknown>`）。 */
+function isPlainRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+const ImagesSchema = z.array(ToolResultImageSchema).min(1);
+
+/**
+ * 工具调用上要回放的厂商 metadata（思考签名）。形状不对就不落——同 `images`：
+ * 进了库就是之后每一轮都发出去的东西。
+ */
+function providerMetadataFromPayload(
+  v: unknown
+): Pick<Extract<MessagePart, { type: 'tool-call' }>, 'providerMetadata'> {
+  if (v === undefined) return {};
+  const parsed = PartProviderMetadataSchema.safeParse(v);
+  return parsed.success ? { providerMetadata: parsed.data } : {};
+}
+
+function imagesFromPayload(
+  v: unknown
+): Pick<Extract<MessagePart, { type: 'tool-result' }>, 'images'> {
+  if (v === undefined) return {};
+  const parsed = ImagesSchema.safeParse(v);
+  return parsed.success ? { images: parsed.data } : {};
+}
+
+/**
+ * 这次重建是不是这一轮的**最后一次**。
+ *
+ * - `'rescue'`（默认，兜底路径）：这一轮已经结束，buffer 里剩下的半截东西
+ *   （没等到 `text-end` 的文本、没等到 `tool-call` 的半截入参）再没有机会被
+ *   封口了，一并抢救出来——中断那一刻已经打出来的字不能丢。
+ * - `'hold'`（增量落库）：轮子还在跑，只交出**已被终止符封口**的 part，半截的
+ *   留在 buffer 里等下一次。这不是洁癖：一个 step 里模型可以并行发起多次调用，
+ *   而落库发生在**逐个**工具执行的间隙——第一次 flush 时第二个调用的入参才流到
+ *   一半，按 `'rescue'` 重建就会凭空落一条「模型从没发出过、参数还是半截 JSON」
+ *   的 tool-call part，等真正的 `tool-call` 事件到了再落一条真的，库里于是两条。
+ */
+export type PartsTail = 'rescue' | 'hold';
+
+/**
+ * 从事件账本重建 parts。**这是落库 parts 的唯一来源**：轮内由
+ * `turn-run.ts#flushStep` 带游标增量取（`tail: 'hold'`），**每一条终态路径**
+ * （正常收尾 / 中断 / 失败 / 门禁拒绝）在 `finish()` 里再取最后一次，那次用
+ * `tail: 'rescue'`。半截 tool call 也抢救出来 —— 先试 JSON.parse，失败就把
+ * 不完整的 JSON 字符串原样存下，便于排查。
+ *
+ * 曾经它只是兜底：主路径另有一套手工累积的 `acc.parts`，两者的等价性靠一句
+ * 注释担保（agent-x 的对应实现漏过 toolName，本仓漏过
+ * `isError`/`ref`/`systemNote`——事件 payload 里一直都有，是这里没读，而两边
+ * 都没有任何测试会红）。现在只剩这一条路，那族判据随之消失。
+ *
+ * **因此本函数的产出必须是「只增不改」的**：已经交出去的 part 不会因为后面又
+ * 来了事件而变形或改变位置——增量落库的游标正是建立在这条性质上（jsonb 追加
+ * 不幂等，落错了改不回来）。今天它成立是因为每种 part 都由一个明确的终止符
+ * 封口：文本靠 `text-end`、reasoning 靠「下一个非 reasoning-delta 事件」、
+ * 工具靠 `tool-call`/`tool-result` 事件本身。
+ *
+ * `reasoning-delta` 单独累积进 reasoningBuf（不与 textBuf 混）——deepseek 的
+ * reasoning 段可以很长，取消极易恰好落在纯 reasoning 阶段、后面再没有任何
+ * text-delta/tool-call 事件；若不认这个事件类型，这类中断会重建出**空** parts
+ * 数组（用户看到一条空白气泡）。`AGENT_EVENT_TYPES` 里没有 `reasoning-end`，
+ * 故 flush 时机改用"下一个非 reasoning-delta 事件到来即先 flush"这条通用规则
+ * （在 switch 之前统一处理），外加循环结束时的收尾 flush——这样即便流从头到
+ * 尾只有 reasoning-delta，也能落出一个 `{type:'reasoning'}` part。这不违反
+ * "reasoning 是回放给模型时唯一允许的有损项"：那条约束在 partsToModelMessages
+ * 里生效，落库层面留着 reasoning 是为了让用户看到取消前发生了什么。
+ *
+ * flushText() 的调用时机：`text-end` 与 `tool-call` 分支都会 flush，
+ * `tool-result` 分支不需要 ——一个 step 内 tool-result 前面必然已经有过
+ * 对应的 tool-call（tool-call 分支已经 flush 过一次），tool-result 本身
+ * 不携带新文本、也不会让 textBuf 重新累积。真正会在 tool-result 之后
+ * 又产生文本的情况，是模型在拿到结果后继续输出（"工具→结果→又有文本"），
+ * 这段新文本会走新的 text-delta 追加进 textBuf，直到下一次 text-end 或
+ * 循环结束时的收尾 flushText() 才落 part —— 顺序仍是
+ * text → tool-call → tool-result → text，与事件的时间顺序一致，未丢失。
+ */
+export function partsFromEventBuffer(
+  events: readonly AgentEvent[],
+  tail: PartsTail = 'rescue'
+): MessagePart[] {
+  return partsFromEventBufferWithBoundary(events, tail).parts;
+}
+
+/**
+ * 重建结果 + **退役边界**。
+ *
+ * `uptoSeq` = 被消费进已交出 part 的**最后一个事件**的 seq（没有交出任何 part
+ * 时为 null）：reasoning 段是它最后一条 `reasoning-delta`（封口它的那个事件
+ * 属于**下一段**，不算）、text 段是 `text-end`、工具是 `tool-call`/`tool-result`
+ * 事件本身。语义是「seq ≤ 它的事件，内容已经全部体现在这些 part 里」——落库成功
+ * 后会话流据此把这些事件退役（`StreamBus.retireUpTo`），刷新重建时它们由 DB 行
+ * 顶替、前端按 `metadata.flushedSeq` 把宽限期内重放的同一批事件丢掉。
+ *
+ * `'hold'` 模式下未封口的尾巴既不进 parts 也不推进边界——那正是「流里只剩未
+ * 落库的尾巴」这条不变量的另一半。
+ */
+export function partsFromEventBufferWithBoundary(
+  events: readonly AgentEvent[],
+  tail: PartsTail = 'rescue'
+): { parts: MessagePart[]; uptoSeq: number | null } {
+  const out: MessagePart[] = [];
+  let uptoSeq: number | null = null;
+  let textBuf = '';
+  let reasoningBuf = '';
+  // 这一段思考的时间窗，取自事件自带的 `ts`（主路径在 runtime 里现测，见
+  // turn-run.ts；这条兜底路径手里只有事件，正好够）。
+  let reasoningFirstTs: number | null = null;
+  let reasoningLastTs = 0;
+  let reasoningLastSeq = 0;
+  const pendingInput = new Map<string, { toolName: string; raw: string }>();
+  const emittedCalls = new Set<string>();
+
+  const flushText = (seq: number) => {
+    if (textBuf) {
+      out.push({ type: 'text', text: textBuf });
+      uptoSeq = seq;
+      textBuf = '';
+    }
+  };
+  const flushReasoning = () => {
+    if (reasoningBuf) {
+      out.push({
+        type: 'reasoning',
+        text: reasoningBuf,
+        // 夹到非负——挂钟回拨会让差值变负（同 turn-run.ts）。
+        ...(reasoningFirstTs != null
+          ? { durationMs: Math.max(0, reasoningLastTs - reasoningFirstTs) }
+          : {}),
+      });
+      uptoSeq = reasoningLastSeq;
+      reasoningBuf = '';
+      reasoningFirstTs = null;
+    }
+  };
+
+  for (const e of events) {
+    const p = e.payload as Record<string, unknown>;
+    // reasoning 必然先于任何跟随其后的事件类型（无 reasoning-end 信号，
+    // 故一见到下一个非 reasoning-delta 事件就把它 flush 出去，保序）。
+    if (e.type !== 'reasoning-delta') flushReasoning();
+    switch (e.type) {
+      case 'text-delta':
+        textBuf += typeof p.text === 'string' ? p.text : '';
+        break;
+      case 'reasoning-delta':
+        reasoningBuf += typeof p.text === 'string' ? p.text : '';
+        reasoningFirstTs ??= e.ts;
+        reasoningLastTs = e.ts;
+        reasoningLastSeq = e.seq;
+        break;
+      case 'text-end':
+        flushText(e.seq);
+        break;
+      case 'tool-input-start':
+        pendingInput.set(String(p.toolCallId), {
+          toolName: String(p.toolName),
+          raw: '',
+        });
+        break;
+      case 'tool-input-delta': {
+        const entry = pendingInput.get(String(p.toolCallId));
+        if (entry) entry.raw += typeof p.delta === 'string' ? p.delta : '';
+        break;
+      }
+      case 'tool-call':
+        flushText(e.seq);
+        pendingInput.delete(String(p.toolCallId));
+        emittedCalls.add(String(p.toolCallId));
+        out.push({
+          type: 'tool-call',
+          toolCallId: String(p.toolCallId),
+          toolName: String(p.toolName),
+          input: p.input,
+          ...providerMetadataFromPayload(p.providerMetadata),
+        });
+        uptoSeq = e.seq;
+        break;
+      case 'tool-result':
+        uptoSeq = e.seq;
+        out.push({
+          type: 'tool-result',
+          toolCallId: String(p.toolCallId),
+          toolName: String(p.toolName),
+          output: p.output,
+          // `isError` / `ref` / `systemNote` 三样事件 payload 里本来就有
+          // （`recordToolResult` 一次 spread 同时喂事件与主路径 part），这条
+          // 兜底路径以前只读 `output`，于是同一次调用走主路径落库带失败标记、
+          // 走重建路径落库就是一条成功的结果。`isError` 尤其是红线级的：
+          // 投影层按它选 `error-json` 变体（parts-to-model-messages.ts），
+          // 丢了就等于下一轮把一次失败的工具调用当成功喂回模型。
+          //
+          // **逐个条件展开、不整体 spread**：主路径的 part 由
+          // `{...outcome}` 得到，`ref`/`systemNote` 没有时是「键不存在」
+          // （JSON 落库后同样不存在），照抄 undefined 会让两条路径的产物在
+          // `toStrictEqual` 下分叉。
+          ...(typeof p.isError === 'boolean' ? { isError: p.isError } : {}),
+          ...(isPlainRecord(p.ref) ? { ref: p.ref } : {}),
+          // `images` 同样来自事件 payload（`recordToolResult` 一次 spread）。
+          // 过一遍 schema 而不是裸 cast：这条兜底路径重建的是要落库的行，一个
+          // 形状不对的 src 进了库，下一轮投影就发出一个解析不了的引用。
+          ...imagesFromPayload(p.images),
+          // 钉住不许裁剪（`AgentTool.persistPinned`）。只认字面的 `true`。
+          ...(p.pinned === true ? { pinned: true } : {}),
+          ...(typeof p.systemNote === 'string'
+            ? { systemNote: p.systemNote }
+            : {}),
+        });
+        break;
+      default:
+        break;
+    }
+  }
+  // 轮子还在跑：半截的一律留在 buffer 里，等封口它的那个事件到了下一次再交
+  // （判据见 `PartsTail`）。
+  if (tail === 'hold') return { parts: out, uptoSeq };
+
+  // 收尾：若流以纯 reasoning 结束（无后续事件触发过 flush），这里补上——
+  // 正是「取消恰好落在纯 reasoning 阶段」那个真实案例的落点。抢救出来的尾巴
+  // 把边界推到最后一个事件：这一轮已经结束，流里的一切都可以退役了。
+  const lastSeq = events.at(-1)?.seq ?? null;
+  flushReasoning();
+  flushText(lastSeq ?? 0);
+
+  // 抢救没等到 tool-call 的半截调用。
+  for (const [toolCallId, { toolName, raw }] of pendingInput) {
+    if (emittedCalls.has(toolCallId)) continue;
+    let input: unknown = raw;
+    try {
+      input = JSON.parse(raw);
+    } catch {
+      // 保持原始字符串，便于排查截断点。
+    }
+    out.push({ type: 'tool-call', toolCallId, toolName, input });
+  }
+  if (out.length > 0 && lastSeq != null) uptoSeq = lastSeq;
+  return { parts: out, uptoSeq };
+}