@allbluecn/web-app 0.12.0 → 0.12.3

package/src/server/ai-gateway/durability/__tests__/reaper.test.ts

@@ -0,0 +1,227 @@
+import { beforeEach, describe, expect, it, vi } from "vitest"
+import type { RunRecord, RunStore } from "@tanstack/ai"
+import type { LockStore } from "@tanstack/ai/locks"
+import type {
+  ReapOptions,
+  ReapResult,
+  RunExitProbe,
+  SandboxCapabilities,
+  SandboxHandle,
+  SandboxInstanceStore,
+  SandboxProvider,
+} from "@tanstack/ai-sandbox"
+import {
+  REAPER_DETACHED_RUN_TTL_MS,
+  REAPER_MAX_RUNS,
+  buildReaperHasFinished,
+  resolveReaperHandle,
+  runReaperCycle,
+  type ReaperCycleDeps,
+} from "../reaper"
+
+vi.mock("@tanstack/ai-sandbox", () => ({
+  probeRunExit: vi.fn(),
+  reapDetachedRuns: vi.fn(),
+  sandboxReclaimer: vi.fn(),
+}))
+
+import {
+  probeRunExit,
+  reapDetachedRuns,
+  sandboxReclaimer,
+} from "@tanstack/ai-sandbox"
+
+const mockedProbe = vi.mocked(probeRunExit)
+const mockedReap = vi.mocked(reapDetachedRuns)
+const mockedReclaimer = vi.mocked(sandboxReclaimer)
+
+const RUN_RECORD: RunRecord = {
+  runId: "run-1",
+  threadId: "thread-1",
+  status: "running",
+  startedAt: 1000,
+  detachedSince: 5000,
+  sandboxKey: "thread:thread-1",
+}
+
+const PROVIDER = {
+  name: "mock",
+  capabilities: () => ({} as SandboxCapabilities),
+  create: vi.fn(),
+  resume: vi.fn(),
+  destroy: vi.fn(),
+} satisfies SandboxProvider
+
+const INSTANCES = {
+  get: vi.fn(),
+  upsert: vi.fn(),
+  delete: vi.fn(),
+} satisfies SandboxInstanceStore
+
+function deps(overrides: Partial<ReaperCycleDeps> = {}): ReaperCycleDeps {
+  return {
+    runs: { get: vi.fn(), update: vi.fn() } as unknown as RunStore,
+    locks: { acquire: vi.fn() } as unknown as LockStore,
+    durability: vi.fn(),
+    drive: vi.fn(),
+    instances: INSTANCES,
+    provider: PROVIDER,
+    ...overrides,
+  }
+}
+
+function instance(key = "thread:thread-1") {
+  return { key, provider: "mock", providerSandboxId: "sb-1", threadId: "thread-1" }
+}
+
+const HANDLE = { id: "sb-1" } as unknown as SandboxHandle
+
+describe("resolveReaperHandle", () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it("run 无 sandboxKey 时返回 null（非沙箱 run，不查实例也不 resume）", async () => {
+    for (const record of [{ ...RUN_RECORD, sandboxKey: undefined }, { ...RUN_RECORD, sandboxKey: "" }]) {
+      expect(await resolveReaperHandle(record, deps())).toBeNull()
+    }
+    expect(INSTANCES.get).not.toHaveBeenCalled()
+    expect(PROVIDER.resume).not.toHaveBeenCalled()
+  })
+
+  it("实例记录已删时返回 null（resume 不被调用）", async () => {
+    INSTANCES.get.mockResolvedValue(null)
+    expect(await resolveReaperHandle(RUN_RECORD, deps())).toBeNull()
+    expect(PROVIDER.resume).not.toHaveBeenCalled()
+  })
+
+  it("provider 不符时返回 null——绝不用一个 provider 的 id 去 resume 另一个 provider", async () => {
+    INSTANCES.get.mockResolvedValue({ ...instance(), provider: "daytona" })
+    expect(await resolveReaperHandle(RUN_RECORD, deps())).toBeNull()
+    expect(PROVIDER.resume).not.toHaveBeenCalled()
+  })
+
+  it("provider 相符时用实例记录的 providerSandboxId resume", async () => {
+    INSTANCES.get.mockResolvedValue(instance())
+    PROVIDER.resume.mockResolvedValue(HANDLE)
+
+    await expect(resolveReaperHandle(RUN_RECORD, deps())).resolves.toBe(HANDLE)
+    expect(INSTANCES.get).toHaveBeenCalledWith("thread:thread-1")
+    expect(PROVIDER.resume).toHaveBeenCalledWith({ id: "sb-1" })
+  })
+
+  it("provider.resume 抛错时返回 null 而不抛——单个 run 的探针异常不能炸掉整个 sweep", async () => {
+    INSTANCES.get.mockResolvedValue(instance())
+    PROVIDER.resume.mockRejectedValue(new Error("sandbox gone"))
+    expect(await resolveReaperHandle(RUN_RECORD, deps())).toBeNull()
+  })
+})
+
+describe("buildReaperHasFinished", () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it("句柄可解析时按 { handle, runId } 调 probeRunExit", async () => {
+    INSTANCES.get.mockResolvedValue(instance())
+    PROVIDER.resume.mockResolvedValue(HANDLE)
+    mockedProbe.mockResolvedValue({ state: "producing" })
+
+    await expect(buildReaperHasFinished(deps())(RUN_RECORD)).resolves.toEqual({
+      state: "producing",
+    })
+    expect(mockedProbe).toHaveBeenCalledWith({ handle: HANDLE, runId: "run-1" })
+  })
+
+  it("句柄不可解析时答 'unknown'（fail-safe 方向）且不触碰 probe", async () => {
+    INSTANCES.get.mockResolvedValue(null)
+    await expect(buildReaperHasFinished(deps())(RUN_RECORD)).resolves.toEqual({
+      state: "unknown",
+      error: "no-live-sandbox-handle",
+    })
+    expect(mockedProbe).not.toHaveBeenCalled()
+  })
+
+  it("probeRunExit 抛错时降级为 'unknown'，异常对象保留在 error 上", async () => {
+    INSTANCES.get.mockResolvedValue(instance())
+    PROVIDER.resume.mockResolvedValue(HANDLE)
+    const boom = new Error("journal unreadable")
+    mockedProbe.mockRejectedValue(boom)
+
+    await expect(buildReaperHasFinished(deps())(RUN_RECORD)).resolves.toEqual({
+      state: "unknown",
+      error: boom,
+    })
+  })
+})
+
+describe("runReaperCycle 装配", () => {
+  const RESULT: ReapResult = {
+    considered: 0,
+    probed: 0,
+    outcomes: {
+      finalized: 0,
+      expired: 0,
+      producing: 0,
+      unknown: 0,
+      "budget-exceeded": 0,
+      "not-claimed": 0,
+      "reclaim-failed": 0,
+      failed: 0,
+    },
+    runs: [],
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockedReap.mockResolvedValue(RESULT)
+  })
+
+  it("传入 sweep 时钟、默认 TTL、默认批量上限与 reclaim 适配器", async () => {
+    await runReaperCycle(deps({ now: 12345 }))
+
+    expect(mockedReap).toHaveBeenCalledTimes(1)
+    const options = mockedReap.mock.calls[0]![0] as ReapOptions
+    expect(options.now).toBe(12345)
+    expect(options.detachedRunTtlMs).toBe(REAPER_DETACHED_RUN_TTL_MS)
+    expect(options.maxRuns).toBe(REAPER_MAX_RUNS)
+    expect(options.runBudgetMs).toBeUndefined()
+    expect(mockedReclaimer).toHaveBeenCalledWith({
+      provider: PROVIDER,
+      instances: INSTANCES,
+    })
+    expect(options.reclaim).toBe(mockedReclaimer.mock.results[0].value)
+  })
+
+  it("now 缺省时用 Date.now，调用方传入的 TTL / 批量 / 预算覆盖默认值", async () => {
+    const nowSpy = vi.spyOn(Date, "now").mockReturnValue(99999)
+    try {
+      await runReaperCycle(
+        deps({
+          detachedRunTtlMs: 60_000,
+          maxRuns: 5,
+          runBudgetMs: 15_000,
+        }),
+      )
+      const options = mockedReap.mock.calls[0]![0] as ReapOptions
+      expect(options.now).toBe(99999)
+      expect(options.detachedRunTtlMs).toBe(60_000)
+      expect(options.maxRuns).toBe(5)
+      expect(options.runBudgetMs).toBe(15_000)
+    } finally {
+      nowSpy.mockRestore()
+    }
+  })
+
+  it("runs / locks / durability / drive 原样透传（同一引用），hasFinished 由 buildReaperHasFinished 生成", async () => {
+    const d = deps()
+    await runReaperCycle(d)
+
+    const options = mockedReap.mock.calls[0]![0] as ReapOptions
+    expect(options.runs).toBe(d.runs)
+    expect(options.locks).toBe(d.locks)
+    expect(options.durability).toBe(d.durability)
+    expect(options.drive).toBe(d.drive)
+    expect(typeof options.hasFinished).toBe("function")
+  })
+})

package/src/server/ai-gateway/durability/pg-stream.ts

@@ -0,0 +1,355 @@
+import type { UpsertableStreamDurability } from "@tanstack/ai"
+import { resolveResumeRunId } from "@tanstack/ai"
+import { prisma, Prisma } from "@allbluecn/database"
+
+/**
+ * chunk 载荷的 JSON 边界类型。StreamChunk 未从 @tanstack/ai 主入口导出，
+ * 这里从 adapter 契约反推，避免依赖包内部子路径。
+ */
+type DurabilityChunk = Parameters<UpsertableStreamDurability["append"]>[0][number]
+
+/** 终态标记行——read 遇到即停止 tail，snapshot 排除。 */
+const TERMINAL_CHUNK = { __aiStreamTerminal: true } as const
+
+/** BigInt id 的字符串形态（pg bigserial 实际不会超过 18 位）。 */
+const MINTED_OFFSET_RE = /^\d{1,18}$/
+
+const READ_BATCH_SIZE = 64
+const TAIL_POLL_MS = 500
+const FIRST_CHUNK_DEADLINE_MS = 100
+
+function assertValidRunId(runId: string): string {
+  if (runId.length === 0 || /[\r\n]/.test(runId)) {
+    throw new Error(`invalid runId (must be non-empty, no CR/LF): ${JSON.stringify(runId)}`)
+  }
+  return runId
+}
+
+function isTerminal(chunk: unknown): boolean {
+  return (
+    typeof chunk === "object" &&
+    chunk !== null &&
+    Object.hasOwn(chunk as Record<string, unknown>, "__aiStreamTerminal")
+  )
+}
+
+/** chunk 存 Prisma Json 列：round-trip 一次，剥掉 undefined 与 class 外壳。 */
+function toJson(chunk: DurabilityChunk): Prisma.InputJsonValue {
+  return JSON.parse(JSON.stringify(chunk)) as Prisma.InputJsonValue
+}
+
+function fromJson(chunk: unknown): DurabilityChunk {
+  return chunk as DurabilityChunk
+}
+
+function abortError(): Error {
+  return new DOMException("The operation was aborted", "AbortError")
+}
+
+async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError())
+      return
+    }
+    const onAbort = () => {
+      clearTimeout(timer)
+      reject(abortError())
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort)
+      resolve()
+    }, ms)
+    signal?.addEventListener("abort", onAbort, { once: true })
+  })
+}
+
+/**
+ * resume offset 的读取口径与官方 memoryStream 完全一致：
+ * `Last-Event-ID` header 优先，其次 `?offset` query。
+ * 官方实现未导出，这里复制契约而非重造，保证两个 adapter 对「消费端已读到哪」的
+ * 认定永不分歧。
+ */
+function readResumeOffset(request: Request): string | null {
+  const header = request.headers.get("Last-Event-ID")
+  if (header) return header
+  try {
+    return new URL(request.url).searchParams.get("offset")
+  } catch {
+    return null
+  }
+}
+
+interface ChunkRow {
+  id: bigint
+  chunk: unknown
+}
+
+/** 当前 tail 行——既用于 "now" 定位，也用于判断 log 是否已终态。 */
+async function tailRow(runId: string): Promise<ChunkRow | null> {
+  const row = await prisma.aiStreamChunk.findFirst({
+    where: { runId },
+    orderBy: { id: "desc" },
+    select: { id: true, chunk: true },
+  })
+  return row ? { id: row.id, chunk: row.chunk } : null
+}
+
+async function appendChunks(runId: string, chunks: DurabilityChunk[]): Promise<string[]> {
+  if (chunks.length === 0) return []
+  return prisma.$transaction(async (tx) => {
+    const offsets: string[] = []
+    for (const chunk of chunks) {
+      const row = await tx.aiStreamChunk.create({
+        data: { runId, chunk: toJson(chunk) },
+      })
+      offsets.push(String(row.id))
+    }
+    return offsets
+  })
+}
+
+async function closeRun(runId: string): Promise<void> {
+  const existing = await prisma.aiStreamChunk.count({
+    where: {
+      runId,
+      chunk: { equals: TERMINAL_CHUNK as Prisma.InputJsonValue },
+    },
+  })
+  if (existing > 0) return
+  await prisma.aiStreamChunk.create({
+    data: { runId, chunk: TERMINAL_CHUNK as Prisma.InputJsonValue },
+  })
+}
+
+/**
+ * read 的 tail 语义：读尽当前批次，批空则等终态或轮询新 chunk。
+ * from-start（"-1"）的 join 若始终空 log，按 FIRST_CHUNK_DEADLINE_MS 抛错，
+ * 对齐 memoryStream 的「接了一个从不产出的 run」边界行为。
+ */
+async function* readRun(
+  runId: string,
+  offset: string,
+  signal?: AbortSignal,
+): AsyncGenerator<{ offset: string; chunk: DurabilityChunk }> {
+  const fromStart = offset === "-1" || offset === ""
+  let cursor: bigint | null
+  if (fromStart) {
+    cursor = null
+  } else if (offset === "now") {
+    const tail = await tailRow(runId)
+    if (tail === null) {
+      cursor = null
+    } else {
+      cursor = tail.id
+      // tail 本身就是终态行：没有任何可回放内容，直接返回而非陷入 poll。
+      if (isTerminal(tail.chunk)) return
+    }
+  } else if (MINTED_OFFSET_RE.test(offset)) {
+    cursor = BigInt(offset)
+  } else {
+    // 外来 cursor（含 memoryStream 的 versioned cursor）：退化为 from-start，
+    // 而不是当 producer 处理——本请求带了 Last-Event-ID，语义是「join 续读」。
+    cursor = null
+  }
+
+  const deadlineAt = fromStart ? Date.now() + FIRST_CHUNK_DEADLINE_MS : null
+  // deadline 只约束「一个从不产出的 run」——收到过 chunk 后 producer 暂停是正常
+  // 状态（生成间隙），继续 tail 等待而非判定超时。
+  let everSeen = false
+
+  for (;;) {
+    if (signal?.aborted) return
+
+    const rows = await prisma.aiStreamChunk.findMany({
+      where: { runId, id: cursor === null ? undefined : { gt: cursor } },
+      orderBy: { id: "asc" },
+      take: READ_BATCH_SIZE,
+    })
+
+    if (rows.length === 0) {
+      // cursor 之后无行，但 tail 是终态行：log 已结束，立即返回而非无限 poll。
+      const tail = await tailRow(runId)
+      if (tail !== null && tail.id <= (cursor ?? 0n) && isTerminal(tail.chunk)) return
+
+      if (!everSeen && deadlineAt !== null && Date.now() > deadlineAt) {
+        throw new Error(`no chunk within ${FIRST_CHUNK_DEADLINE_MS}ms for run ${runId}`)
+      }
+      await sleep(TAIL_POLL_MS, signal)
+      continue
+    }
+
+    let terminal = false
+    for (const row of rows) {
+      const chunk = fromJson(row.chunk)
+      if (isTerminal(chunk)) {
+        terminal = true
+        break
+      }
+      everSeen = true
+      cursor = row.id
+      yield { offset: String(row.id), chunk }
+    }
+
+    if (terminal) return
+    if (rows.length < READ_BATCH_SIZE) {
+      await sleep(TAIL_POLL_MS, signal)
+    }
+  }
+}
+
+async function snapshotRun(runId: string): Promise<Array<{ offset: string; chunk: DurabilityChunk }>> {
+  const rows = await prisma.aiStreamChunk.findMany({
+    where: { runId },
+    orderBy: { id: "asc" },
+  })
+  const out: Array<{ offset: string; chunk: DurabilityChunk }> = []
+  for (const row of rows) {
+    if (isTerminal(row.chunk)) break
+    out.push({ offset: String(row.id), chunk: fromJson(row.chunk) })
+  }
+  return out
+}
+
+/**
+ * upsert 的四条硬校验——全部在变更之前完成，一次失败绝不部分落库：
+ * ① offset 必须是本 adapter 铸造的形态  ② 拒绝外来（未落库）offset
+ * ③ 拒绝批内重复  ④ 拒绝稀疏空洞。
+ */
+async function upsertRun(
+  runId: string,
+  entries: Array<{ chunk: DurabilityChunk; offset: string }>,
+): Promise<string[]> {
+  if (entries.length === 0) return []
+
+  for (const entry of entries) {
+    if (!MINTED_OFFSET_RE.test(entry.offset)) {
+      throw new Error(`upsert 拒绝外来 offset：${entry.offset}`)
+    }
+  }
+
+  const offsets = entries.map((e) => e.offset)
+  if (new Set(offsets).size !== offsets.length) {
+    throw new Error("upsert 拒绝批内重复 offset")
+  }
+
+  const ids = offsets.map((o) => BigInt(o))
+  const stored = await prisma.aiStreamChunk.findMany({
+    where: { runId, id: { in: ids } },
+    select: { id: true, chunk: true },
+  })
+  const storedByOffset = new Map(stored.map((r) => [r.id.toString(), r.chunk]))
+
+  for (const offset of offsets) {
+    if (storedByOffset.get(offset) === undefined) {
+      throw new Error(`upsert 拒绝未铸造 offset：${offset}`)
+    }
+  }
+  for (const row of stored) {
+    if (isTerminal(row.chunk)) {
+      throw new Error(`upsert 拒绝覆盖终态标记行：${row.id}`)
+    }
+  }
+
+  const sorted = [...ids].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+  for (let i = 1; i < sorted.length; i++) {
+    if (sorted[i] - sorted[i - 1] !== 1n) {
+      throw new Error("upsert 拒绝稀疏空洞")
+    }
+  }
+
+  await prisma.$transaction(async (tx) => {
+    for (const entry of entries) {
+      await tx.aiStreamChunk.update({
+        where: { id: BigInt(entry.offset) },
+        data: { chunk: toJson(entry.chunk) },
+      })
+    }
+  })
+
+  return offsets
+}
+
+function makePgDurability(runId: string, resumeOffset: string | null): UpsertableStreamDurability {
+  return {
+    resumeFrom: () => resumeOffset,
+    append: (chunks) => appendChunks(runId, chunks),
+    read: (offset, signal) => readRun(runId, offset, signal),
+    close: () => closeRun(runId),
+    snapshot: () => snapshotRun(runId),
+    upsert: (entries) => upsertRun(runId, entries),
+  }
+}
+
+/**
+ * run 粒度 adapter：runId 闭包、无请求上下文。reaper 与
+ * PgStreamDurabilityFactory.forRun 共用——cron 没有 Request 可传，而
+ * ReapOptions.durability 的契约形态本就是 (runId) => StreamDurability。
+ */
+export function pgRunDurability(runId: string): UpsertableStreamDurability {
+  return makePgDurability(assertValidRunId(runId), null)
+}
+
+export interface PgStreamDurabilityFactory {
+  /** 请求级 fallback key；未提供时 factory 自动生成 pending:* 键。 */
+  readonly fallbackRunKey: string | undefined
+  /** POST/GET resume 用：runId 未知场景，chunk 落 fallback key 下。 */
+  resumeAdapter(): UpsertableStreamDurability
+  /** 每 run 一实例（runId 闭包）——withSandbox / reaper 的契约形态。 */
+  forRun(runId: string): UpsertableStreamDurability
+  /**
+   * withSandbox 拿到真实 runId 后调用：把 fallback key 的行收敛到正式 runId。
+   * 幂等——重复调用只是 0 行更新。
+   */
+  attachToRun(runId: string): Promise<number>
+}
+
+/**
+ * PG StreamDurability factory（P3 任务 4）。
+ *
+ * 导出形态是 factory 而非单例，这是包契约要求：ReapOptions.durability 与
+ * withSandbox 的 durability 通道都以 run 为粒度取 adapter，需要闭包持有 runId。
+ *
+ * offset 是 ai_stream_chunks.id 的字符串形态——bigserial 单调递增，天然可重放。
+ * runId 提取直接用官方 resolveResumeRunId（X-Run-Id header 优先 → ?runId query），
+ * 与 resumeServerSentEventsResponse 的 run driver 共享同一实现，adapter 与 helper
+ * 不可能对「请求指的是哪个 run」产生分歧。
+ */
+export function pgStreamDurabilityFactory(
+  request: Request,
+  options?: { fallbackRunKey?: string },
+): PgStreamDurabilityFactory {
+  const rawOffset = readResumeOffset(request)
+  // 请求带了 Last-Event-ID / ?offset 就是 join：即便 cursor 不可识别（跨 adapter
+  // 遗留的 memoryStream versioned cursor），也不能返回 null——null 会被当成 producer。
+  const resumeOffset = rawOffset === null
+    ? null
+    : rawOffset === "now"
+      ? "now"
+      : MINTED_OFFSET_RE.test(rawOffset)
+        ? rawOffset
+        : "-1"
+
+  const requestedRunId = resolveResumeRunId(request)
+  const fallbackRunKey = options?.fallbackRunKey
+  const producerRunKey = requestedRunId ?? fallbackRunKey ?? `pending:${crypto.randomUUID()}`
+
+  return {
+    fallbackRunKey,
+    resumeAdapter() {
+      return makePgDurability(assertValidRunId(producerRunKey), resumeOffset)
+    },
+    forRun(runId: string) {
+      return pgRunDurability(runId)
+    },
+    async attachToRun(runId: string) {
+      const target = assertValidRunId(runId)
+      if (!fallbackRunKey || fallbackRunKey === target) return 0
+      const result = await prisma.aiStreamChunk.updateMany({
+        where: { runId: fallbackRunKey },
+        data: { runId: target },
+      })
+      return result.count
+    },
+  }
+}

package/src/server/ai-gateway/durability/reaper-driver.ts

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// AllBlue - 理想之海
+// Copyright (C) 2026 AllBlue Contributors
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+// GNU Affero General Public License for more details.
+//
+// You should have received a copy of the GNU Affero General Public License
+// along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+import type { StreamChunk } from "@tanstack/ai"
+import type { ReapOptions } from "@tanstack/ai-sandbox"
+import { sandboxRunDriver } from "@tanstack/ai-sandbox"
+import { prisma } from "@allbluecn/database"
+import { pgRunDurability } from "../durability/pg-stream"
+import { buildChatStreamWithTools } from "../chat-stream-builder"
+import { resolveOverrides } from "../runs/resolve-overrides"
+
+/**
+ * reaper 的 drive 装配口——P3 任务 11 接线。
+ *
+ * 通过 sandboxRunDriver 把每个到期 run 的剩余 journal 事件重放到 run log：
+ * 1. 从 RunRecord 反查 threadId → chatThread.userId + agentId
+ * 2. 用 userId + agentId 调用 resolveOverrides 获取 agent 配置
+ *    （systemPrompt / knowledgeBaseIds / allowedTools / temperature）
+ * 3. 以 attach: true 调用 buildChatStreamWithTools，read 已有沙箱 journal
+ *    而非新开 agent——journal 已终态时 adapter 仅回放已存事件，不产生新 token
+ *
+ * 多实例部署下 drive 由各自实例独立执行（reapDetachedRuns 自身幂等），
+ * 跨实例重复 replay 由 pgLockStore 互斥兜底。
+ */
+export function buildReaperDrive(): ReapOptions["drive"] | null {
+  return async function* ({ runId, threadId, signal }: {
+    runId: string
+    threadId: string
+    signal: AbortSignal
+  }): AsyncIterable<StreamChunk> {
+    const thread = await prisma.chatThread.findUnique({
+      where: { id: threadId },
+      select: { userId: true, agentId: true },
+    })
+    if (!thread) return
+
+    const overrides = await resolveOverrides(thread.userId, thread.agentId ?? undefined)
+    const userMessages = [{ role: "user" as const, content: "" }]
+
+    const stream = await buildChatStreamWithTools({
+      adapter: null as never,
+      userId: thread.userId,
+      messages: userMessages,
+      threadId,
+      runId,
+      sandbox: true,
+      attach: true,
+      durabilityFactory: {
+        // reaper 场景 runId 已知且无 fallback 行需要收敛（attachToRun 幂等 0）。
+        fallbackRunKey: undefined,
+        resumeAdapter: () => pgRunDurability(runId),
+        forRun: (id) => pgRunDurability(id),
+        attachToRun: async () => 0,
+      },
+      ...(overrides?.agent?.persona ? { systemPrompts: [overrides.agent.persona] } : {}),
+      ...(overrides?.allowedTools ? { allowedTools: overrides.allowedTools } : {}),
+      ...(overrides?.knowledgeBaseIds ? { knowledgeBaseIds: overrides.knowledgeBaseIds } : {}),
+      ...(overrides?.temperature != null ? { temperature: overrides.temperature } : {}),
+    })
+
+    for await (const chunk of stream) {
+      if (signal.aborted) break
+      yield chunk
+    }
+  }
+}