@tanstack/ai-sandbox 0.1.0

package/dist/esm/run-log.d.ts

@@ -0,0 +1,81 @@
+import { StreamChunk } from '@tanstack/ai';
+/** A terminal run status: no further events will be appended. */
+export type TerminalRunStatus = 'done' | 'error' | 'aborted';
+/** Lifecycle status of a run. `done`/`error`/`aborted` are terminal. */
+export type RunStatus = 'running' | TerminalRunStatus;
+/** Whether a run status is terminal (no further events will be appended). */
+export declare function isTerminalRunStatus(status: RunStatus): boolean;
+export interface RunError {
+    message: string;
+    code?: string;
+}
+/** Durable bookkeeping for a single run. */
+export interface RunRecord {
+    runId: string;
+    threadId?: string;
+    status: RunStatus;
+    /** Seq of the last appended event, or `-1` when no events yet. */
+    lastSeq: number;
+    error?: RunError;
+    createdAt: number;
+    updatedAt: number;
+}
+/** One persisted event: a chunk plus its monotonic, gap-free sequence number. */
+export interface RunEvent {
+    seq: number;
+    chunk: StreamChunk;
+}
+export interface RunEventLogReadOptions {
+    /**
+     * Exclusive cursor: only events with `seq > fromSeq` are yielded. Pass the
+     * client's last-seen `seq` to resume; omit (or `-1`) to replay from the start.
+     */
+    fromSeq?: number;
+    /** Stop tailing when this fires (e.g. the client disconnected). */
+    signal?: AbortSignal;
+}
+/**
+ * Append-only, `seq`-indexed log of a run's stream, with resumable reads.
+ *
+ * Contract:
+ * - `append` assigns the next `seq` (0, 1, 2, …) and returns it.
+ * - `read` yields the backlog after `fromSeq` in order, then live-tails new
+ *   events, and RETURNS once the run is terminal and the cursor has caught up.
+ * - All methods reject for an unknown `runId` except `get`, which resolves null.
+ */
+export interface RunEventLog {
+    /** Idempotently create (or return) the run record. */
+    open: (input: {
+        runId: string;
+        threadId?: string;
+    }) => Promise<RunRecord>;
+    /** Append one chunk; resolves with its assigned `seq`. */
+    append: (runId: string, chunk: StreamChunk) => Promise<number>;
+    /** Move the run to a terminal status. Idempotent for the same status. */
+    finish: (runId: string, status: TerminalRunStatus, error?: RunError) => Promise<void>;
+    /** Current record, or null if the run is unknown. */
+    get: (runId: string) => Promise<RunRecord | null>;
+    /** Replay-then-tail events with `seq > fromSeq` until the run is terminal. */
+    read: (runId: string, options?: RunEventLogReadOptions) => AsyncIterable<RunEvent>;
+}
+/**
+ * Single-process {@link RunEventLog}. Backs `read`'s live-tail with an internal
+ * waiter set: `append`/`finish` wake every blocked reader. Suitable for a
+ * long-running Node host, tests, and as the reference implementation a durable
+ * backend mirrors.
+ */
+export declare class InMemoryRunEventLog implements RunEventLog {
+    private readonly runs;
+    private now;
+    private require;
+    private wake;
+    open(input: {
+        runId: string;
+        threadId?: string;
+    }): Promise<RunRecord>;
+    append(runId: string, chunk: StreamChunk): Promise<number>;
+    finish(runId: string, status: TerminalRunStatus, error?: RunError): Promise<void>;
+    get(runId: string): Promise<RunRecord | null>;
+    read(runId: string, options?: RunEventLogReadOptions): AsyncIterable<RunEvent>;
+    private waitForChange;
+}

package/dist/esm/run-log.js

@@ -0,0 +1,107 @@
+const TERMINAL = /* @__PURE__ */ new Set([
+  "done",
+  "error",
+  "aborted"
+]);
+function isTerminalRunStatus(status) {
+  return TERMINAL.has(status);
+}
+class InMemoryRunEventLog {
+  runs = /* @__PURE__ */ new Map();
+  now() {
+    return Date.now();
+  }
+  require(runId) {
+    const state = this.runs.get(runId);
+    if (!state) throw new Error(`run-log: unknown runId "${runId}"`);
+    return state;
+  }
+  wake(state) {
+    const waiters = [...state.waiters];
+    state.waiters.clear();
+    for (const resolve of waiters) resolve();
+  }
+  // Mutators return a Promise without `async` so contract violations REJECT
+  // (rather than throwing synchronously from a Promise-typed method — a
+  // `.catch()` footgun) without an `await`-less async body.
+  open(input) {
+    const existing = this.runs.get(input.runId);
+    if (existing) return Promise.resolve({ ...existing.record });
+    const now = this.now();
+    const record = {
+      runId: input.runId,
+      ...input.threadId !== void 0 ? { threadId: input.threadId } : {},
+      status: "running",
+      lastSeq: -1,
+      createdAt: now,
+      updatedAt: now
+    };
+    this.runs.set(input.runId, { record, chunks: [], waiters: /* @__PURE__ */ new Set() });
+    return Promise.resolve({ ...record });
+  }
+  append(runId, chunk) {
+    const state = this.runs.get(runId);
+    if (!state) {
+      return Promise.reject(new Error(`run-log: unknown runId "${runId}"`));
+    }
+    if (isTerminalRunStatus(state.record.status)) {
+      return Promise.reject(
+        new Error(
+          `run-log: cannot append to terminal run "${runId}" (status=${state.record.status})`
+        )
+      );
+    }
+    const seq = state.record.lastSeq + 1;
+    state.chunks.push(chunk);
+    state.record.lastSeq = seq;
+    state.record.updatedAt = this.now();
+    this.wake(state);
+    return Promise.resolve(seq);
+  }
+  finish(runId, status, error) {
+    const state = this.runs.get(runId);
+    if (!state) {
+      return Promise.reject(new Error(`run-log: unknown runId "${runId}"`));
+    }
+    if (isTerminalRunStatus(state.record.status)) return Promise.resolve();
+    state.record.status = status;
+    if (error !== void 0) state.record.error = error;
+    state.record.updatedAt = this.now();
+    this.wake(state);
+    return Promise.resolve();
+  }
+  get(runId) {
+    const state = this.runs.get(runId);
+    return Promise.resolve(state ? { ...state.record } : null);
+  }
+  async *read(runId, options) {
+    const state = this.require(runId);
+    const signal = options?.signal;
+    let cursor = options?.fromSeq ?? -1;
+    while (!signal?.aborted) {
+      while (cursor < state.record.lastSeq) {
+        cursor += 1;
+        const chunk = state.chunks[cursor];
+        if (chunk !== void 0) yield { seq: cursor, chunk };
+      }
+      if (isTerminalRunStatus(state.record.status)) return;
+      await this.waitForChange(state, signal);
+    }
+  }
+  waitForChange(state, signal) {
+    return new Promise((resolve) => {
+      const wake = () => {
+        state.waiters.delete(wake);
+        if (signal) signal.removeEventListener("abort", wake);
+        resolve();
+      };
+      state.waiters.add(wake);
+      if (signal) signal.addEventListener("abort", wake, { once: true });
+    });
+  }
+}
+export {
+  InMemoryRunEventLog,
+  isTerminalRunStatus
+};
+//# sourceMappingURL=run-log.js.map

package/dist/esm/run-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-log.js","sources":["../../src/run-log.ts"],"sourcesContent":["/**\n * Resumable run event-log — the primitive that lets a trigger (e.g. a\n * Cloudflare Worker) start an agent run and return immediately while a durable\n * orchestrator (e.g. a Durable Object) drives the run and persists every\n * emitted {@link StreamChunk} under a monotonic `seq`.\n *\n * Clients tail the log from a cursor (`fromSeq`), so a dropped connection, a new\n * browser tab, or an orchestrator that hibernated between chunks all reconnect\n * cleanly: replay everything after the client's last-seen `seq`, then live-tail\n * until the run reaches a terminal status. The *run* never depends on any single\n * connection staying open — that is what makes the serverless/edge model work.\n *\n * This module is transport- and storage-agnostic. {@link InMemoryRunEventLog} is\n * the default (single-process / tests); a durable backend (DO storage, KV, SQL)\n * implements the same {@link RunEventLog} interface — see the Cloudflare example.\n */\nimport type { StreamChunk } from '@tanstack/ai'\n\n/** A terminal run status: no further events will be appended. */\nexport type TerminalRunStatus = 'done' | 'error' | 'aborted'\n\n/** Lifecycle status of a run. `done`/`error`/`aborted` are terminal. */\nexport type RunStatus = 'running' | TerminalRunStatus\n\nconst TERMINAL: ReadonlySet<RunStatus> = new Set<RunStatus>([\n  'done',\n  'error',\n  'aborted',\n])\n\n/** Whether a run status is terminal (no further events will be appended). */\nexport function isTerminalRunStatus(status: RunStatus): boolean {\n  return TERMINAL.has(status)\n}\n\nexport interface RunError {\n  message: string\n  code?: string\n}\n\n/** Durable bookkeeping for a single run. */\nexport interface RunRecord {\n  runId: string\n  threadId?: string\n  status: RunStatus\n  /** Seq of the last appended event, or `-1` when no events yet. */\n  lastSeq: number\n  error?: RunError\n  createdAt: number\n  updatedAt: number\n}\n\n/** One persisted event: a chunk plus its monotonic, gap-free sequence number. */\nexport interface RunEvent {\n  seq: number\n  chunk: StreamChunk\n}\n\nexport interface RunEventLogReadOptions {\n  /**\n   * Exclusive cursor: only events with `seq > fromSeq` are yielded. Pass the\n   * client's last-seen `seq` to resume; omit (or `-1`) to replay from the start.\n   */\n  fromSeq?: number\n  /** Stop tailing when this fires (e.g. the client disconnected). */\n  signal?: AbortSignal\n}\n\n/**\n * Append-only, `seq`-indexed log of a run's stream, with resumable reads.\n *\n * Contract:\n * - `append` assigns the next `seq` (0, 1, 2, …) and returns it.\n * - `read` yields the backlog after `fromSeq` in order, then live-tails new\n *   events, and RETURNS once the run is terminal and the cursor has caught up.\n * - All methods reject for an unknown `runId` except `get`, which resolves null.\n */\nexport interface RunEventLog {\n  /** Idempotently create (or return) the run record. */\n  open: (input: { runId: string; threadId?: string }) => Promise<RunRecord>\n  /** Append one chunk; resolves with its assigned `seq`. */\n  append: (runId: string, chunk: StreamChunk) => Promise<number>\n  /** Move the run to a terminal status. Idempotent for the same status. */\n  finish: (\n    runId: string,\n    status: TerminalRunStatus,\n    error?: RunError,\n  ) => Promise<void>\n  /** Current record, or null if the run is unknown. */\n  get: (runId: string) => Promise<RunRecord | null>\n  /** Replay-then-tail events with `seq > fromSeq` until the run is terminal. */\n  read: (\n    runId: string,\n    options?: RunEventLogReadOptions,\n  ) => AsyncIterable<RunEvent>\n}\n\n/** Per-run state for the in-memory log. */\ninterface RunState {\n  record: RunRecord\n  chunks: Array<StreamChunk>\n  /** Resolved (and cleared) whenever an event is appended or status changes. */\n  waiters: Set<() => void>\n}\n\n/**\n * Single-process {@link RunEventLog}. Backs `read`'s live-tail with an internal\n * waiter set: `append`/`finish` wake every blocked reader. Suitable for a\n * long-running Node host, tests, and as the reference implementation a durable\n * backend mirrors.\n */\nexport class InMemoryRunEventLog implements RunEventLog {\n  private readonly runs = new Map<string, RunState>()\n\n  private now(): number {\n    return Date.now()\n  }\n\n  private require(runId: string): RunState {\n    const state = this.runs.get(runId)\n    if (!state) throw new Error(`run-log: unknown runId \"${runId}\"`)\n    return state\n  }\n\n  private wake(state: RunState): void {\n    const waiters = [...state.waiters]\n    state.waiters.clear()\n    for (const resolve of waiters) resolve()\n  }\n\n  // Mutators return a Promise without `async` so contract violations REJECT\n  // (rather than throwing synchronously from a Promise-typed method — a\n  // `.catch()` footgun) without an `await`-less async body.\n  open(input: { runId: string; threadId?: string }): Promise<RunRecord> {\n    const existing = this.runs.get(input.runId)\n    if (existing) return Promise.resolve({ ...existing.record })\n    const now = this.now()\n    const record: RunRecord = {\n      runId: input.runId,\n      ...(input.threadId !== undefined ? { threadId: input.threadId } : {}),\n      status: 'running',\n      lastSeq: -1,\n      createdAt: now,\n      updatedAt: now,\n    }\n    this.runs.set(input.runId, { record, chunks: [], waiters: new Set() })\n    return Promise.resolve({ ...record })\n  }\n\n  append(runId: string, chunk: StreamChunk): Promise<number> {\n    const state = this.runs.get(runId)\n    if (!state) {\n      return Promise.reject(new Error(`run-log: unknown runId \"${runId}\"`))\n    }\n    if (isTerminalRunStatus(state.record.status)) {\n      return Promise.reject(\n        new Error(\n          `run-log: cannot append to terminal run \"${runId}\" (status=${state.record.status})`,\n        ),\n      )\n    }\n    // Derive seq from the record's cursor (not `chunks.length`) so the gap-free\n    // invariant holds the same way the durable backend computes it, even if the\n    // backlog is ever trimmed/compacted.\n    const seq = state.record.lastSeq + 1\n    state.chunks.push(chunk)\n    state.record.lastSeq = seq\n    state.record.updatedAt = this.now()\n    this.wake(state)\n    return Promise.resolve(seq)\n  }\n\n  finish(\n    runId: string,\n    status: TerminalRunStatus,\n    error?: RunError,\n  ): Promise<void> {\n    const state = this.runs.get(runId)\n    if (!state) {\n      return Promise.reject(new Error(`run-log: unknown runId \"${runId}\"`))\n    }\n    if (isTerminalRunStatus(state.record.status)) return Promise.resolve()\n    state.record.status = status\n    if (error !== undefined) state.record.error = error\n    state.record.updatedAt = this.now()\n    this.wake(state)\n    return Promise.resolve()\n  }\n\n  get(runId: string): Promise<RunRecord | null> {\n    const state = this.runs.get(runId)\n    return Promise.resolve(state ? { ...state.record } : null)\n  }\n\n  async *read(\n    runId: string,\n    options?: RunEventLogReadOptions,\n  ): AsyncIterable<RunEvent> {\n    const state = this.require(runId)\n    const signal = options?.signal\n    let cursor = options?.fromSeq ?? -1\n    while (!signal?.aborted) {\n      while (cursor < state.record.lastSeq) {\n        cursor += 1\n        const chunk = state.chunks[cursor]\n        if (chunk !== undefined) yield { seq: cursor, chunk }\n      }\n      if (isTerminalRunStatus(state.record.status)) return\n      await this.waitForChange(state, signal)\n    }\n  }\n\n  private waitForChange(state: RunState, signal?: AbortSignal): Promise<void> {\n    return new Promise<void>((resolve) => {\n      const wake = (): void => {\n        state.waiters.delete(wake)\n        if (signal) signal.removeEventListener('abort', wake)\n        resolve()\n      }\n      state.waiters.add(wake)\n      if (signal) signal.addEventListener('abort', wake, { once: true })\n    })\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/run.d.ts

@@ -0,0 +1,58 @@
+import { StreamChunk } from '@tanstack/ai';
+import { RunEvent, RunEventLog, RunRecord } from './run-log.js';
+export interface PipeToRunLogOptions {
+    log: RunEventLog;
+    runId: string;
+    threadId?: string;
+    /** Abort consumption mid-stream; the run finishes as `aborted`. */
+    signal?: AbortSignal;
+}
+/**
+ * Open the run, append every chunk from `stream`, and finish with the right
+ * terminal status. Resolves with the final {@link RunRecord} and never rejects:
+ * a thrown stream error is surfaced as a `RUN_ERROR` event + the record's
+ * `error`, which is what tailing clients see.
+ *
+ * - normal completion → `finish('done')`
+ * - a `RUN_ERROR` chunk → append it, then `finish('error', { message, code })`
+ * - the stream throws → append a synthesized `RUN_ERROR`, then `finish('error')`
+ * - `signal` aborts mid-stream → stop consuming, `finish('aborted')`
+ */
+export declare function pipeToRunLog(stream: AsyncIterable<StreamChunk>, opts: PipeToRunLogOptions): Promise<RunRecord>;
+export interface RunControllerStartInput {
+    runId: string;
+    threadId?: string;
+    stream: AsyncIterable<StreamChunk>;
+    /** Abort consumption mid-stream; the run finishes as `aborted`. */
+    signal?: AbortSignal;
+}
+export interface RunHandle {
+    runId: string;
+    /** Resolves with the final record once the run reaches a terminal status. */
+    done: Promise<RunRecord>;
+}
+/**
+ * Thin orchestration helper over a {@link RunEventLog}: fire-and-track a run via
+ * {@link pipeToRunLog}, tail it from a cursor, and `drain()` all in-flight runs
+ * (e.g. inside a `ctx.waitUntil`). Holds no run state of its own beyond the set
+ * of currently in-flight `done` promises.
+ */
+export declare class RunController {
+    private readonly log;
+    private readonly inFlight;
+    constructor(log: RunEventLog);
+    /**
+     * Kick off `pipeToRunLog` without awaiting it and return the `runId`
+     * immediately plus a `done` promise the orchestrator may await or detach.
+     */
+    start(input: RunControllerStartInput): RunHandle;
+    /** Resumable client tail — replay from `fromSeq`, then live-tail to terminal. */
+    attach(runId: string, opts?: {
+        fromSeq?: number;
+        signal?: AbortSignal;
+    }): AsyncIterable<RunEvent>;
+    /** Current run record, or null if the run is unknown. */
+    status(runId: string): Promise<RunRecord | null>;
+    /** Await every currently in-flight run's `done` promise. */
+    drain(): Promise<void>;
+}

package/dist/esm/run.js

@@ -0,0 +1,89 @@
+import { EventType } from "@tanstack/ai";
+function isRunErrorChunk(chunk) {
+  return chunk.type === EventType.RUN_ERROR;
+}
+function runErrorFromChunk(chunk) {
+  return chunk.code !== void 0 ? { message: chunk.message, code: chunk.code } : { message: chunk.message };
+}
+function messageOf(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+function syntheticRunError(message) {
+  const chunk = {
+    type: EventType.RUN_ERROR,
+    message
+  };
+  return chunk;
+}
+async function pipeToRunLog(stream, opts) {
+  const { log, runId, threadId, signal } = opts;
+  await log.open(threadId !== void 0 ? { runId, threadId } : { runId });
+  if (signal?.aborted) {
+    await log.finish(runId, "aborted");
+    return reread(log, runId);
+  }
+  try {
+    for await (const chunk of stream) {
+      if (signal?.aborted) {
+        await log.finish(runId, "aborted");
+        return reread(log, runId);
+      }
+      await log.append(runId, chunk);
+      if (isRunErrorChunk(chunk)) {
+        await log.finish(runId, "error", runErrorFromChunk(chunk));
+        return reread(log, runId);
+      }
+    }
+  } catch (error) {
+    const message = messageOf(error);
+    await log.append(runId, syntheticRunError(message));
+    await log.finish(runId, "error", { message });
+    return reread(log, runId);
+  }
+  await log.finish(runId, "done");
+  return reread(log, runId);
+}
+async function reread(log, runId) {
+  const latest = await log.get(runId);
+  if (!latest) throw new Error(`run: record for "${runId}" vanished mid-run`);
+  return latest;
+}
+class RunController {
+  constructor(log) {
+    this.log = log;
+  }
+  log;
+  inFlight = /* @__PURE__ */ new Set();
+  /**
+   * Kick off `pipeToRunLog` without awaiting it and return the `runId`
+   * immediately plus a `done` promise the orchestrator may await or detach.
+   */
+  start(input) {
+    const done = pipeToRunLog(input.stream, {
+      log: this.log,
+      runId: input.runId,
+      ...input.threadId !== void 0 ? { threadId: input.threadId } : {},
+      ...input.signal !== void 0 ? { signal: input.signal } : {}
+    });
+    this.inFlight.add(done);
+    void done.finally(() => this.inFlight.delete(done));
+    return { runId: input.runId, done };
+  }
+  /** Resumable client tail — replay from `fromSeq`, then live-tail to terminal. */
+  attach(runId, opts) {
+    return this.log.read(runId, opts);
+  }
+  /** Current run record, or null if the run is unknown. */
+  status(runId) {
+    return this.log.get(runId);
+  }
+  /** Await every currently in-flight run's `done` promise. */
+  async drain() {
+    await Promise.all([...this.inFlight]);
+  }
+}
+export {
+  RunController,
+  pipeToRunLog
+};
+//# sourceMappingURL=run.js.map

package/dist/esm/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sources":["../../src/run.ts"],"sourcesContent":["/**\n * The \"run driver\" for the inverted/serverless sandbox model: pump a `chat()`\n * stream into a {@link RunEventLog} so a trigger can return immediately while a\n * durable orchestrator drives the run and clients tail from a cursor.\n *\n * The key inversion vs. a classic request/response handler: there is no caller\n * holding the stream open, so nothing to throw an error *back to*. The log is\n * the only channel — every chunk (including a terminal {@link EventType.RUN_ERROR})\n * is persisted under a `seq`, and a thrown stream error is recorded as a\n * synthesized `RUN_ERROR` event plus the record's `error` field. Tailing clients\n * therefore always observe failures; {@link pipeToRunLog} never rejects.\n */\nimport { EventType } from '@tanstack/ai'\nimport type { StreamChunk } from '@tanstack/ai'\nimport type { RunError, RunEvent, RunEventLog, RunRecord } from './run-log'\n\n/** Whether a chunk is the terminal error event the chat engine emits. */\nfunction isRunErrorChunk(\n  chunk: StreamChunk,\n): chunk is StreamChunk & { message: string; code?: string } {\n  return chunk.type === EventType.RUN_ERROR\n}\n\n/** Pull `{ message, code }` off a RUN_ERROR chunk for the run record. */\nfunction runErrorFromChunk(\n  chunk: StreamChunk & { message: string; code?: string },\n): RunError {\n  return chunk.code !== undefined\n    ? { message: chunk.message, code: chunk.code }\n    : { message: chunk.message }\n}\n\n/** Render an unknown thrown value as a stable error message. */\nfunction messageOf(error: unknown): string {\n  return error instanceof Error ? error.message : String(error)\n}\n\n/** Build the synthetic RUN_ERROR chunk appended when the stream throws. */\nfunction syntheticRunError(message: string): StreamChunk {\n  const chunk: { type: EventType.RUN_ERROR; message: string } = {\n    type: EventType.RUN_ERROR,\n    message,\n  }\n  return chunk\n}\n\nexport interface PipeToRunLogOptions {\n  log: RunEventLog\n  runId: string\n  threadId?: string\n  /** Abort consumption mid-stream; the run finishes as `aborted`. */\n  signal?: AbortSignal\n}\n\n/**\n * Open the run, append every chunk from `stream`, and finish with the right\n * terminal status. Resolves with the final {@link RunRecord} and never rejects:\n * a thrown stream error is surfaced as a `RUN_ERROR` event + the record's\n * `error`, which is what tailing clients see.\n *\n * - normal completion → `finish('done')`\n * - a `RUN_ERROR` chunk → append it, then `finish('error', { message, code })`\n * - the stream throws → append a synthesized `RUN_ERROR`, then `finish('error')`\n * - `signal` aborts mid-stream → stop consuming, `finish('aborted')`\n */\nexport async function pipeToRunLog(\n  stream: AsyncIterable<StreamChunk>,\n  opts: PipeToRunLogOptions,\n): Promise<RunRecord> {\n  const { log, runId, threadId, signal } = opts\n  await log.open(threadId !== undefined ? { runId, threadId } : { runId })\n  if (signal?.aborted) {\n    await log.finish(runId, 'aborted')\n    return reread(log, runId)\n  }\n\n  try {\n    for await (const chunk of stream) {\n      if (signal?.aborted) {\n        await log.finish(runId, 'aborted')\n        return reread(log, runId)\n      }\n      await log.append(runId, chunk)\n      if (isRunErrorChunk(chunk)) {\n        await log.finish(runId, 'error', runErrorFromChunk(chunk))\n        return reread(log, runId)\n      }\n    }\n  } catch (error) {\n    // Detached run: no caller to throw to. Record the failure in the log so\n    // tailing clients observe it, then return — do NOT rethrow.\n    const message = messageOf(error)\n    await log.append(runId, syntheticRunError(message))\n    await log.finish(runId, 'error', { message })\n    return reread(log, runId)\n  }\n\n  await log.finish(runId, 'done')\n  return reread(log, runId)\n}\n\n/** Re-read the now-terminal record; the run was just driven, so it must exist. */\nasync function reread(log: RunEventLog, runId: string): Promise<RunRecord> {\n  const latest = await log.get(runId)\n  if (!latest) throw new Error(`run: record for \"${runId}\" vanished mid-run`)\n  return latest\n}\n\nexport interface RunControllerStartInput {\n  runId: string\n  threadId?: string\n  stream: AsyncIterable<StreamChunk>\n  /** Abort consumption mid-stream; the run finishes as `aborted`. */\n  signal?: AbortSignal\n}\n\nexport interface RunHandle {\n  runId: string\n  /** Resolves with the final record once the run reaches a terminal status. */\n  done: Promise<RunRecord>\n}\n\n/**\n * Thin orchestration helper over a {@link RunEventLog}: fire-and-track a run via\n * {@link pipeToRunLog}, tail it from a cursor, and `drain()` all in-flight runs\n * (e.g. inside a `ctx.waitUntil`). Holds no run state of its own beyond the set\n * of currently in-flight `done` promises.\n */\nexport class RunController {\n  private readonly inFlight = new Set<Promise<RunRecord>>()\n\n  constructor(private readonly log: RunEventLog) {}\n\n  /**\n   * Kick off `pipeToRunLog` without awaiting it and return the `runId`\n   * immediately plus a `done` promise the orchestrator may await or detach.\n   */\n  start(input: RunControllerStartInput): RunHandle {\n    const done = pipeToRunLog(input.stream, {\n      log: this.log,\n      runId: input.runId,\n      ...(input.threadId !== undefined ? { threadId: input.threadId } : {}),\n      ...(input.signal !== undefined ? { signal: input.signal } : {}),\n    })\n    this.inFlight.add(done)\n    void done.finally(() => this.inFlight.delete(done))\n    return { runId: input.runId, done }\n  }\n\n  /** Resumable client tail — replay from `fromSeq`, then live-tail to terminal. */\n  attach(\n    runId: string,\n    opts?: { fromSeq?: number; signal?: AbortSignal },\n  ): AsyncIterable<RunEvent> {\n    return this.log.read(runId, opts)\n  }\n\n  /** Current run record, or null if the run is unknown. */\n  status(runId: string): Promise<RunRecord | null> {\n    return this.log.get(runId)\n  }\n\n  /** Await every currently in-flight run's `done` promise. */\n  async drain(): Promise<void> {\n    await Promise.all([...this.inFlight])\n  }\n}\n"],"names":[],"mappings":";AAiBA,SAAS,gBACP,OAC2D;AAC3D,SAAO,MAAM,SAAS,UAAU;AAClC;AAGA,SAAS,kBACP,OACU;AACV,SAAO,MAAM,SAAS,SAClB,EAAE,SAAS,MAAM,SAAS,MAAM,MAAM,KAAA,IACtC,EAAE,SAAS,MAAM,QAAA;AACvB;AAGA,SAAS,UAAU,OAAwB;AACzC,SAAO,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC9D;AAGA,SAAS,kBAAkB,SAA8B;AACvD,QAAM,QAAwD;AAAA,IAC5D,MAAM,UAAU;AAAA,IAChB;AAAA,EAAA;AAEF,SAAO;AACT;AAqBA,eAAsB,aACpB,QACA,MACoB;AACpB,QAAM,EAAE,KAAK,OAAO,UAAU,WAAW;AACzC,QAAM,IAAI,KAAK,aAAa,SAAY,EAAE,OAAO,SAAA,IAAa,EAAE,OAAO;AACvE,MAAI,QAAQ,SAAS;AACnB,UAAM,IAAI,OAAO,OAAO,SAAS;AACjC,WAAO,OAAO,KAAK,KAAK;AAAA,EAC1B;AAEA,MAAI;AACF,qBAAiB,SAAS,QAAQ;AAChC,UAAI,QAAQ,SAAS;AACnB,cAAM,IAAI,OAAO,OAAO,SAAS;AACjC,eAAO,OAAO,KAAK,KAAK;AAAA,MAC1B;AACA,YAAM,IAAI,OAAO,OAAO,KAAK;AAC7B,UAAI,gBAAgB,KAAK,GAAG;AAC1B,cAAM,IAAI,OAAO,OAAO,SAAS,kBAAkB,KAAK,CAAC;AACzD,eAAO,OAAO,KAAK,KAAK;AAAA,MAC1B;AAAA,IACF;AAAA,EACF,SAAS,OAAO;AAGd,UAAM,UAAU,UAAU,KAAK;AAC/B,UAAM,IAAI,OAAO,OAAO,kBAAkB,OAAO,CAAC;AAClD,UAAM,IAAI,OAAO,OAAO,SAAS,EAAE,SAAS;AAC5C,WAAO,OAAO,KAAK,KAAK;AAAA,EAC1B;AAEA,QAAM,IAAI,OAAO,OAAO,MAAM;AAC9B,SAAO,OAAO,KAAK,KAAK;AAC1B;AAGA,eAAe,OAAO,KAAkB,OAAmC;AACzE,QAAM,SAAS,MAAM,IAAI,IAAI,KAAK;AAClC,MAAI,CAAC,OAAQ,OAAM,IAAI,MAAM,oBAAoB,KAAK,oBAAoB;AAC1E,SAAO;AACT;AAsBO,MAAM,cAAc;AAAA,EAGzB,YAA6B,KAAkB;AAAlB,SAAA,MAAA;AAAA,EAAmB;AAAA,EAAnB;AAAA,EAFZ,+BAAe,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQhC,MAAM,OAA2C;AAC/C,UAAM,OAAO,aAAa,MAAM,QAAQ;AAAA,MACtC,KAAK,KAAK;AAAA,MACV,OAAO,MAAM;AAAA,MACb,GAAI,MAAM,aAAa,SAAY,EAAE,UAAU,MAAM,SAAA,IAAa,CAAA;AAAA,MAClE,GAAI,MAAM,WAAW,SAAY,EAAE,QAAQ,MAAM,WAAW,CAAA;AAAA,IAAC,CAC9D;AACD,SAAK,SAAS,IAAI,IAAI;AACtB,SAAK,KAAK,QAAQ,MAAM,KAAK,SAAS,OAAO,IAAI,CAAC;AAClD,WAAO,EAAE,OAAO,MAAM,OAAO,KAAA;AAAA,EAC/B;AAAA;AAAA,EAGA,OACE,OACA,MACyB;AACzB,WAAO,KAAK,IAAI,KAAK,OAAO,IAAI;AAAA,EAClC;AAAA;AAAA,EAGA,OAAO,OAA0C;AAC/C,WAAO,KAAK,IAAI,IAAI,KAAK;AAAA,EAC3B;AAAA;AAAA,EAGA,MAAM,QAAuB;AAC3B,UAAM,QAAQ,IAAI,CAAC,GAAG,KAAK,QAAQ,CAAC;AAAA,EACtC;AACF;"}

package/dist/esm/runner.d.ts

@@ -0,0 +1,21 @@
+import { ProcessOptions, SandboxHandle } from './contracts.js';
+export interface SpawnNdjsonOptions extends ProcessOptions {
+    /**
+     * Called for each raw stdout line that is non-empty but fails JSON parsing
+     * (e.g. a CLI banner). Defaults to ignoring it. Stderr is never parsed.
+     */
+    onNonJsonLine?: (line: string) => void;
+    /**
+     * Written to the process stdin (then stdin is closed) right after spawn —
+     * e.g. the agent prompt for `claude -p`. Avoids putting the prompt in argv.
+     */
+    input?: string;
+}
+/** Split a stream of arbitrary string chunks into complete lines. */
+export declare function toLines(chunks: AsyncIterable<string>): AsyncIterable<string>;
+/**
+ * Spawn `command` in the sandbox and yield each stdout line parsed as JSON.
+ * Resolves the spawn handle's exit via `wait()` after stdout closes; a non-zero
+ * exit with no events surfaced is the adapter's concern to detect.
+ */
+export declare function spawnNdjson(handle: SandboxHandle, command: string, options?: SpawnNdjsonOptions): AsyncIterable<unknown>;

package/dist/esm/runner.js

@@ -0,0 +1,54 @@
+async function* toLines(chunks) {
+  let buffer = "";
+  for await (const chunk of chunks) {
+    buffer += chunk;
+    let newlineIndex = buffer.indexOf("\n");
+    while (newlineIndex !== -1) {
+      const line = buffer.slice(0, newlineIndex);
+      buffer = buffer.slice(newlineIndex + 1);
+      yield line;
+      newlineIndex = buffer.indexOf("\n");
+    }
+  }
+  if (buffer.length > 0) yield buffer;
+}
+async function* spawnNdjson(handle, command, options = {}) {
+  const { onNonJsonLine, input, ...processOptions } = options;
+  const proc = await handle.process.spawn(command, processOptions);
+  if (input !== void 0) {
+    await proc.stdin.write(input);
+    await proc.stdin.end();
+  }
+  const stderrChunks = [];
+  const stderrDrained = (async () => {
+    try {
+      for await (const chunk of proc.stderr) stderrChunks.push(chunk);
+    } catch {
+    }
+  })();
+  for await (const line of toLines(proc.stdout)) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      onNonJsonLine?.(trimmed);
+      continue;
+    }
+    yield parsed;
+  }
+  const exitCode = await proc.wait();
+  await stderrDrained;
+  if (exitCode !== 0) {
+    const stderr = stderrChunks.join("").trim();
+    throw new Error(
+      `Agent process exited with code ${exitCode}` + (stderr ? `: ${stderr.slice(0, 1e3)}` : "")
+    );
+  }
+}
+export {
+  spawnNdjson,
+  toLines
+};
+//# sourceMappingURL=runner.js.map

package/dist/esm/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sources":["../../src/runner.ts"],"sourcesContent":["/**\n * The reusable \"run an agent CLI inside a sandbox and stream its events out\"\n * primitive. Harness adapters (claude-code, codex, …) spawn their CLI via the\n * uniform {@link SandboxHandle} and consume newline-delimited JSON from stdout,\n * which they then translate into AG-UI StreamChunks.\n *\n * This is intentionally transport-minimal: a stdout NDJSON pipe. Multi-client\n * reconnect / replay belongs to the persistence/EventLog layer, not here.\n */\nimport type { ProcessOptions, SandboxHandle } from './contracts'\n\nexport interface SpawnNdjsonOptions extends ProcessOptions {\n  /**\n   * Called for each raw stdout line that is non-empty but fails JSON parsing\n   * (e.g. a CLI banner). Defaults to ignoring it. Stderr is never parsed.\n   */\n  onNonJsonLine?: (line: string) => void\n  /**\n   * Written to the process stdin (then stdin is closed) right after spawn —\n   * e.g. the agent prompt for `claude -p`. Avoids putting the prompt in argv.\n   */\n  input?: string\n}\n\n/** Split a stream of arbitrary string chunks into complete lines. */\nexport async function* toLines(\n  chunks: AsyncIterable<string>,\n): AsyncIterable<string> {\n  let buffer = ''\n  for await (const chunk of chunks) {\n    buffer += chunk\n    let newlineIndex = buffer.indexOf('\\n')\n    while (newlineIndex !== -1) {\n      const line = buffer.slice(0, newlineIndex)\n      buffer = buffer.slice(newlineIndex + 1)\n      yield line\n      newlineIndex = buffer.indexOf('\\n')\n    }\n  }\n  if (buffer.length > 0) yield buffer\n}\n\n/**\n * Spawn `command` in the sandbox and yield each stdout line parsed as JSON.\n * Resolves the spawn handle's exit via `wait()` after stdout closes; a non-zero\n * exit with no events surfaced is the adapter's concern to detect.\n */\nexport async function* spawnNdjson(\n  handle: SandboxHandle,\n  command: string,\n  options: SpawnNdjsonOptions = {},\n): AsyncIterable<unknown> {\n  const { onNonJsonLine, input, ...processOptions } = options\n  const proc = await handle.process.spawn(command, processOptions)\n\n  if (input !== undefined) {\n    await proc.stdin.write(input)\n    await proc.stdin.end()\n  }\n\n  // Drain stderr concurrently. A CLI that fails before producing stdout (a\n  // broken install, an auth/permission refusal, …) prints to stderr and exits\n  // non-zero; without this, stdout-only parsing yields nothing and the failure\n  // vanishes. Capturing it lets us surface the cause below.\n  const stderrChunks: Array<string> = []\n  const stderrDrained = (async () => {\n    try {\n      for await (const chunk of proc.stderr) stderrChunks.push(chunk)\n    } catch {\n      // stderr stream torn down — use whatever was captured\n    }\n  })()\n\n  for await (const line of toLines(proc.stdout)) {\n    const trimmed = line.trim()\n    if (trimmed === '') continue\n    let parsed: unknown\n    try {\n      parsed = JSON.parse(trimmed)\n    } catch {\n      onNonJsonLine?.(trimmed)\n      continue\n    }\n    yield parsed\n  }\n\n  const exitCode = await proc.wait()\n  await stderrDrained\n  // A non-zero exit means the agent CLI itself failed. Throw so the adapter's\n  // catch turns it into a RUN_ERROR the UI can show, instead of ending the\n  // stream silently with no events.\n  if (exitCode !== 0) {\n    const stderr = stderrChunks.join('').trim()\n    throw new Error(\n      `Agent process exited with code ${exitCode}` +\n        (stderr ? `: ${stderr.slice(0, 1000)}` : ''),\n    )\n  }\n}\n"],"names":[],"mappings":"AAyBA,gBAAuB,QACrB,QACuB;AACvB,MAAI,SAAS;AACb,mBAAiB,SAAS,QAAQ;AAChC,cAAU;AACV,QAAI,eAAe,OAAO,QAAQ,IAAI;AACtC,WAAO,iBAAiB,IAAI;AAC1B,YAAM,OAAO,OAAO,MAAM,GAAG,YAAY;AACzC,eAAS,OAAO,MAAM,eAAe,CAAC;AACtC,YAAM;AACN,qBAAe,OAAO,QAAQ,IAAI;AAAA,IACpC;AAAA,EACF;AACA,MAAI,OAAO,SAAS,EAAG,OAAM;AAC/B;AAOA,gBAAuB,YACrB,QACA,SACA,UAA8B,CAAA,GACN;AACxB,QAAM,EAAE,eAAe,OAAO,GAAG,mBAAmB;AACpD,QAAM,OAAO,MAAM,OAAO,QAAQ,MAAM,SAAS,cAAc;AAE/D,MAAI,UAAU,QAAW;AACvB,UAAM,KAAK,MAAM,MAAM,KAAK;AAC5B,UAAM,KAAK,MAAM,IAAA;AAAA,EACnB;AAMA,QAAM,eAA8B,CAAA;AACpC,QAAM,iBAAiB,YAAY;AACjC,QAAI;AACF,uBAAiB,SAAS,KAAK,OAAQ,cAAa,KAAK,KAAK;AAAA,IAChE,QAAQ;AAAA,IAER;AAAA,EACF,GAAA;AAEA,mBAAiB,QAAQ,QAAQ,KAAK,MAAM,GAAG;AAC7C,UAAM,UAAU,KAAK,KAAA;AACrB,QAAI,YAAY,GAAI;AACpB,QAAI;AACJ,QAAI;AACF,eAAS,KAAK,MAAM,OAAO;AAAA,IAC7B,QAAQ;AACN,sBAAgB,OAAO;AACvB;AAAA,IACF;AACA,UAAM;AAAA,EACR;AAEA,QAAM,WAAW,MAAM,KAAK,KAAA;AAC5B,QAAM;AAIN,MAAI,aAAa,GAAG;AAClB,UAAM,SAAS,aAAa,KAAK,EAAE,EAAE,KAAA;AACrC,UAAM,IAAI;AAAA,MACR,kCAAkC,QAAQ,MACvC,SAAS,KAAK,OAAO,MAAM,GAAG,GAAI,CAAC,KAAK;AAAA,IAAA;AAAA,EAE/C;AACF;"}

package/dist/esm/sandbox.d.ts

@@ -0,0 +1,79 @@
+import { SandboxFileEvent } from '@tanstack/ai';
+import { SandboxHandle, SandboxProvider } from './contracts.js';
+import { LockStore, SandboxStore } from './store.js';
+import { SandboxPolicy } from './policy.js';
+import { WorkspaceDefinition } from './workspace.js';
+/**
+ * Sandbox-scoped hooks declared on `defineSandbox`. File hooks fire for every
+ * create/change/delete during a chat run; lifecycle hooks fire server-side.
+ */
+export interface SandboxHooks {
+    onFile?: (e: SandboxFileEvent) => void | Promise<void>;
+    onFileCreate?: (e: SandboxFileEvent) => void | Promise<void>;
+    onFileChange?: (e: SandboxFileEvent) => void | Promise<void>;
+    onFileDelete?: (e: SandboxFileEvent) => void | Promise<void>;
+    onReady?: (handle: SandboxHandle) => void | Promise<void>;
+    onError?: (err: unknown) => void | Promise<void>;
+    onDestroy?: () => void | Promise<void>;
+}
+export type ReuseStrategy = 'thread' | 'none';
+export type SnapshotStrategy = 'after-setup' | 'after-run' | 'none';
+export interface SandboxLifecycle {
+    /** `'thread'` resumes one sandbox per thread; `'none'` is fresh per run. */
+    reuse?: ReuseStrategy;
+    /** When to snapshot (provider-permitting). */
+    snapshot?: SnapshotStrategy;
+    /** Hint for how long a provider should keep the sandbox warm between runs. */
+    keepAlive?: string;
+    /** Destroy the sandbox after the run completes. */
+    destroyOnComplete?: boolean;
+    /**
+     * Maximum age of a sandbox record before it is discarded and re-created
+     * instead of resumed. Accepts `'<n>h'` (hours) or `'<n>m'` (minutes),
+     * e.g. `'2h'` or `'30m'`.
+     */
+    snapshotMaxAge?: string;
+}
+export interface SandboxConfig {
+    id: string;
+    provider: SandboxProvider;
+    workspace?: WorkspaceDefinition;
+    policy?: SandboxPolicy;
+    lifecycle?: SandboxLifecycle;
+    /** Sandbox-scoped file/lifecycle hooks. */
+    hooks?: SandboxHooks;
+    /** Watch the workspace for file events (default true). Set false to disable. */
+    fileEvents?: boolean;
+}
+/** Context passed to `ensure()` by `withSandbox` (or advanced callers). */
+export interface SandboxEnsureContext {
+    threadId: string;
+    runId: string;
+    /** Persistence seam; falls back to an in-memory store when absent. */
+    store?: SandboxStore;
+    /** Lock seam; falls back to an in-memory lock when absent. */
+    locks?: LockStore;
+    tenant?: {
+        userId?: string;
+        orgId?: string;
+    };
+    signal?: AbortSignal;
+}
+export interface SandboxDefinition {
+    readonly id: string;
+    readonly provider: SandboxProvider;
+    readonly workspace?: WorkspaceDefinition;
+    readonly policy?: SandboxPolicy;
+    readonly lifecycle?: SandboxLifecycle;
+    /** Sandbox-scoped file/lifecycle hooks. */
+    readonly hooks?: SandboxHooks;
+    /** Watch the workspace for file events (default true). Set false to disable. */
+    readonly fileEvents?: boolean;
+    /** Compound instance key for a given run context. */
+    key: (ctx: SandboxEnsureContext) => string;
+    /** Resume-or-create the sandbox for this thread/run. */
+    ensure: (ctx: SandboxEnsureContext) => Promise<SandboxHandle>;
+    /** Tear down the sandbox recorded for this key. */
+    destroy: (ctx: SandboxEnsureContext) => Promise<void>;
+}
+export declare function defineSandbox(config: SandboxConfig): SandboxDefinition;