@tanstack/ai-sandbox-cloudflare 0.2.4 → 0.3.0

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

@@ -0,0 +1,127 @@
+import { RunError, RunRecord, RunStore, StreamChunk, TerminalRunStatus } from '@tanstack/ai';
+/**
+ * The mutable-field patch a {@link RunStore.update} accepts, reused verbatim so
+ * the log can back a `RunStore` without restating (and drifting from) the pick.
+ */
+export type RunRecordPatch = Parameters<RunStore['update']>[1];
+/**
+ * Durable bookkeeping for one run in the event log: core's {@link RunRecord}
+ * plus the two fields only an event log needs.
+ */
+export interface RunLogRecord extends RunRecord {
+    /** Seq of the last appended event, or `-1` when no events yet. */
+    lastSeq: number;
+    /**
+     * Epoch ms of the last append or status change — the activity clock a stall
+     * watchdog reads. Distinct from `finishedAt`, which is set once, at terminal.
+     */
+    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. An existing record is
+     * returned unchanged; `startedAt` (default `Date.now()`) applies only on
+     * first creation — matching core's `RunStore.createOrResume` invariant, which
+     * `runLogStore` maps directly onto this method.
+     */
+    open: (input: {
+        runId: string;
+        threadId: string;
+        startedAt?: number;
+    }) => Promise<RunLogRecord>;
+    /** 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>;
+    /**
+     * Patch the record's mutable fields ({@link RunRecordPatch}). Unknown `runId`
+     * is a NO-OP (never a throw, never a create) — core's `RunStore.update`
+     * invariant, which `runLogStore` maps onto this method.
+     *
+     * MUST wake blocked readers, exactly like `append`/`finish`: the record and
+     * the event log share one status field here, so a driver that terminalizes
+     * through its `RunStore` — core's `pipeToRunLog` writes its terminal status
+     * via `runs.update`, not `finish` — is ending the log with this call.
+     */
+    update: (runId: string, patch: RunRecordPatch) => Promise<void>;
+    /** Current record, or null if the run is unknown. */
+    get: (runId: string) => Promise<RunLogRecord | null>;
+    /** Every run record this log holds. Backs `RunStore.findActiveRun`. */
+    list: () => Promise<Array<RunLogRecord>>;
+    /** Replay-then-tail events with `seq > fromSeq` until the run is terminal. */
+    read: (runId: string, options?: RunEventLogReadOptions) => AsyncIterable<RunEvent>;
+}
+/**
+ * The record layout this log persisted before converging on core's run
+ * vocabulary. Never constructed by current code — it exists so
+ * {@link migrateStoredRunRecord} can name what it reads out of old storage.
+ */
+interface LegacyStoredRunRecord {
+    runId: string;
+    threadId?: string;
+    status: 'running' | 'done' | 'error' | 'aborted';
+    lastSeq: number;
+    error?: RunError;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Convert a stored record to the converged {@link RunLogRecord} layout.
+ *
+ * Total over both layouts: a converged record passes through unchanged
+ * (`migrated: false`), a legacy one is mapped as documented in the module
+ * header (`migrated: true`) so a durable backend can write the result back and
+ * pay the conversion exactly once.
+ */
+export declare function migrateStoredRunRecord(stored: RunLogRecord | LegacyStoredRunRecord): {
+    record: RunLogRecord;
+    migrated: boolean;
+};
+/**
+ * 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;
+        startedAt?: number;
+    }): Promise<RunLogRecord>;
+    append(runId: string, chunk: StreamChunk): Promise<number>;
+    finish(runId: string, status: TerminalRunStatus, error?: RunError): Promise<void>;
+    update(runId: string, patch: RunRecordPatch): Promise<void>;
+    get(runId: string): Promise<RunLogRecord | null>;
+    list(): Promise<Array<RunLogRecord>>;
+    read(runId: string, options?: RunEventLogReadOptions): AsyncIterable<RunEvent>;
+    private waitForChange;
+}
+export {};

package/dist/esm/run-log.js

@@ -0,0 +1,198 @@
+import { isTerminalRunStatus } from "@tanstack/ai";
+//#region src/run-log.ts
+/**
+* Resumable run event-log — the primitive that lets a trigger (e.g. a
+* Cloudflare Worker) start an agent run and return immediately while a durable
+* orchestrator (e.g. a Durable Object) drives the run and persists every
+* emitted {@link StreamChunk} under a monotonic `seq`.
+*
+* Clients tail the log from a cursor (`fromSeq`), so a dropped connection, a new
+* browser tab, or an orchestrator that hibernated between chunks all reconnect
+* cleanly: replay everything after the client's last-seen `seq`, then live-tail
+* until the run reaches a terminal status. The *run* never depends on any single
+* connection staying open — that is what makes the serverless/edge model work.
+*
+* This module is transport- and storage-agnostic. {@link InMemoryRunEventLog} is
+* the default (single-process / tests); a durable backend (DO storage, KV, SQL)
+* implements the same {@link RunEventLog} interface — see
+* {@link DurableObjectRunEventLog} in `./run-log-do`.
+*
+* ---
+*
+* CONVERGED VOCABULARY (v1) + LIVE-DATA MIGRATION:
+*
+* This module used to keep a legacy vocabulary distinct from core's
+* (`TerminalRunStatus = 'done' | 'error' | 'aborted'`, a `RunRecord` with
+* `lastSeq`/`createdAt`/`updatedAt` and an optional `threadId`), deferred
+* because adopting core's shape meant migrating the Durable Object's persisted
+* record layout. That migration is now done: run statuses, `RunError`, and the
+* record's lifecycle fields come from `@tanstack/ai` (`'completed' | 'failed'
+* | 'aborted'` terminal set, `startedAt`/`finishedAt`, required `threadId`),
+* and {@link RunLogRecord} is core's {@link RunRecord} plus the two fields only
+* an event log needs: the `lastSeq` cursor and the `updatedAt` activity clock.
+*
+* Records persisted under the legacy layout are migrated **in place, on first
+* read**, by {@link migrateStoredRunRecord}:
+*
+* - `status` `'done'` → `'completed'`, `'error'` → `'failed'`
+*   (`'running'`/`'aborted'` are unchanged);
+* - `createdAt` → `startedAt`; a terminal record gains
+*   `finishedAt = updatedAt` (the closest stored approximation);
+* - a record persisted without `threadId` gets `threadId = runId`. The log
+*   performs no thread-scoped queries, so this self-reference can never leak
+*   into thread history; it exists only to satisfy the converged shape.
+*
+* `DurableObjectRunEventLog` writes the migrated record back on the read that
+* migrated it, so each record pays the conversion exactly once. The migration
+* is client-visible where the record is: `GET /runs/:id` and the WebSocket
+* terminal `status` frame now carry core's status strings and field names.
+*/
+var LEGACY_STATUS_MAP = {
+	done: "completed",
+	error: "failed"
+};
+function isLegacyStoredRunRecord(value) {
+	return "createdAt" in value;
+}
+/**
+* Convert a stored record to the converged {@link RunLogRecord} layout.
+*
+* Total over both layouts: a converged record passes through unchanged
+* (`migrated: false`), a legacy one is mapped as documented in the module
+* header (`migrated: true`) so a durable backend can write the result back and
+* pay the conversion exactly once.
+*/
+function migrateStoredRunRecord(stored) {
+	if (!isLegacyStoredRunRecord(stored)) return {
+		record: stored,
+		migrated: false
+	};
+	const status = stored.status === "done" || stored.status === "error" ? LEGACY_STATUS_MAP[stored.status] : stored.status;
+	return {
+		record: {
+			runId: stored.runId,
+			threadId: stored.threadId ?? stored.runId,
+			status,
+			lastSeq: stored.lastSeq,
+			startedAt: stored.createdAt,
+			updatedAt: stored.updatedAt,
+			...isTerminalRunStatus(status) ? { finishedAt: stored.updatedAt } : {},
+			...stored.error !== void 0 ? { error: stored.error } : {}
+		},
+		migrated: true
+	};
+}
+/**
+* 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.
+*/
+var InMemoryRunEventLog = class {
+	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();
+	}
+	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,
+			threadId: input.threadId,
+			status: "running",
+			lastSeq: -1,
+			startedAt: input.startedAt ?? 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(/* @__PURE__ */ new Error(`run-log: unknown runId "${runId}"`));
+		if (isTerminalRunStatus(state.record.status)) return Promise.reject(/* @__PURE__ */ 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(/* @__PURE__ */ new Error(`run-log: unknown runId "${runId}"`));
+		if (isTerminalRunStatus(state.record.status)) return Promise.resolve();
+		const now = this.now();
+		state.record.status = status;
+		if (error !== void 0) state.record.error = error;
+		state.record.finishedAt = now;
+		state.record.updatedAt = now;
+		this.wake(state);
+		return Promise.resolve();
+	}
+	update(runId, patch) {
+		const state = this.runs.get(runId);
+		if (!state) return Promise.resolve();
+		state.record = {
+			...state.record,
+			...patch,
+			updatedAt: this.now()
+		};
+		this.wake(state);
+		return Promise.resolve();
+	}
+	get(runId) {
+		const state = this.runs.get(runId);
+		return Promise.resolve(state ? { ...state.record } : null);
+	}
+	list() {
+		return Promise.resolve([...this.runs.values()].map((state) => ({ ...state.record })));
+	}
+	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 });
+		});
+	}
+};
+//#endregion
+export { InMemoryRunEventLog, migrateStoredRunRecord };
+
+//# sourceMappingURL=run-log.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"run-log.js","names":[],"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\n * {@link DurableObjectRunEventLog} in `./run-log-do`.\n *\n * ---\n *\n * CONVERGED VOCABULARY (v1) + LIVE-DATA MIGRATION:\n *\n * This module used to keep a legacy vocabulary distinct from core's\n * (`TerminalRunStatus = 'done' | 'error' | 'aborted'`, a `RunRecord` with\n * `lastSeq`/`createdAt`/`updatedAt` and an optional `threadId`), deferred\n * because adopting core's shape meant migrating the Durable Object's persisted\n * record layout. That migration is now done: run statuses, `RunError`, and the\n * record's lifecycle fields come from `@tanstack/ai` (`'completed' | 'failed'\n * | 'aborted'` terminal set, `startedAt`/`finishedAt`, required `threadId`),\n * and {@link RunLogRecord} is core's {@link RunRecord} plus the two fields only\n * an event log needs: the `lastSeq` cursor and the `updatedAt` activity clock.\n *\n * Records persisted under the legacy layout are migrated **in place, on first\n * read**, by {@link migrateStoredRunRecord}:\n *\n * - `status` `'done'` → `'completed'`, `'error'` → `'failed'`\n *   (`'running'`/`'aborted'` are unchanged);\n * - `createdAt` → `startedAt`; a terminal record gains\n *   `finishedAt = updatedAt` (the closest stored approximation);\n * - a record persisted without `threadId` gets `threadId = runId`. The log\n *   performs no thread-scoped queries, so this self-reference can never leak\n *   into thread history; it exists only to satisfy the converged shape.\n *\n * `DurableObjectRunEventLog` writes the migrated record back on the read that\n * migrated it, so each record pays the conversion exactly once. The migration\n * is client-visible where the record is: `GET /runs/:id` and the WebSocket\n * terminal `status` frame now carry core's status strings and field names.\n */\nimport { isTerminalRunStatus } from '@tanstack/ai'\nimport type {\n  RunError,\n  RunRecord,\n  RunStore,\n  StreamChunk,\n  TerminalRunStatus,\n} from '@tanstack/ai'\n\n/**\n * The mutable-field patch a {@link RunStore.update} accepts, reused verbatim so\n * the log can back a `RunStore` without restating (and drifting from) the pick.\n */\nexport type RunRecordPatch = Parameters<RunStore['update']>[1]\n\n/**\n * Durable bookkeeping for one run in the event log: core's {@link RunRecord}\n * plus the two fields only an event log needs.\n */\nexport interface RunLogRecord extends RunRecord {\n  /** Seq of the last appended event, or `-1` when no events yet. */\n  lastSeq: number\n  /**\n   * Epoch ms of the last append or status change — the activity clock a stall\n   * watchdog reads. Distinct from `finishedAt`, which is set once, at terminal.\n   */\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  /**\n   * Idempotently create (or return) the run record. An existing record is\n   * returned unchanged; `startedAt` (default `Date.now()`) applies only on\n   * first creation — matching core's `RunStore.createOrResume` invariant, which\n   * `runLogStore` maps directly onto this method.\n   */\n  open: (input: {\n    runId: string\n    threadId: string\n    startedAt?: number\n  }) => Promise<RunLogRecord>\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  /**\n   * Patch the record's mutable fields ({@link RunRecordPatch}). Unknown `runId`\n   * is a NO-OP (never a throw, never a create) — core's `RunStore.update`\n   * invariant, which `runLogStore` maps onto this method.\n   *\n   * MUST wake blocked readers, exactly like `append`/`finish`: the record and\n   * the event log share one status field here, so a driver that terminalizes\n   * through its `RunStore` — core's `pipeToRunLog` writes its terminal status\n   * via `runs.update`, not `finish` — is ending the log with this call.\n   */\n  update: (runId: string, patch: RunRecordPatch) => Promise<void>\n  /** Current record, or null if the run is unknown. */\n  get: (runId: string) => Promise<RunLogRecord | null>\n  /** Every run record this log holds. Backs `RunStore.findActiveRun`. */\n  list: () => Promise<Array<RunLogRecord>>\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/**\n * The record layout this log persisted before converging on core's run\n * vocabulary. Never constructed by current code — it exists so\n * {@link migrateStoredRunRecord} can name what it reads out of old storage.\n */\ninterface LegacyStoredRunRecord {\n  runId: string\n  threadId?: string\n  status: 'running' | 'done' | 'error' | 'aborted'\n  lastSeq: number\n  error?: RunError\n  createdAt: number\n  updatedAt: number\n}\n\nconst LEGACY_STATUS_MAP = {\n  done: 'completed',\n  error: 'failed',\n} as const\n\nfunction isLegacyStoredRunRecord(\n  value: RunLogRecord | LegacyStoredRunRecord,\n): value is LegacyStoredRunRecord {\n  // `createdAt` is the discriminant: it exists on every legacy record and on no\n  // converged one. Status alone would miss legacy `running`/`aborted` records.\n  return 'createdAt' in value\n}\n\n/**\n * Convert a stored record to the converged {@link RunLogRecord} layout.\n *\n * Total over both layouts: a converged record passes through unchanged\n * (`migrated: false`), a legacy one is mapped as documented in the module\n * header (`migrated: true`) so a durable backend can write the result back and\n * pay the conversion exactly once.\n */\nexport function migrateStoredRunRecord(\n  stored: RunLogRecord | LegacyStoredRunRecord,\n): { record: RunLogRecord; migrated: boolean } {\n  if (!isLegacyStoredRunRecord(stored))\n    return { record: stored, migrated: false }\n  const status =\n    stored.status === 'done' || stored.status === 'error'\n      ? LEGACY_STATUS_MAP[stored.status]\n      : stored.status\n  const record: RunLogRecord = {\n    runId: stored.runId,\n    // See the module header: the log runs no thread-scoped queries, so a\n    // legacy record without a thread gets a self-reference, never a fake one.\n    threadId: stored.threadId ?? stored.runId,\n    status,\n    lastSeq: stored.lastSeq,\n    startedAt: stored.createdAt,\n    updatedAt: stored.updatedAt,\n    ...(isTerminalRunStatus(status) ? { finishedAt: stored.updatedAt } : {}),\n    ...(stored.error !== undefined ? { error: stored.error } : {}),\n  }\n  return { record, migrated: true }\n}\n\n/** Per-run state for the in-memory log. */\ninterface RunState {\n  record: RunLogRecord\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: {\n    runId: string\n    threadId: string\n    startedAt?: number\n  }): Promise<RunLogRecord> {\n    const existing = this.runs.get(input.runId)\n    if (existing) return Promise.resolve({ ...existing.record })\n    const now = this.now()\n    const record: RunLogRecord = {\n      runId: input.runId,\n      threadId: input.threadId,\n      status: 'running',\n      lastSeq: -1,\n      startedAt: input.startedAt ?? 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    const now = this.now()\n    state.record.status = status\n    if (error !== undefined) state.record.error = error\n    state.record.finishedAt = now\n    state.record.updatedAt = now\n    this.wake(state)\n    return Promise.resolve()\n  }\n\n  update(runId: string, patch: RunRecordPatch): Promise<void> {\n    const state = this.runs.get(runId)\n    if (!state) return Promise.resolve() // unknown runId is a no-op\n    state.record = { ...state.record, ...patch, updatedAt: this.now() }\n    // A patch may terminalize the shared status field (core's driver writes its\n    // terminal status through `RunStore.update`) — parked readers must see it.\n    this.wake(state)\n    return Promise.resolve()\n  }\n\n  get(runId: string): Promise<RunLogRecord | null> {\n    const state = this.runs.get(runId)\n    return Promise.resolve(state ? { ...state.record } : null)\n  }\n\n  list(): Promise<Array<RunLogRecord>> {\n    return Promise.resolve(\n      [...this.runs.values()].map((state) => ({ ...state.record })),\n    )\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"],"mappings":"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"}

package/dist/esm/runner.js

@@ -1,107 +1,158 @@
-import { createServer } from "node:http";
+import { parseContainerRunRequest } from "./protocol.js";
+import { createSecrets, defineSandbox, defineWorkspace, httpRemoteToolExecutor, remoteToolStubs, withSandbox } from "@tanstack/ai-sandbox";
 import { EventType, chat } from "@tanstack/ai";
-import { defineSandbox, withSandbox, remoteToolStubs, httpRemoteToolExecutor, defineWorkspace, createSecrets } from "@tanstack/ai-sandbox";
+import { createServer } from "node:http";
 import { localProcessSandbox } from "@tanstack/ai-sandbox-local-process";
-import { parseContainerRunRequest } from "./protocol.js";
+//#region src/runner.ts
+/**
+* `runInContainerHarness` — the IN-CONTAINER harness runner, shipped from the
+* package so a co-located app's container program is a single function call.
+*
+* This is the heart of the CO-LOCATED model: the agent harness loop AND its MCP
+* tool-bridge run HERE, on the container's own localhost. The Durable Object
+* outside never calls `chat()`; it POSTs `/run` to this server and reads the
+* NDJSON stream back.
+*
+*   DO  ── POST /run {messages, harness, model, workspace, toolDescriptors,
+*                     toolExecUrl, toolExecToken} ──▶  THIS
+*   THIS ── NDJSON stream of StreamChunk ──────────────────────────────────▶  DO
+*
+* It is a tiny `node:http` server (NODE/container side — NOT Workers; it uses
+* `localProcessSandbox`). On `POST /run` it validates the {@link
+* ContainerRunRequest}, builds `chat()` with the in-container `local-process`
+* sandbox and the adapter the CALLER resolves, and streams each {@link
+* StreamChunk} back as NDJSON (one JSON object per line).
+*
+* Why the MCP bridge is genuinely in-container: the in-container sandbox is
+* `localProcessSandbox()` — the container IS the host — so the harness adapter
+* serves its tool-bridge over the container's own `localhost` and feeds the
+* prompt over NATIVE writable stdin (no file-redirect; the bridge URL/token
+* never leave the container). The MCP protocol never crosses the network.
+*
+* The ONE thing that still crosses back to the DO is host-tool EXECUTION: each
+* tool rebuilt by {@link remoteToolStubs} delegates its `execute()` to {@link
+* httpRemoteToolExecutor}, which POSTs `{ name, args }` (bearer-gated) to the
+* DO's `toolExecUrl`:
+*
+*   agent → in-container MCP bridge → stub.execute → httpRemoteToolExecutor → DO
+*
+* The app supplies only `resolveAdapter` — which `*Text` adapter to build for a
+* given `{ harness, model }`. The server + `chat()` wiring lives here, so the
+* package doesn't depend on every adapter package.
+*
+* NOTE: container-side Node code — compiles against the real TanStack AI types;
+* not runtime-verified in this repo (no container build in CI).
+*/
+/** Read a request body fully into a string (small JSON payloads only). */
 function readBody(req) {
-  return new Promise((resolve, reject) => {
-    let body = "";
-    req.setEncoding("utf8");
-    req.on("data", (chunk) => {
-      body += chunk;
-    });
-    req.on("end", () => resolve(body));
-    req.on("error", reject);
-  });
+	return new Promise((resolve, reject) => {
+		let body = "";
+		req.setEncoding("utf8");
+		req.on("data", (chunk) => {
+			body += chunk;
+		});
+		req.on("end", () => resolve(body));
+		req.on("error", reject);
+	});
 }
+/**
+* Rebuild the request's workspace with a real `createSecrets`, pulling each
+* referenced secret's VALUE from the container env. Secret values never cross
+* the `POST /run` boundary (`createSecrets` stores them under a non-enumerable
+* symbol, so serializing the workspace carries only the names) — the DO injects
+* them into the container env via `sandbox.setEnvVars`, and we reconstitute them
+* here. A referenced secret missing from the env is a hard error, never a silent
+* keyless run.
+*/
 function reconstituteWorkspace(workspace) {
-  if (workspace.secrets === void 0) return workspace;
-  const names = Object.keys(workspace.secrets);
-  if (names.length === 0) return workspace;
-  const values = {};
-  for (const name of names) {
-    const value = process.env[name];
-    if (value === void 0 || value === "") {
-      throw new Error(
-        `runInContainerHarness: secret "${name}" is not set in the container env`
-      );
-    }
-    values[name] = value;
-  }
-  return defineWorkspace({ ...workspace, secrets: createSecrets(values) });
+	if (workspace.secrets === void 0) return workspace;
+	const names = Object.keys(workspace.secrets);
+	if (names.length === 0) return workspace;
+	const values = {};
+	for (const name of names) {
+		const value = process.env[name];
+		if (value === void 0 || value === "") throw new Error(`runInContainerHarness: secret "${name}" is not set in the container env`);
+		values[name] = value;
+	}
+	return defineWorkspace({
+		...workspace,
+		secrets: createSecrets(values)
+	});
 }
+/**
+* Build the `chat()` stream that runs the harness on THIS container via the
+* `local-process` sandbox. The agent's `chat()` tools are stubs that delegate
+* back to the DO; everything else (the harness loop, the MCP bridge, stdin)
+* stays on localhost.
+*/
 function runAgent(request, resolveAdapter) {
-  const sandbox = defineSandbox({
-    // The container IS the host: no isolation, just run on its own filesystem.
-    id: "colocated-in-container",
-    provider: localProcessSandbox(),
-    // Honor the app's workspace (source / setup / skills / …), with the secrets
-    // re-resolved from the container env.
-    workspace: reconstituteWorkspace(request.workspace)
-  });
-  return chat({
-    threadId: request.threadId,
-    adapter: resolveAdapter({
-      harness: request.harness,
-      model: request.model
-    }),
-    messages: request.messages,
-    stream: true,
-    // Rebuild the DO's host tools as stubs whose execute() POSTs back to the DO.
-    // The adapter bridges them over the in-container localhost MCP transport.
-    tools: remoteToolStubs(
-      request.toolDescriptors,
-      httpRemoteToolExecutor(request.toolExecUrl, request.toolExecToken)
-    ),
-    // Provide the in-container local-process sandbox handle the adapter needs.
-    middleware: [withSandbox(sandbox)]
-  });
+	const sandbox = defineSandbox({
+		id: "colocated-in-container",
+		provider: localProcessSandbox(),
+		workspace: reconstituteWorkspace(request.workspace)
+	});
+	return chat({
+		threadId: request.threadId,
+		adapter: resolveAdapter({
+			harness: request.harness,
+			model: request.model
+		}),
+		messages: request.messages,
+		stream: true,
+		tools: remoteToolStubs(request.toolDescriptors, httpRemoteToolExecutor(request.toolExecUrl, request.toolExecToken)),
+		middleware: [withSandbox(sandbox)]
+	});
 }
+/** Stream the agent's chunks to the response as NDJSON, one object per line. */
 async function handleRun(req, res, resolveAdapter) {
-  const parsed = JSON.parse(await readBody(req));
-  const request = parseContainerRunRequest(parsed);
-  res.writeHead(200, {
-    "content-type": "application/x-ndjson",
-    "cache-control": "no-cache"
-  });
-  try {
-    for await (const chunk of runAgent(request, resolveAdapter)) {
-      res.write(`${JSON.stringify(chunk)}
-`);
-    }
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    res.write(`${JSON.stringify({ type: EventType.RUN_ERROR, message })}
-`);
-  } finally {
-    res.end();
-  }
+	const request = parseContainerRunRequest(JSON.parse(await readBody(req)));
+	res.writeHead(200, {
+		"content-type": "application/x-ndjson",
+		"cache-control": "no-cache"
+	});
+	try {
+		for await (const chunk of runAgent(request, resolveAdapter)) res.write(`${JSON.stringify(chunk)}\n`);
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error);
+		res.write(`${JSON.stringify({
+			type: EventType.RUN_ERROR,
+			message
+		})}\n`);
+	} finally {
+		res.end();
+	}
 }
+/**
+* Start the in-container harness runner: a `node:http` server with `GET /health`
+* and `POST /run`. Call this as the container's program; the app supplies only
+* `resolveAdapter`.
+*/
 function runInContainerHarness(options) {
-  const port = options.port ?? Number.parseInt(process.env.RUNNER_PORT ?? "8080", 10);
-  const server = createServer((req, res) => {
-    if (req.method === "POST" && req.url === "/run") {
-      handleRun(req, res, options.resolveAdapter).catch((error) => {
-        const message = error instanceof Error ? error.message : String(error);
-        if (!res.headersSent) {
-          res.writeHead(400, { "content-type": "text/plain" });
-        }
-        res.end(message);
-      });
-      return;
-    }
-    if (req.method === "GET" && req.url === "/health") {
-      res.writeHead(200).end("ok");
-      return;
-    }
-    res.writeHead(404).end("not found");
-  });
-  server.listen(port, () => {
-    console.log(`[container-runner] listening on :${port}`);
-  });
-  return { server, port };
+	const port = options.port ?? Number.parseInt(process.env.RUNNER_PORT ?? "8080", 10);
+	const server = createServer((req, res) => {
+		if (req.method === "POST" && req.url === "/run") {
+			handleRun(req, res, options.resolveAdapter).catch((error) => {
+				const message = error instanceof Error ? error.message : String(error);
+				if (!res.headersSent) res.writeHead(400, { "content-type": "text/plain" });
+				res.end(message);
+			});
+			return;
+		}
+		if (req.method === "GET" && req.url === "/health") {
+			res.writeHead(200).end("ok");
+			return;
+		}
+		res.writeHead(404).end("not found");
+	});
+	server.listen(port, () => {
+		console.log(`[container-runner] listening on :${port}`);
+	});
+	return {
+		server,
+		port
+	};
 }
-export {
-  runInContainerHarness
-};
-//# sourceMappingURL=runner.js.map
+//#endregion
+export { runInContainerHarness };
+
+//# sourceMappingURL=runner.js.map