@tanstack/ai-sandbox-cloudflare 0.2.3 → 0.3.0

package/src/durability.ts

@@ -0,0 +1,164 @@
+/**
+ * The portable seams over a {@link RunEventLog} — what makes the coordinator a
+ * platform *binding* of core's run driver rather than a parallel architecture.
+ *
+ * Core's `pipeToRunLog` / `RunController` (`@tanstack/ai-sandbox`) drive a run
+ * through two seams: a `RunStore` for the lifecycle record and a per-run
+ * `StreamDurability` for the event log. On Cloudflare both are backed by the
+ * SAME Durable Object storage — the run log's `rec:` record is core's
+ * {@link RunLogRecord} and its `evt:` rows are the chunks — so this module is
+ * two thin views over one log:
+ *
+ * - {@link runLogStore} — the log as a `RunStore`;
+ * - {@link runLogStream} — one run of the log as a `StreamDurability`.
+ *
+ * The fusion has one consequence worth naming: the record's `status` and the
+ * log's terminal state are the same field. Core's driver terminalizes through
+ * `runs.update(...)` and then calls `durability.close()`; on this backend the
+ * `update` already ended the log (and woke its readers — see
+ * {@link RunEventLog.update}), so `close()` is normally a no-op. It still maps
+ * to `finish('completed')` for the one path where it isn't: an `update` that
+ * failed would otherwise leave readers parked on a log nothing will ever end.
+ */
+import type { RunStore, StreamChunk, StreamDurability } from '@tanstack/ai'
+import type { RunEventLog } from './run-log'
+
+/**
+ * Expose a {@link RunEventLog} as core's `RunStore`, for the `runs` half of
+ * `RunDeps`. A pure rename layer — the invariants (idempotent `createOrResume`,
+ * no-op `update` on an unknown run) are the log's own.
+ */
+export function runLogStore(log: RunEventLog): RunStore {
+  return {
+    // `status` is accepted but ignored: a log run always opens `'running'`,
+    // which is also `createOrResume`'s documented default, and core's driver
+    // never passes anything else.
+    createOrResume: ({ runId, threadId, startedAt }) =>
+      log.open({ runId, threadId, startedAt }),
+    update: (runId, patch) => log.update(runId, patch),
+    get: (runId) => log.get(runId),
+    findActiveRun: async (threadId) => {
+      let active = null
+      for (const record of await log.list()) {
+        if (record.threadId !== threadId || record.status !== 'running') {
+          continue
+        }
+        if (active === null || record.startedAt > active.startedAt) {
+          active = record
+        }
+      }
+      return active
+    },
+  }
+}
+
+const RUN_LOG_OFFSET_PREFIX = 'cfrunlog:v1:'
+
+function encodeOffset(runId: string, seq: number): string {
+  return `${RUN_LOG_OFFSET_PREFIX}${encodeURIComponent(runId)}:${seq}`
+}
+
+function decodeOffset(offset: string): { runId: string; seq: number } {
+  if (!offset.startsWith(RUN_LOG_OFFSET_PREFIX)) {
+    throw new Error(`Invalid run-log stream offset: ${offset}`)
+  }
+  const encoded = offset.slice(RUN_LOG_OFFSET_PREFIX.length)
+  const separator = encoded.lastIndexOf(':')
+  if (separator === -1) {
+    throw new Error(`Invalid run-log stream offset: ${offset}`)
+  }
+  const runId = decodeURIComponent(encoded.slice(0, separator))
+  const seq = Number(encoded.slice(separator + 1))
+  if (!Number.isSafeInteger(seq) || seq < 0) {
+    throw new Error(`Invalid run-log stream offset: ${offset}`)
+  }
+  return { runId, seq }
+}
+
+/** Construction input for {@link runLogStream}. */
+export interface RunLogStreamInit {
+  /** The run this durability adapter attaches to. */
+  runId: string
+  /**
+   * Resume offset captured by the consumer (`resumeFrom()` returns it).
+   * Defaults to `null` (a producer / from-start reader).
+   */
+  offset?: string | null
+}
+
+/**
+ * Expose one run of a {@link RunEventLog} as core's `StreamDurability`, for the
+ * `durability` half of `RunDeps`: `(runId) => runLogStream(log, { runId })`.
+ *
+ * The run must already exist — core's driver guarantees it (`createOrResume`
+ * runs before the first `append`), and a standalone consumer opens it first.
+ * `append` and `read` on an unknown run reject, per the log's own contract;
+ * `snapshot` resolves `[]`, per `StreamDurability`'s.
+ *
+ * Offsets encode the log's monotonic `seq` (versioned, run-scoped, opaque to
+ * callers). The `'-1'` (from-start) and `'now'` (tail-only) read sentinels
+ * every shipped backend honors are supported.
+ */
+export function runLogStream(
+  log: RunEventLog,
+  init: RunLogStreamInit,
+): StreamDurability {
+  const { runId } = init
+  const resumeOffset = init.offset ?? null
+
+  const seqAfter = async (offset: string): Promise<number> => {
+    if (offset === '-1') return -1
+    if (offset === 'now') return (await log.get(runId))?.lastSeq ?? -1
+    const decoded = decodeOffset(offset)
+    if (decoded.runId !== runId) {
+      throw new Error(
+        `Run-log stream offset belongs to run ${JSON.stringify(decoded.runId)}, not ${JSON.stringify(runId)}`,
+      )
+    }
+    return decoded.seq
+  }
+
+  return {
+    resumeFrom: () => resumeOffset,
+    append: async (chunks) => {
+      const offsets: Array<string> = []
+      for (const chunk of chunks) {
+        offsets.push(encodeOffset(runId, await log.append(runId, chunk)))
+      }
+      return offsets
+    },
+    read: async function* (offset, signal) {
+      const fromSeq = await seqAfter(offset)
+      const events = log.read(runId, {
+        fromSeq,
+        ...(signal !== undefined ? { signal } : {}),
+      })
+      for await (const event of events) {
+        yield { offset: encodeOffset(runId, event.seq), chunk: event.chunk }
+      }
+    },
+    // See the module header: normally a no-op (the driver's terminal
+    // `runs.update` already ended the shared record); `'completed'` lands only
+    // when that update failed, where unwedging parked readers beats leaving
+    // them on a log nothing will ever end.
+    close: () => log.finish(runId, 'completed'),
+    snapshot: async () => {
+      const record = await log.get(runId)
+      // Unknown run resolves to [] — the contract forbids reusing the
+      // unknown-run failure path a from-start `read` join takes.
+      if (record === null || record.lastSeq < 0) return []
+      const lastSeq = record.lastSeq
+      const entries: Array<{ offset: string; chunk: StreamChunk }> = []
+      for await (const event of log.read(runId, { fromSeq: -1 })) {
+        entries.push({
+          offset: encodeOffset(runId, event.seq),
+          chunk: event.chunk,
+        })
+        // Stop at the lastSeq captured BEFORE the read: `read` live-tails an
+        // open log, and a snapshot must return a point-in-time view instead.
+        if (event.seq >= lastSeq) break
+      }
+      return entries
+    },
+  }
+}

package/src/handle.ts

@@ -39,6 +39,11 @@ export const CLOUDFLARE_CAPS: SandboxCapabilities = {
   backgroundProcesses: true,
   // No writable host→process stdin; stdin-fed harnesses use file-redirection.
   writableStdin: false,
+  // `spawnProcess.kill()` is a no-op (see the comment in `spawnProcess`) and
+  // the caller's abort signal is never forwarded to `sandbox.exec` — on
+  // `exec` as well as `spawn` — so a spawned follower process (e.g. `tail -f`)
+  // can never be stopped by the caller here.
+  killableProcesses: false,
   snapshots: false,
   networkPolicy: false,
   durableFilesystem: false,

package/src/run-log-do.ts

@@ -7,32 +7,47 @@
  * between chunks all resume cleanly: replay everything after the client's
  * `lastSeq`, then live-tail to terminal.
  *
- * Mirrors {@link InMemoryRunEventLog} from `@tanstack/ai-sandbox` exactly.
+ * Mirrors {@link InMemoryRunEventLog} exactly.
  * Storage layout (keys scoped by `runId` so one DO can host many runs):
- * - `rec:<runId>`        → the {@link RunRecord}
+ * - `rec:<runId>`        → the {@link RunLogRecord}
  * - `evt:<runId>:<seq8>` → the chunk for that seq (seq zero-padded to 8 digits
  *                          so `list({ prefix })` returns events in seq order).
  *
+ * LIVE-DATA MIGRATION: `rec:` values written before the run vocabulary
+ * converged on core's (see the module header in `./run-log`) are converted by
+ * {@link migrateStoredRunRecord} on first read and written back immediately, so
+ * each record pays the conversion exactly once and every read path — `get`,
+ * `append`'s precondition check, the watchdog's {@link list} — observes only
+ * the converged layout. Event values (`evt:`) are raw chunks and need no
+ * migration.
+ *
  * The live-tail wake-up (the in-memory waiter set) is per-INSTANCE; if the
  * instance is evicted mid-run, a reader re-reads the persisted backlog and the
  * `TAIL_POLL_MS` fallback poll keeps it progressing. No event is ever lost.
  *
  * NOTE: Workers-runtime code — compiles against `@cloudflare/workers-types`.
  */
-import { isTerminalRunStatus } from '@tanstack/ai-sandbox'
+import { isTerminalRunStatus } from '@tanstack/ai'
+import { migrateStoredRunRecord } from './run-log'
 import type {
-  RunError,
   RunEvent,
   RunEventLog,
   RunEventLogReadOptions,
-  RunRecord,
-  TerminalRunStatus,
-} from '@tanstack/ai-sandbox'
-import type { StreamChunk } from '@tanstack/ai'
+  RunLogRecord,
+  RunRecordPatch,
+} from './run-log'
+import type { RunError, StreamChunk, TerminalRunStatus } from '@tanstack/ai'
 
 /** How long a post-eviction reader waits before re-polling storage (ms). */
 const TAIL_POLL_MS = 250
 
+/**
+ * What a `rec:` key may hold: the converged layout, or the pre-convergence one
+ * `migrateStoredRunRecord` still reads. Typed as the migration function's input
+ * so a read is forced through it.
+ */
+type StoredRunRecord = Parameters<typeof migrateStoredRunRecord>[0]
+
 const recKey = (runId: string): string => `rec:${runId}`
 const evtKey = (runId: string, seq: number): string =>
   `evt:${runId}:${String(seq).padStart(8, '0')}`
@@ -44,8 +59,21 @@ export class DurableObjectRunEventLog implements RunEventLog {
 
   constructor(private readonly storage: DurableObjectStorage) {}
 
-  private async require(runId: string): Promise<RunRecord> {
-    const record = await this.storage.get<RunRecord>(recKey(runId))
+  /**
+   * Read (and, when needed, migrate + write back) the record under `rec:<runId>`.
+   * The single storage read path — everything else goes through here so no
+   * caller can observe the legacy layout.
+   */
+  private async getRecord(runId: string): Promise<RunLogRecord | null> {
+    const stored = await this.storage.get<StoredRunRecord>(recKey(runId))
+    if (!stored) return null
+    const { record, migrated } = migrateStoredRunRecord(stored)
+    if (migrated) await this.storage.put(recKey(runId), record)
+    return record
+  }
+
+  private async require(runId: string): Promise<RunLogRecord> {
+    const record = await this.getRecord(runId)
     if (!record) throw new Error(`run-log: unknown runId "${runId}"`)
     return record
   }
@@ -59,16 +87,20 @@ export class DurableObjectRunEventLog implements RunEventLog {
     for (const resolve of pending) resolve()
   }
 
-  async open(input: { runId: string; threadId?: string }): Promise<RunRecord> {
-    const existing = await this.storage.get<RunRecord>(recKey(input.runId))
+  async open(input: {
+    runId: string
+    threadId: string
+    startedAt?: number
+  }): Promise<RunLogRecord> {
+    const existing = await this.getRecord(input.runId)
     if (existing) return existing
     const now = Date.now()
-    const record: RunRecord = {
+    const record: RunLogRecord = {
       runId: input.runId,
-      ...(input.threadId !== undefined ? { threadId: input.threadId } : {}),
+      threadId: input.threadId,
       status: 'running',
       lastSeq: -1,
-      createdAt: now,
+      startedAt: input.startedAt ?? now,
       updatedAt: now,
     }
     await this.storage.put(recKey(input.runId), record)
@@ -83,7 +115,11 @@ export class DurableObjectRunEventLog implements RunEventLog {
       )
     }
     const seq = record.lastSeq + 1
-    const next: RunRecord = { ...record, lastSeq: seq, updatedAt: Date.now() }
+    const next: RunLogRecord = {
+      ...record,
+      lastSeq: seq,
+      updatedAt: Date.now(),
+    }
     // One transaction so the appended event and its bumped record commit
     // together — a reader never sees a lastSeq pointing at a missing event.
     await this.storage.transaction(async (txn) => {
@@ -101,18 +137,47 @@ export class DurableObjectRunEventLog implements RunEventLog {
   ): Promise<void> {
     const record = await this.require(runId)
     if (isTerminalRunStatus(record.status)) return
-    const next: RunRecord = {
+    const now = Date.now()
+    const next: RunLogRecord = {
       ...record,
       status,
       ...(error !== undefined ? { error } : {}),
-      updatedAt: Date.now(),
+      finishedAt: now,
+      updatedAt: now,
     }
     await this.storage.put(recKey(runId), next)
     this.wake(runId)
   }
 
-  async get(runId: string): Promise<RunRecord | null> {
-    return (await this.storage.get<RunRecord>(recKey(runId))) ?? null
+  async update(runId: string, patch: RunRecordPatch): Promise<void> {
+    const record = await this.getRecord(runId)
+    if (!record) return // unknown runId is a no-op
+    const next: RunLogRecord = { ...record, ...patch, updatedAt: Date.now() }
+    await this.storage.put(recKey(runId), next)
+    // A patch may terminalize the shared status field (core's driver writes its
+    // terminal status through `RunStore.update`) — parked readers must see it
+    // now, not a TAIL_POLL_MS later.
+    this.wake(runId)
+  }
+
+  async get(runId: string): Promise<RunLogRecord | null> {
+    return this.getRecord(runId)
+  }
+
+  /**
+   * Every run record this log holds, migrated. The coordinator's stall
+   * watchdog iterates this instead of listing `rec:` keys itself, so the
+   * storage layout (and its migration) stays this module's private concern.
+   */
+  async list(): Promise<Array<RunLogRecord>> {
+    const stored = await this.storage.list<StoredRunRecord>({ prefix: 'rec:' })
+    const records: Array<RunLogRecord> = []
+    for (const [key, value] of stored) {
+      const { record, migrated } = migrateStoredRunRecord(value)
+      if (migrated) await this.storage.put(key, record)
+      records.push(record)
+    }
+    return records
   }
 
   async *read(