@tanstack/ai-sandbox 0.2.3 → 0.3.0

package/dist/esm/runner.d.ts

@@ -1,4 +1,5 @@
 import { ProcessOptions, SandboxHandle } from './contracts.js';
+import { RunStore } from '@tanstack/ai';
 export interface SpawnNdjsonOptions extends ProcessOptions {
     /**
      * Called for each raw stdout line that is non-empty but fails JSON parsing
@@ -10,12 +11,128 @@ export interface SpawnNdjsonOptions extends ProcessOptions {
      * e.g. the agent prompt for `claude -p`. Avoids putting the prompt in argv.
      */
     input?: string;
+    /**
+     * Route the agent's stdout through an in-sandbox journal rather than holding
+     * its pipe directly.
+     *
+     * This is what makes a run survive host death: with nothing piped, there is
+     * no reader whose disappearance can SIGPIPE the agent, and a later host reads
+     * the same file from byte 0. Opt-in so every existing caller (and every
+     * existing test) is unaffected.
+     */
+    journal?: JournalOptions;
 }
+/** Journaling configuration for {@link spawnNdjson}. */
+export interface JournalOptions {
+    /** Run id the journal path is derived from. Must match across hosts. */
+    runId: string;
+    /** Journal directory. Defaults to `/tmp/tanstack-runs`. */
+    dir?: string;
+    /**
+     * Read an EXISTING journal instead of starting the agent. The read still
+     * begins at byte 0 — the alignment step, not the reader, decides what has
+     * already been delivered.
+     */
+    attach?: boolean;
+    /** Poll interval for providers that cannot follow. */
+    pollIntervalMs?: number;
+    /**
+     * Run record store, consulted ONLY on an attach and only when the journal is
+     * absent, to tell "not written yet" from "will never be written" (see
+     * `attach-preflight.ts`). Optional so an attach with no store wired keeps the
+     * bounded wait while losing the unknown/terminal classification.
+     */
+    runs?: RunStore;
+    /**
+     * Bounded wait for a live run's journal to appear on an attach, AND — on every
+     * path, attach or fresh — the bound on the read's first byte
+     * (`ReadJournalOptions.firstByteTimeoutMs`). One knob for both because they
+     * bound the same question from two sides: the preflight covers "the file does
+     * not exist", the read covers "the file exists but nothing is writing to it",
+     * and a caller that widens one always means to widen the other.
+     *
+     * Defaults to `DEFAULT_ATTACH_JOURNAL_WAIT_MS`.
+     */
+    attachWaitMs?: number;
+}
+type JournaledOptions = SpawnNdjsonOptions & {
+    journal: JournalOptions;
+};
 /** Split a stream of arbitrary string chunks into complete lines. */
 export declare function toLines(chunks: AsyncIterable<string>): AsyncIterable<string>;
+/**
+ * Start the agent with its stdout (and the `{"__exit":N}` sentinel) redirected
+ * into the journal, then return.
+ *
+ * Deliberately does NOT wait for the process and does NOT read its stdout: the
+ * whole point of journaling is that the host holds no handle on the agent's
+ * output, so a host that dies mid-run cannot take the agent down with it (no
+ * pipe to SIGPIPE). The spawned process is left running in the sandbox; the
+ * sentinel line the wrapper appends on exit is how anyone — this host or a
+ * successor — learns it finished. Stdin is still written directly to the
+ * spawned process, exactly as the unjournaled path does, since that transport
+ * is unaffected by where stdout goes.
+ */
+export declare function startJournaledAgent(handle: SandboxHandle, command: string, options: JournaledOptions): Promise<void>;
+/**
+ * Read a run's journal and yield each line parsed as JSON.
+ *
+ * Always reads from byte 0 — the alignment step (a later phase), not this
+ * reader, decides what a client has already seen. Stops at the `{"__exit":N}`
+ * sentinel, and throws for a non-zero N so the calling adapter's existing
+ * `catch` turns it into a `RUN_ERROR`, the same observable outcome the
+ * unjournaled path produces from a non-zero `wait()`. There is nothing to
+ * `wait()` on here: the host holds a `tail`, not the agent process, so the
+ * sentinel line IS the exit code.
+ *
+ * The sentinel is also what bounds journal growth: reaching it means the run is
+ * terminal, and a terminal run's record is the event log, so both journal files
+ * are deleted before this iterable finishes. The ordering below is load-bearing
+ * and is asserted, not merely commented:
+ *
+ * - The sentinel is captured and the loop is `break`-ed, so the source's
+ *   `finally` kills the `tail` BEFORE the `rm` runs — the reader is stopped, then
+ *   its input is deleted, never the other way round.
+ * - `exitCode` stays `undefined` if the journal stream ends without a sentinel.
+ *   NOTHING is deleted on that path either way — the run may be mid-flight and a
+ *   successor host may still need every byte — but the two causes are then
+ *   separated by `options.signal.aborted`: an aborted consumer returns quietly,
+ *   while a stream that died on its own (killed `tail`, destroyed sandbox, torn
+ *   pipe) THROWS. Returning for both is how a truncated read used to reach the
+ *   client as a normally-completing run.
+ * - A non-zero sentinel deletes too. The run is terminal either way.
+ * - The stderr sidecar is read BEFORE the deletion that destroys it, so a
+ *   non-zero exit carries up to {@link STDERR_ERROR_CHARS} chars of the agent's
+ *   own diagnostics, exactly as the unjournaled path below does. That closes the
+ *   "Known regression" this function used to document; the read is bounded and
+ *   failure-swallowing (see {@link readStderrTail}), so it cannot turn a run
+ *   failure into a cleanup failure.
+ *
+ * On an ATTACH (`journal.attach === true`) the read is preceded by
+ * {@link awaitAttachableJournal}, which fails fast for a runId the store does not
+ * know or has already terminalized and otherwise waits a BOUNDED time for a live
+ * run's journal to appear. Without it, an attach to a runId with no journal
+ * created an empty one (`journalFollowCommand` does that deliberately) and tailed
+ * it forever — no sentinel, no error, no timeout.
+ *
+ * One case this does NOT bound: a run that reaches its sentinel while DETACHED
+ * has no host reading it, so nothing observes the sentinel and nothing here
+ * runs. Sweeping those is `pruneJournals`' job (`journal-sweep.ts`): it consults
+ * the run store's status for each journal it finds and deletes only the terminal
+ * ones, from a cron the application schedules rather than from a run.
+ */
+export declare function readJournalNdjson(handle: SandboxHandle, options: JournaledOptions): AsyncIterable<unknown>;
 /**
  * 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.
+ *
+ * Without `options.journal`, behavior is byte-identical to before: 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.
+ *
+ * With `options.journal`, the agent's stdout is redirected into an in-sandbox
+ * journal (unless `journal.attach` is set, meaning a run already in flight)
+ * and then read back from byte 0 — one code path for a fresh run and an
+ * attach, both going through {@link readJournalNdjson}.
  */
 export declare function spawnNdjson(handle: SandboxHandle, command: string, options?: SpawnNdjsonOptions): AsyncIterable<unknown>;
+export {};

package/dist/esm/runner.js

@@ -1,54 +1,273 @@
+import { journalCleanupCommand, journalPaths, journalStderrReadCommand, journaledCommand, parseExitSentinel } from "./journal.js";
+import { awaitAttachableJournal } from "./attach-preflight.js";
+import { decodeBase64Stream } from "./journal-bytes.js";
+import { readJournal } from "./journal-reader.js";
+//#region src/runner.ts
+/**
+* The reusable "run an agent CLI inside a sandbox and stream its events out"
+* primitive. Harness adapters (claude-code, codex, …) spawn their CLI via the
+* uniform {@link SandboxHandle} and consume newline-delimited JSON from stdout,
+* which they then translate into AG-UI StreamChunks.
+*
+* This is intentionally transport-minimal: a stdout NDJSON pipe. Multi-client
+* reconnect / replay belongs to the persistence/EventLog layer, not here.
+*
+* The `journal` option adds a second, opt-in transport: instead of holding the
+* agent's stdout pipe directly, the host redirects it into an append-only file
+* inside the sandbox and tails that file. See `journal.ts` for why (host death
+* cannot SIGPIPE the agent, and a later host can resume the same file from byte
+* 0). `spawnNdjson`'s signature and unjournaled behavior are unchanged; every
+* existing caller keeps working exactly as before.
+*/
+function isJournaled(options) {
+	return options.journal !== void 0;
+}
+function resolvePaths(options) {
+	return journalPaths(options.journal.runId, options.journal.dir);
+}
+/**
+* Strip the runner-only options, leaving what `handle.process.spawn` accepts.
+*
+* `signal` is deliberately KEPT: on the UNJOURNALED path the host holds the
+* agent's stdout pipe, so a client disconnect should take the process down with
+* it. The journaled path must not forward it — see
+* {@link toJournaledSpawnOptions}.
+*/
+function toProcessOptions(options) {
+	const { onNonJsonLine, input, journal, ...rest } = options;
+	return rest;
+}
+/**
+* The journaled agent's spawn options: {@link toProcessOptions} MINUS `signal`.
+*
+* The request's signal must never reach the agent process on this path. Providers
+* DO act on it at spawn time — local-process registers it to `killTree` the
+* process group, and daytona and docker honor it too — so forwarding it means a
+* client disconnect kills the journaled agent. The agent then writes no exit
+* sentinel, and a successor host takes over a run that is already dead: the exact
+* opposite of the guarantee documented on {@link startJournaledAgent}, and of the
+* reason the journal is a file rather than a pipe.
+*
+* The signal is still honored for the READ. `readJournalNdjson` forwards it to
+* `readJournal` and `awaitAttachableJournal` on its own, so a disconnecting
+* client stops tailing immediately. Only the agent spawn outlives the request.
+*/
+function toJournaledSpawnOptions(options) {
+	const { signal, ...rest } = toProcessOptions(options);
+	return rest;
+}
+/** Split a stream of arbitrary string chunks into complete lines. */
 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;
+	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;
+}
+/**
+* Start the agent with its stdout (and the `{"__exit":N}` sentinel) redirected
+* into the journal, then return.
+*
+* Deliberately does NOT wait for the process and does NOT read its stdout: the
+* whole point of journaling is that the host holds no handle on the agent's
+* output, so a host that dies mid-run cannot take the agent down with it (no
+* pipe to SIGPIPE). The spawned process is left running in the sandbox; the
+* sentinel line the wrapper appends on exit is how anyone — this host or a
+* successor — learns it finished. Stdin is still written directly to the
+* spawned process, exactly as the unjournaled path does, since that transport
+* is unaffected by where stdout goes.
+*/
+async function startJournaledAgent(handle, command, options) {
+	const paths = resolvePaths(options);
+	const proc = await handle.process.spawn(journaledCommand(command, paths), toJournaledSpawnOptions(options));
+	if (options.input !== void 0) {
+		await proc.stdin.write(options.input);
+		await proc.stdin.end();
+	}
 }
+/** Chars of stderr attached to a non-zero-exit error, on both paths. */
+var STDERR_ERROR_CHARS = 1e3;
+async function* singleValue(value) {
+	yield value;
+}
+/**
+* Read the tail of a run's stderr sidecar, for the error message only.
+*
+* Returns `''` on ANY failure — a provider whose `exec` rejects, a sidecar that
+* no longer exists, a base64 frame the provider truncated. The caller is on its
+* way to throwing the real failure (the agent's non-zero exit), and losing a
+* diagnostic suffix must never replace that error with a cleanup error. Decoding
+* is deliberately lossy: `journalStderrReadCommand` reads the LAST N bytes, so
+* byte 0 of the frame can sit mid-character.
+*/
+async function readStderrTail(handle, paths) {
+	try {
+		const result = await handle.process.exec(journalStderrReadCommand(paths));
+		const decoder = new TextDecoder();
+		let text = "";
+		for await (const bytes of decodeBase64Stream(singleValue(result.stdout))) text += decoder.decode(bytes, { stream: true });
+		text += decoder.decode();
+		return text.trim();
+	} catch {
+		return "";
+	}
+}
+/**
+* Delete a terminal run's journal. Best effort by construction: see
+* {@link journalCleanupCommand} for why a failure here cannot be allowed to fail
+* a run that has already finished.
+*/
+async function cleanupJournal(handle, paths) {
+	try {
+		await handle.process.exec(journalCleanupCommand(paths));
+	} catch {}
+}
+/**
+* Read a run's journal and yield each line parsed as JSON.
+*
+* Always reads from byte 0 — the alignment step (a later phase), not this
+* reader, decides what a client has already seen. Stops at the `{"__exit":N}`
+* sentinel, and throws for a non-zero N so the calling adapter's existing
+* `catch` turns it into a `RUN_ERROR`, the same observable outcome the
+* unjournaled path produces from a non-zero `wait()`. There is nothing to
+* `wait()` on here: the host holds a `tail`, not the agent process, so the
+* sentinel line IS the exit code.
+*
+* The sentinel is also what bounds journal growth: reaching it means the run is
+* terminal, and a terminal run's record is the event log, so both journal files
+* are deleted before this iterable finishes. The ordering below is load-bearing
+* and is asserted, not merely commented:
+*
+* - The sentinel is captured and the loop is `break`-ed, so the source's
+*   `finally` kills the `tail` BEFORE the `rm` runs — the reader is stopped, then
+*   its input is deleted, never the other way round.
+* - `exitCode` stays `undefined` if the journal stream ends without a sentinel.
+*   NOTHING is deleted on that path either way — the run may be mid-flight and a
+*   successor host may still need every byte — but the two causes are then
+*   separated by `options.signal.aborted`: an aborted consumer returns quietly,
+*   while a stream that died on its own (killed `tail`, destroyed sandbox, torn
+*   pipe) THROWS. Returning for both is how a truncated read used to reach the
+*   client as a normally-completing run.
+* - A non-zero sentinel deletes too. The run is terminal either way.
+* - The stderr sidecar is read BEFORE the deletion that destroys it, so a
+*   non-zero exit carries up to {@link STDERR_ERROR_CHARS} chars of the agent's
+*   own diagnostics, exactly as the unjournaled path below does. That closes the
+*   "Known regression" this function used to document; the read is bounded and
+*   failure-swallowing (see {@link readStderrTail}), so it cannot turn a run
+*   failure into a cleanup failure.
+*
+* On an ATTACH (`journal.attach === true`) the read is preceded by
+* {@link awaitAttachableJournal}, which fails fast for a runId the store does not
+* know or has already terminalized and otherwise waits a BOUNDED time for a live
+* run's journal to appear. Without it, an attach to a runId with no journal
+* created an empty one (`journalFollowCommand` does that deliberately) and tailed
+* it forever — no sentinel, no error, no timeout.
+*
+* One case this does NOT bound: a run that reaches its sentinel while DETACHED
+* has no host reading it, so nothing observes the sentinel and nothing here
+* runs. Sweeping those is `pruneJournals`' job (`journal-sweep.ts`): it consults
+* the run store's status for each journal it finds and deletes only the terminal
+* ones, from a cron the application schedules rather than from a run.
+*/
+async function* readJournalNdjson(handle, options) {
+	const paths = resolvePaths(options);
+	if (options.journal.attach === true) await awaitAttachableJournal(handle, {
+		paths,
+		runId: options.journal.runId,
+		...options.journal.runs === void 0 ? {} : { runs: options.journal.runs },
+		...options.journal.attachWaitMs === void 0 ? {} : { waitMs: options.journal.attachWaitMs },
+		...options.signal === void 0 ? {} : { signal: options.signal }
+	});
+	let exitCode;
+	for await (const { line } of readJournal(handle, {
+		paths,
+		fromByte: 0,
+		runId: options.journal.runId,
+		...options.signal === void 0 ? {} : { signal: options.signal },
+		...options.journal.pollIntervalMs === void 0 ? {} : { pollIntervalMs: options.journal.pollIntervalMs },
+		...options.journal.attachWaitMs === void 0 ? {} : { firstByteTimeoutMs: options.journal.attachWaitMs }
+	})) {
+		const trimmed = line.trim();
+		if (trimmed === "") continue;
+		const sentinel = parseExitSentinel(trimmed, paths);
+		if (sentinel !== null) {
+			exitCode = sentinel;
+			break;
+		}
+		let parsed;
+		try {
+			parsed = JSON.parse(trimmed);
+		} catch {
+			options.onNonJsonLine?.(trimmed);
+			continue;
+		}
+		yield parsed;
+	}
+	if (exitCode === void 0) {
+		if (options.signal?.aborted === true) return;
+		throw new Error(`Agent journal stream for run ${options.journal.runId} ended without an exit sentinel (${paths.journal}). The run was NOT observed to finish: the tail was torn down, the sandbox went away, or the agent's shell died before writing its sentinel. Both journal files are left in place for a successor host.`);
+	}
+	const stderr = exitCode === 0 ? "" : await readStderrTail(handle, paths);
+	await cleanupJournal(handle, paths);
+	if (exitCode !== 0) throw new Error(`Agent process exited with code ${exitCode}` + (stderr ? `: ${stderr.slice(0, STDERR_ERROR_CHARS)}` : ""));
+}
+/**
+* Spawn `command` in the sandbox and yield each stdout line parsed as JSON.
+*
+* Without `options.journal`, behavior is byte-identical to before: 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.
+*
+* With `options.journal`, the agent's stdout is redirected into an in-sandbox
+* journal (unless `journal.attach` is set, meaning a run already in flight)
+* and then read back from byte 0 — one code path for a fresh run and an
+* attach, both going through {@link readJournalNdjson}.
+*/
 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
+	if (isJournaled(options)) {
+		if (options.journal.attach !== true) await startJournaledAgent(handle, command, options);
+		yield* readJournalNdjson(handle, options);
+		return;
+	}
+	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, STDERR_ERROR_CHARS)}` : ""));
+	}
+}
+//#endregion
+export { readJournalNdjson, spawnNdjson, startJournaledAgent, toLines };
+
+//# sourceMappingURL=runner.js.map

package/dist/esm/runner.js.map

@@ -1 +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;"}
+{"version":3,"file":"runner.js","names":[],"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 *\n * The `journal` option adds a second, opt-in transport: instead of holding the\n * agent's stdout pipe directly, the host redirects it into an append-only file\n * inside the sandbox and tails that file. See `journal.ts` for why (host death\n * cannot SIGPIPE the agent, and a later host can resume the same file from byte\n * 0). `spawnNdjson`'s signature and unjournaled behavior are unchanged; every\n * existing caller keeps working exactly as before.\n */\nimport {\n  journalCleanupCommand,\n  journalPaths,\n  journalStderrReadCommand,\n  journaledCommand,\n  parseExitSentinel,\n} from './journal'\nimport { readJournal } from './journal-reader'\nimport { decodeBase64Stream } from './journal-bytes'\nimport { awaitAttachableJournal } from './attach-preflight'\nimport type { JournalPaths } from './journal'\nimport type { ProcessOptions, SandboxHandle } from './contracts'\nimport type { RunStore } from '@tanstack/ai'\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   * Route the agent's stdout through an in-sandbox journal rather than holding\n   * its pipe directly.\n   *\n   * This is what makes a run survive host death: with nothing piped, there is\n   * no reader whose disappearance can SIGPIPE the agent, and a later host reads\n   * the same file from byte 0. Opt-in so every existing caller (and every\n   * existing test) is unaffected.\n   */\n  journal?: JournalOptions\n}\n\n/** Journaling configuration for {@link spawnNdjson}. */\nexport interface JournalOptions {\n  /** Run id the journal path is derived from. Must match across hosts. */\n  runId: string\n  /** Journal directory. Defaults to `/tmp/tanstack-runs`. */\n  dir?: string\n  /**\n   * Read an EXISTING journal instead of starting the agent. The read still\n   * begins at byte 0 — the alignment step, not the reader, decides what has\n   * already been delivered.\n   */\n  attach?: boolean\n  /** Poll interval for providers that cannot follow. */\n  pollIntervalMs?: number\n  /**\n   * Run record store, consulted ONLY on an attach and only when the journal is\n   * absent, to tell \"not written yet\" from \"will never be written\" (see\n   * `attach-preflight.ts`). Optional so an attach with no store wired keeps the\n   * bounded wait while losing the unknown/terminal classification.\n   */\n  runs?: RunStore\n  /**\n   * Bounded wait for a live run's journal to appear on an attach, AND — on every\n   * path, attach or fresh — the bound on the read's first byte\n   * (`ReadJournalOptions.firstByteTimeoutMs`). One knob for both because they\n   * bound the same question from two sides: the preflight covers \"the file does\n   * not exist\", the read covers \"the file exists but nothing is writing to it\",\n   * and a caller that widens one always means to widen the other.\n   *\n   * Defaults to `DEFAULT_ATTACH_JOURNAL_WAIT_MS`.\n   */\n  attachWaitMs?: number\n}\n\ntype JournaledOptions = SpawnNdjsonOptions & { journal: JournalOptions }\n\nfunction isJournaled(options: SpawnNdjsonOptions): options is JournaledOptions {\n  return options.journal !== undefined\n}\n\nfunction resolvePaths(options: JournaledOptions) {\n  return journalPaths(options.journal.runId, options.journal.dir)\n}\n\n/**\n * Strip the runner-only options, leaving what `handle.process.spawn` accepts.\n *\n * `signal` is deliberately KEPT: on the UNJOURNALED path the host holds the\n * agent's stdout pipe, so a client disconnect should take the process down with\n * it. The journaled path must not forward it — see\n * {@link toJournaledSpawnOptions}.\n */\nfunction toProcessOptions(options: SpawnNdjsonOptions): ProcessOptions {\n  const { onNonJsonLine, input, journal, ...rest } = options\n  void onNonJsonLine\n  void input\n  void journal\n  return rest\n}\n\n/**\n * The journaled agent's spawn options: {@link toProcessOptions} MINUS `signal`.\n *\n * The request's signal must never reach the agent process on this path. Providers\n * DO act on it at spawn time — local-process registers it to `killTree` the\n * process group, and daytona and docker honor it too — so forwarding it means a\n * client disconnect kills the journaled agent. The agent then writes no exit\n * sentinel, and a successor host takes over a run that is already dead: the exact\n * opposite of the guarantee documented on {@link startJournaledAgent}, and of the\n * reason the journal is a file rather than a pipe.\n *\n * The signal is still honored for the READ. `readJournalNdjson` forwards it to\n * `readJournal` and `awaitAttachableJournal` on its own, so a disconnecting\n * client stops tailing immediately. Only the agent spawn outlives the request.\n */\nfunction toJournaledSpawnOptions(options: JournaledOptions): ProcessOptions {\n  const { signal, ...rest } = toProcessOptions(options)\n  void signal\n  return rest\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 * Start the agent with its stdout (and the `{\"__exit\":N}` sentinel) redirected\n * into the journal, then return.\n *\n * Deliberately does NOT wait for the process and does NOT read its stdout: the\n * whole point of journaling is that the host holds no handle on the agent's\n * output, so a host that dies mid-run cannot take the agent down with it (no\n * pipe to SIGPIPE). The spawned process is left running in the sandbox; the\n * sentinel line the wrapper appends on exit is how anyone — this host or a\n * successor — learns it finished. Stdin is still written directly to the\n * spawned process, exactly as the unjournaled path does, since that transport\n * is unaffected by where stdout goes.\n */\nexport async function startJournaledAgent(\n  handle: SandboxHandle,\n  command: string,\n  options: JournaledOptions,\n): Promise<void> {\n  const paths = resolvePaths(options)\n  const proc = await handle.process.spawn(\n    journaledCommand(command, paths),\n    toJournaledSpawnOptions(options),\n  )\n  if (options.input !== undefined) {\n    await proc.stdin.write(options.input)\n    await proc.stdin.end()\n  }\n}\n\n/** Chars of stderr attached to a non-zero-exit error, on both paths. */\nconst STDERR_ERROR_CHARS = 1000\n\nasync function* singleValue(value: string): AsyncIterable<string> {\n  yield value\n}\n\n/**\n * Read the tail of a run's stderr sidecar, for the error message only.\n *\n * Returns `''` on ANY failure — a provider whose `exec` rejects, a sidecar that\n * no longer exists, a base64 frame the provider truncated. The caller is on its\n * way to throwing the real failure (the agent's non-zero exit), and losing a\n * diagnostic suffix must never replace that error with a cleanup error. Decoding\n * is deliberately lossy: `journalStderrReadCommand` reads the LAST N bytes, so\n * byte 0 of the frame can sit mid-character.\n */\nasync function readStderrTail(\n  handle: SandboxHandle,\n  paths: JournalPaths,\n): Promise<string> {\n  try {\n    const result = await handle.process.exec(journalStderrReadCommand(paths))\n    const decoder = new TextDecoder()\n    let text = ''\n    for await (const bytes of decodeBase64Stream(singleValue(result.stdout))) {\n      text += decoder.decode(bytes, { stream: true })\n    }\n    text += decoder.decode()\n    return text.trim()\n  } catch {\n    return ''\n  }\n}\n\n/**\n * Delete a terminal run's journal. Best effort by construction: see\n * {@link journalCleanupCommand} for why a failure here cannot be allowed to fail\n * a run that has already finished.\n */\nasync function cleanupJournal(\n  handle: SandboxHandle,\n  paths: JournalPaths,\n): Promise<void> {\n  try {\n    await handle.process.exec(journalCleanupCommand(paths))\n  } catch {\n    // The sandbox may already be gone, `/tmp` may be read-only, the provider's\n    // `exec` may reject. Nothing about a completed run depends on the files\n    // still existing OR on them being gone, so there is nothing to report.\n  }\n}\n\n/**\n * Read a run's journal and yield each line parsed as JSON.\n *\n * Always reads from byte 0 — the alignment step (a later phase), not this\n * reader, decides what a client has already seen. Stops at the `{\"__exit\":N}`\n * sentinel, and throws for a non-zero N so the calling adapter's existing\n * `catch` turns it into a `RUN_ERROR`, the same observable outcome the\n * unjournaled path produces from a non-zero `wait()`. There is nothing to\n * `wait()` on here: the host holds a `tail`, not the agent process, so the\n * sentinel line IS the exit code.\n *\n * The sentinel is also what bounds journal growth: reaching it means the run is\n * terminal, and a terminal run's record is the event log, so both journal files\n * are deleted before this iterable finishes. The ordering below is load-bearing\n * and is asserted, not merely commented:\n *\n * - The sentinel is captured and the loop is `break`-ed, so the source's\n *   `finally` kills the `tail` BEFORE the `rm` runs — the reader is stopped, then\n *   its input is deleted, never the other way round.\n * - `exitCode` stays `undefined` if the journal stream ends without a sentinel.\n *   NOTHING is deleted on that path either way — the run may be mid-flight and a\n *   successor host may still need every byte — but the two causes are then\n *   separated by `options.signal.aborted`: an aborted consumer returns quietly,\n *   while a stream that died on its own (killed `tail`, destroyed sandbox, torn\n *   pipe) THROWS. Returning for both is how a truncated read used to reach the\n *   client as a normally-completing run.\n * - A non-zero sentinel deletes too. The run is terminal either way.\n * - The stderr sidecar is read BEFORE the deletion that destroys it, so a\n *   non-zero exit carries up to {@link STDERR_ERROR_CHARS} chars of the agent's\n *   own diagnostics, exactly as the unjournaled path below does. That closes the\n *   \"Known regression\" this function used to document; the read is bounded and\n *   failure-swallowing (see {@link readStderrTail}), so it cannot turn a run\n *   failure into a cleanup failure.\n *\n * On an ATTACH (`journal.attach === true`) the read is preceded by\n * {@link awaitAttachableJournal}, which fails fast for a runId the store does not\n * know or has already terminalized and otherwise waits a BOUNDED time for a live\n * run's journal to appear. Without it, an attach to a runId with no journal\n * created an empty one (`journalFollowCommand` does that deliberately) and tailed\n * it forever — no sentinel, no error, no timeout.\n *\n * One case this does NOT bound: a run that reaches its sentinel while DETACHED\n * has no host reading it, so nothing observes the sentinel and nothing here\n * runs. Sweeping those is `pruneJournals`' job (`journal-sweep.ts`): it consults\n * the run store's status for each journal it finds and deletes only the terminal\n * ones, from a cron the application schedules rather than from a run.\n */\nexport async function* readJournalNdjson(\n  handle: SandboxHandle,\n  options: JournaledOptions,\n): AsyncIterable<unknown> {\n  const paths = resolvePaths(options)\n  // ATTACH ONLY, and before the first read. `journalFollowCommand` CREATES the\n  // journal it tails, so an attach for a runId that never had one would\n  // otherwise create an empty file and tail it forever with no sentinel ever\n  // arriving. A fresh run must not be gated: its journal is created by its own\n  // `journaledCommand` spawn, which `spawnNdjson` has just issued.\n  if (options.journal.attach === true) {\n    await awaitAttachableJournal(handle, {\n      paths,\n      runId: options.journal.runId,\n      ...(options.journal.runs === undefined\n        ? {}\n        : { runs: options.journal.runs }),\n      ...(options.journal.attachWaitMs === undefined\n        ? {}\n        : { waitMs: options.journal.attachWaitMs }),\n      ...(options.signal === undefined ? {} : { signal: options.signal }),\n    })\n  }\n  let exitCode: number | undefined\n  for await (const { line } of readJournal(handle, {\n    paths,\n    fromByte: 0,\n    runId: options.journal.runId,\n    ...(options.signal === undefined ? {} : { signal: options.signal }),\n    ...(options.journal.pollIntervalMs === undefined\n      ? {}\n      : { pollIntervalMs: options.journal.pollIntervalMs }),\n    ...(options.journal.attachWaitMs === undefined\n      ? {}\n      : { firstByteTimeoutMs: options.journal.attachWaitMs }),\n  })) {\n    const trimmed = line.trim()\n    if (trimmed === '') continue\n    // The sentinel test comes FIRST and is nonce-checked, so an agent line that\n    // merely looks like a sentinel is delivered as the event it is instead of\n    // truncating the run (see `parseExitSentinel`).\n    const sentinel = parseExitSentinel(trimmed, paths)\n    if (sentinel !== null) {\n      exitCode = sentinel\n      break\n    }\n    let parsed: unknown\n    try {\n      parsed = JSON.parse(trimmed)\n    } catch {\n      options.onNonJsonLine?.(trimmed)\n      continue\n    }\n    yield parsed\n  }\n\n  // The stream ended with no sentinel. Two very different causes share this\n  // shape, and collapsing them is how a torn-down read used to be recorded as a\n  // short but SUCCESSFUL run:\n  //\n  // - The CONSUMER aborted (lease lost, client gone, host shutting down). Not a\n  //   failure and not terminal: return, having deleted nothing, because a\n  //   successor host may still need every byte. `pipeToRunLog`'s post-loop check\n  //   turns this into `'aborted'`.\n  // - The read DIED (the `tail` was killed, the sandbox was destroyed, the pipe\n  //   was torn down). The iterable ends without an error, so returning here made\n  //   the adapter emit a normally-completing but silently TRUNCATED run — in a\n  //   function whose documented job is to throw so the adapter converts it to a\n  //   `RUN_ERROR`. `signal.aborted` is what tells the two apart, and the throw\n  //   matches the shape the unjournaled path already uses for a bad exit.\n  if (exitCode === undefined) {\n    if (options.signal?.aborted === true) return\n    throw new Error(\n      `Agent journal stream for run ${options.journal.runId} ended without an exit sentinel ` +\n        `(${paths.journal}). The run was NOT observed to finish: the tail was torn down, ` +\n        `the sandbox went away, or the agent's shell died before writing its sentinel. ` +\n        `Both journal files are left in place for a successor host.`,\n    )\n  }\n\n  const stderr = exitCode === 0 ? '' : await readStderrTail(handle, paths)\n  await cleanupJournal(handle, paths)\n  if (exitCode !== 0) {\n    throw new Error(\n      `Agent process exited with code ${exitCode}` +\n        (stderr ? `: ${stderr.slice(0, STDERR_ERROR_CHARS)}` : ''),\n    )\n  }\n}\n\n/**\n * Spawn `command` in the sandbox and yield each stdout line parsed as JSON.\n *\n * Without `options.journal`, behavior is byte-identical to before: resolves\n * the spawn handle's exit via `wait()` after stdout closes; a non-zero exit\n * with no events surfaced is the adapter's concern to detect.\n *\n * With `options.journal`, the agent's stdout is redirected into an in-sandbox\n * journal (unless `journal.attach` is set, meaning a run already in flight)\n * and then read back from byte 0 — one code path for a fresh run and an\n * attach, both going through {@link readJournalNdjson}.\n */\nexport async function* spawnNdjson(\n  handle: SandboxHandle,\n  command: string,\n  options: SpawnNdjsonOptions = {},\n): AsyncIterable<unknown> {\n  if (isJournaled(options)) {\n    if (options.journal.attach !== true) {\n      await startJournaledAgent(handle, command, options)\n    }\n    yield* readJournalNdjson(handle, options)\n    return\n  }\n\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, STDERR_ERROR_CHARS)}` : ''),\n    )\n  }\n}\n"],"mappings":"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"}

package/dist/esm/sandbox.d.ts

@@ -1,6 +1,7 @@
+import { LockStore } from '@tanstack/ai/locks';
 import { SandboxFileHookEvent } from '@tanstack/ai';
+import { SandboxInstanceStore } from './instance-store.js';
 import { SandboxHandle, SandboxProvider } from './contracts.js';
-import { LockStore, SandboxStore } from './store.js';
 import { SandboxPolicy } from './policy.js';
 import { WorkspaceDefinition } from './workspace.js';
 /**
@@ -53,7 +54,7 @@ export interface SandboxEnsureContext {
     threadId: string;
     runId: string;
     /** Persistence seam; falls back to an in-memory store when absent. */
-    store?: SandboxStore;
+    store?: SandboxInstanceStore;
     /** Lock seam; falls back to an in-memory lock when absent. */
     locks?: LockStore;
     tenant?: {