@tanstack/ai-sandbox 0.2.3 → 0.3.0

package/dist/esm/shell.js

@@ -1,164 +1,203 @@
+//#region src/shell.ts
+/**
+* Parse the output of `export -p` (or `declare -x`) into a plain env map.
+* Shared by the stdin shell's `forkState` and the exec-backed shell.
+*/
 function parseExports(output) {
-  const env = {};
-  for (const line of output.split("\n")) {
-    const trimmed = line.trim();
-    const match = /^(?:declare\s+-x\s+|export\s+)([A-Za-z_][A-Za-z0-9_]*)(?:="((?:[^"\\]|\\.)*)")?$/.exec(
-      trimmed
-    );
-    if (match === null) continue;
-    const key = match[1];
-    if (key === void 0) continue;
-    const raw = match[2];
-    if (raw === void 0) continue;
-    env[key] = raw.replace(/\\(.)/g, "$1");
-  }
-  return env;
+	const env = {};
+	for (const line of output.split("\n")) {
+		const trimmed = line.trim();
+		const match = /^(?:declare\s+-x\s+|export\s+)([A-Za-z_][A-Za-z0-9_]*)(?:="((?:[^"\\]|\\.)*)")?$/.exec(trimmed);
+		if (match === null) continue;
+		const key = match[1];
+		if (key === void 0) continue;
+		const raw = match[2];
+		if (raw === void 0) continue;
+		env[key] = raw.replace(/\\(.)/g, "$1");
+	}
+	return env;
 }
+/** Default {@link BootstrapShellOptions.commandTimeoutMs} — 30 minutes. */
+var DEFAULT_COMMAND_TIMEOUT_MS = 1800 * 1e3;
+/** Race marker for the per-command deadline. A symbol cannot collide with a
+*  literal stdout line (a line of text `'timeout'` would). */
+var TIMED_OUT = Symbol("bootstrap-shell-timeout");
+/**
+* Spawn one `sh` process and return a {@link BootstrapShell} that drives it
+* via the sentinel-echo protocol.
+*
+* Protocol: for each `run(cmd)` call, we write
+*   `<cmd>; printf "\n__BSSH_<N>__ $?\n"` to stdin, then read stdout lines
+* until we see a line matching `__BSSH_<N>__ <exitCode>`. Everything before
+* that line is the command's stdout; the trailing integer is the exit code.
+* The counter `N` is a module-level monotonic integer — no Date.now / random.
+*/
 async function createBootstrapShell(handle, opts = {}) {
-  if (!handle.capabilities.writableStdin) {
-    return createExecBootstrapShell(handle, opts);
-  }
-  const proc = await handle.process.spawn("sh", { cwd: opts.cwd });
-  const lineBuffer = [];
-  let pending = [];
-  let streamDone = false;
-  async function drainStdout() {
-    let partial = "";
-    for await (const chunk of proc.stdout) {
-      partial += chunk;
-      const parts = partial.split("\n");
-      for (let i = 0; i < parts.length - 1; i++) {
-        const line = parts[i];
-        const resolver = pending.shift();
-        if (resolver !== void 0) {
-          resolver(line);
-        } else {
-          lineBuffer.push(line);
-        }
-      }
-      partial = parts[parts.length - 1];
-    }
-    if (partial.length > 0) {
-      const line = partial;
-      const resolver = pending.shift();
-      if (resolver !== void 0) {
-        resolver(line);
-      } else {
-        lineBuffer.push(line);
-      }
-    }
-    streamDone = true;
-    for (const resolver of pending) {
-      resolver("");
-    }
-    pending = [];
-  }
-  const drainPromise = drainStdout();
-  function nextLine() {
-    const buffered = lineBuffer.shift();
-    if (buffered !== void 0) {
-      return Promise.resolve(buffered);
-    }
-    if (streamDone) {
-      return Promise.resolve("");
-    }
-    return new Promise((resolve) => {
-      pending.push(resolve);
-    });
-  }
-  let counter = 0;
-  async function run(command) {
-    const id = counter;
-    counter += 1;
-    const sentinel = `__BSSH_${id}__`;
-    await proc.stdin.write(
-      `{ ${command} ; } 2>&1; printf "\\n${sentinel} $?\\n"
-`
-    );
-    const outputLines = [];
-    for (; ; ) {
-      const line = await nextLine();
-      if (line.startsWith(`${sentinel} `)) {
-        const codeStr = line.slice(sentinel.length + 1).trim();
-        const exitCode = parseInt(codeStr, 10);
-        return {
-          exitCode: Number.isFinite(exitCode) ? exitCode : 1,
-          stdout: outputLines.join("\n")
-        };
-      }
-      outputLines.push(line);
-    }
-  }
-  async function forkState() {
-    const pwdResult = await run("pwd");
-    const cwd = pwdResult.stdout.trim();
-    const exportResult = await run("export -p");
-    return { cwd, env: parseExports(exportResult.stdout) };
-  }
-  async function dispose() {
-    await proc.stdin.end();
-    await proc.kill();
-    await drainPromise;
-  }
-  return { run, forkState, dispose };
+	if (!handle.capabilities.writableStdin) return createExecBootstrapShell(handle, opts);
+	const proc = await handle.process.spawn("sh", { cwd: opts.cwd });
+	const lineBuffer = [];
+	let pending = [];
+	let streamDone = false;
+	let streamError;
+	/** Feed the stdout async-iterable into the shared line queue. */
+	async function drainStdout() {
+		let partial = "";
+		try {
+			for await (const chunk of proc.stdout) {
+				partial += chunk;
+				const parts = partial.split("\n");
+				for (let i = 0; i < parts.length - 1; i++) {
+					const line = parts[i];
+					const resolver = pending.shift();
+					if (resolver !== void 0) resolver(line);
+					else lineBuffer.push(line);
+				}
+				partial = parts[parts.length - 1];
+			}
+			if (partial.length > 0) {
+				const line = partial;
+				const resolver = pending.shift();
+				if (resolver !== void 0) resolver(line);
+				else lineBuffer.push(line);
+			}
+		} catch (error) {
+			streamError = error;
+		} finally {
+			streamDone = true;
+			for (const resolver of pending) resolver(null);
+			pending = [];
+		}
+	}
+	const drainPromise = drainStdout();
+	/** Read the next line from the shared queue, or `null` once stdout ended. */
+	function nextLine() {
+		const buffered = lineBuffer.shift();
+		if (buffered !== void 0) return Promise.resolve(buffered);
+		if (streamDone) return Promise.resolve(null);
+		return new Promise((resolve) => {
+			pending.push(resolve);
+		});
+	}
+	let counter = 0;
+	async function run(command) {
+		const id = counter;
+		counter += 1;
+		const sentinel = `__BSSH_${id}__`;
+		await proc.stdin.write(`{ ${command} ; } 2>&1; printf "\\n${sentinel} $?\\n"\n`);
+		const outputLines = [];
+		let timer;
+		const deadline = new Promise((resolve) => {
+			timer = setTimeout(() => resolve(TIMED_OUT), opts.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS);
+		});
+		try {
+			for (;;) {
+				const line = await Promise.race([nextLine(), deadline]);
+				if (line === TIMED_OUT) throw new Error(`bootstrap shell: timed out after ${opts.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS}ms waiting for the sentinel of command: ${command}`);
+				if (line === null) throw new Error(`bootstrap shell: the shell exited before the sentinel was printed; command: ${command}`, streamError === void 0 ? void 0 : { cause: streamError });
+				if (line.startsWith(`${sentinel} `)) {
+					const codeStr = line.slice(sentinel.length + 1).trim();
+					const exitCode = parseInt(codeStr, 10);
+					return {
+						exitCode: Number.isFinite(exitCode) ? exitCode : 1,
+						stdout: outputLines.join("\n")
+					};
+				}
+				outputLines.push(line);
+			}
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	async function forkState() {
+		return {
+			cwd: (await run("pwd")).stdout.trim(),
+			env: parseExports((await run("export -p")).stdout)
+		};
+	}
+	async function dispose() {
+		await proc.stdin.end();
+		await proc.kill();
+		await drainPromise;
+	}
+	return {
+		run,
+		forkState,
+		dispose
+	};
 }
+/**
+* Exec-backed {@link BootstrapShell} for providers WITHOUT a writable stdin.
+*
+* There is no persistent process to feed commands into, so persistence of `cd`
+* and exported variables is reproduced by threading state across discrete
+* {@link SandboxHandle.process.exec} calls: each `run()` executes the command in
+* the tracked cwd+env, then captures the resulting `pwd` and `export -p` (via
+* marker lines) so the NEXT command inherits any directory change or exports.
+*/
 function createExecBootstrapShell(handle, opts = {}) {
-  let cwd = opts.cwd ?? "/";
-  let env = {};
-  let counter = 0;
-  async function run(command) {
-    const id = counter;
-    counter += 1;
-    const sentinel = `__BSSH_${id}__`;
-    const script = [
-      command,
-      `__bssh_rc=$?`,
-      `printf '\\n%s %s\\n' '${sentinel}' "$__bssh_rc"`,
-      `printf '%s\\n' '${sentinel}_CWD'`,
-      `pwd`,
-      `printf '%s\\n' '${sentinel}_ENV'`,
-      `export -p`
-    ].join("\n");
-    const res = await handle.process.exec(script, { cwd, env });
-    const cmdOut = [];
-    const cwdLines = [];
-    const envLines = [];
-    let exitCode = res.exitCode;
-    let phase = "cmd";
-    for (const line of res.stdout.split("\n")) {
-      if (phase === "cmd") {
-        if (line.startsWith(`${sentinel} `)) {
-          const parsed = parseInt(line.slice(sentinel.length + 1).trim(), 10);
-          exitCode = Number.isFinite(parsed) ? parsed : res.exitCode;
-          phase = "await-cwd";
-          continue;
-        }
-        cmdOut.push(line);
-      } else if (phase === "await-cwd") {
-        if (line === `${sentinel}_CWD`) phase = "cwd";
-      } else if (phase === "cwd") {
-        if (line === `${sentinel}_ENV`) phase = "env";
-        else cwdLines.push(line);
-      } else {
-        envLines.push(line);
-      }
-    }
-    const newCwd = cwdLines.map((l) => l.trim()).filter(Boolean).pop();
-    if (newCwd) cwd = newCwd;
-    const newEnv = parseExports(envLines.join("\n"));
-    if (Object.keys(newEnv).length > 0) env = newEnv;
-    return { exitCode, stdout: cmdOut.join("\n") };
-  }
-  function forkState() {
-    return Promise.resolve({ cwd, env: { ...env } });
-  }
-  function dispose() {
-    return Promise.resolve();
-  }
-  return { run, forkState, dispose };
+	let cwd = opts.cwd ?? "/";
+	let env = {};
+	let counter = 0;
+	async function run(command) {
+		const id = counter;
+		counter += 1;
+		const sentinel = `__BSSH_${id}__`;
+		const script = [
+			command,
+			`__bssh_rc=$?`,
+			`printf '\\n%s %s\\n' '${sentinel}' "$__bssh_rc"`,
+			`printf '%s\\n' '${sentinel}_CWD'`,
+			`pwd`,
+			`printf '%s\\n' '${sentinel}_ENV'`,
+			`export -p`
+		].join("\n");
+		const res = await handle.process.exec(script, {
+			cwd,
+			env
+		});
+		const cmdOut = [];
+		const cwdLines = [];
+		const envLines = [];
+		let exitCode = res.exitCode;
+		let phase = "cmd";
+		for (const line of res.stdout.split("\n")) if (phase === "cmd") {
+			if (line.startsWith(`${sentinel} `)) {
+				const parsed = parseInt(line.slice(sentinel.length + 1).trim(), 10);
+				exitCode = Number.isFinite(parsed) ? parsed : res.exitCode;
+				phase = "await-cwd";
+				continue;
+			}
+			cmdOut.push(line);
+		} else if (phase === "await-cwd") {
+			if (line === `${sentinel}_CWD`) phase = "cwd";
+		} else if (phase === "cwd") if (line === `${sentinel}_ENV`) phase = "env";
+		else cwdLines.push(line);
+		else envLines.push(line);
+		const newCwd = cwdLines.map((l) => l.trim()).filter(Boolean).pop();
+		if (newCwd) cwd = newCwd;
+		const newEnv = parseExports(envLines.join("\n"));
+		if (Object.keys(newEnv).length > 0) env = newEnv;
+		return {
+			exitCode,
+			stdout: cmdOut.join("\n")
+		};
+	}
+	function forkState() {
+		return Promise.resolve({
+			cwd,
+			env: { ...env }
+		});
+	}
+	function dispose() {
+		return Promise.resolve();
+	}
+	return {
+		run,
+		forkState,
+		dispose
+	};
 }
-export {
-  createBootstrapShell,
-  createExecBootstrapShell
-};
-//# sourceMappingURL=shell.js.map
+//#endregion
+export { createBootstrapShell, createExecBootstrapShell };
+
+//# sourceMappingURL=shell.js.map

package/dist/esm/shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell.js","sources":["../../src/shell.ts"],"sourcesContent":["/**\n * Internal persistent bootstrap shell.\n *\n * Spawns a single `sh` process via {@link SandboxHandle.process.spawn} and\n * drives it over stdin/stdout with a sentinel-echo protocol. Commands run\n * sequentially inside the same shell so `cd`, exported variables, etc. persist\n * across calls — exactly the exec model the bootstrap setup plan needs.\n *\n * Providers WITHOUT a writable host→process stdin (`capabilities.writableStdin\n * === false`, e.g. Cloudflare / Daytona / Vercel) can't be driven over stdin, so\n * {@link createBootstrapShell} transparently falls back to an exec-backed shell\n * ({@link createExecBootstrapShell}) that threads `cwd`/env across `exec` calls\n * to reproduce the same persistent-shell semantics.\n *\n * This module is internal-only and must NOT be re-exported from\n * `packages/ai-sandbox/src/index.ts`.\n */\nimport type { SandboxHandle } from './contracts'\n\n/**\n * Parse the output of `export -p` (or `declare -x`) into a plain env map.\n * Shared by the stdin shell's `forkState` and the exec-backed shell.\n */\nfunction parseExports(output: string): Record<string, string> {\n  const env: Record<string, string> = {}\n  for (const line of output.split('\\n')) {\n    const trimmed = line.trim()\n    // Match `declare -x KEY=...` or `export KEY=...` forms.\n    const match =\n      /^(?:declare\\s+-x\\s+|export\\s+)([A-Za-z_][A-Za-z0-9_]*)(?:=\"((?:[^\"\\\\]|\\\\.)*)\")?$/.exec(\n        trimmed,\n      )\n    if (match === null) continue\n    const key = match[1]\n    if (key === undefined) continue\n    // Value may be absent for exported-but-unset vars; skip those.\n    const raw = match[2]\n    if (raw === undefined) continue\n    // Unescape backslash-escaped chars inside double quotes.\n    env[key] = raw.replace(/\\\\(.)/g, '$1')\n  }\n  return env\n}\n\n/** The surface the bootstrap engine uses. */\nexport interface BootstrapShell {\n  /** Run a shell command and capture its stdout + exit code. */\n  run: (command: string) => Promise<{ exitCode: number; stdout: string }>\n  /**\n   * Snapshot the shell's current working directory and exported environment.\n   * Used to fork parallel exec calls that inherit the serial shell's state.\n   */\n  forkState: () => Promise<{ cwd: string; env: Record<string, string> }>\n  /** End the shell session (closes stdin, kills the process). */\n  dispose: () => Promise<void>\n}\n\n/** Options for {@link createBootstrapShell}. */\nexport interface BootstrapShellOptions {\n  /** Working directory to start the shell in (passed as ProcessOptions.cwd). */\n  cwd?: string\n}\n\n/**\n * Spawn one `sh` process and return a {@link BootstrapShell} that drives it\n * via the sentinel-echo protocol.\n *\n * Protocol: for each `run(cmd)` call, we write\n *   `<cmd>; printf \"\\n__BSSH_<N>__ $?\\n\"` to stdin, then read stdout lines\n * until we see a line matching `__BSSH_<N>__ <exitCode>`. Everything before\n * that line is the command's stdout; the trailing integer is the exit code.\n * The counter `N` is a module-level monotonic integer — no Date.now / random.\n */\nexport async function createBootstrapShell(\n  handle: SandboxHandle,\n  opts: BootstrapShellOptions = {},\n): Promise<BootstrapShell> {\n  // Providers without a writable host→process stdin can't run the sentinel-echo\n  // protocol below (it feeds commands over stdin), so use the exec-backed shell.\n  if (!handle.capabilities.writableStdin) {\n    return createExecBootstrapShell(handle, opts)\n  }\n  const proc = await handle.process.spawn('sh', { cwd: opts.cwd })\n\n  /*\n   * We need to read stdout lines across multiple run() calls while keeping\n   * the iterator open. Buffer chunks into lines manually.\n   */\n  const lineBuffer: Array<string> = []\n  let pending: Array<(line: string) => void> = []\n  let streamDone = false\n\n  /** Feed the stdout async-iterable into the shared line queue. */\n  async function drainStdout(): Promise<void> {\n    let partial = ''\n    for await (const chunk of proc.stdout) {\n      partial += chunk\n      const parts = partial.split('\\n')\n      // All but the last element are complete lines.\n      for (let i = 0; i < parts.length - 1; i++) {\n        const line = parts[i] as string\n        const resolver = pending.shift()\n        if (resolver !== undefined) {\n          resolver(line)\n        } else {\n          lineBuffer.push(line)\n        }\n      }\n      partial = parts[parts.length - 1] as string\n    }\n    // Flush any trailing partial line.\n    if (partial.length > 0) {\n      const line = partial\n      const resolver = pending.shift()\n      if (resolver !== undefined) {\n        resolver(line)\n      } else {\n        lineBuffer.push(line)\n      }\n    }\n    streamDone = true\n    // Resolve any remaining waiters with an empty sentinel so they unblock.\n    for (const resolver of pending) {\n      resolver('')\n    }\n    pending = []\n  }\n\n  // Start draining immediately; do NOT await — runs concurrently.\n  const drainPromise = drainStdout()\n\n  /** Read the next line from the shared queue. */\n  function nextLine(): Promise<string> {\n    const buffered = lineBuffer.shift()\n    if (buffered !== undefined) {\n      return Promise.resolve(buffered)\n    }\n    if (streamDone) {\n      return Promise.resolve('')\n    }\n    return new Promise<string>((resolve) => {\n      pending.push(resolve)\n    })\n  }\n\n  let counter = 0\n\n  async function run(\n    command: string,\n  ): Promise<{ exitCode: number; stdout: string }> {\n    const id = counter\n    counter += 1\n    const sentinel = `__BSSH_${id}__`\n\n    // Write the command followed by a sentinel printf to stdin. Merge the\n    // command's stderr into stdout (`{ … ; } 2>&1`) so a failing setup step's\n    // error text is captured and can be surfaced — otherwise only the exit code\n    // is visible. `$?` after the group is still the command's own exit code.\n    await proc.stdin.write(\n      `{ ${command} ; } 2>&1; printf \"\\\\n${sentinel} $?\\\\n\"\\n`,\n    )\n\n    const outputLines: Array<string> = []\n\n    // Read lines until we find the sentinel.\n    for (;;) {\n      const line = await nextLine()\n      if (line.startsWith(`${sentinel} `)) {\n        const codeStr = line.slice(sentinel.length + 1).trim()\n        const exitCode = parseInt(codeStr, 10)\n        return {\n          exitCode: Number.isFinite(exitCode) ? exitCode : 1,\n          stdout: outputLines.join('\\n'),\n        }\n      }\n      outputLines.push(line)\n    }\n  }\n\n  async function forkState(): Promise<{\n    cwd: string\n    env: Record<string, string>\n  }> {\n    const pwdResult = await run('pwd')\n    const cwd = pwdResult.stdout.trim()\n\n    const exportResult = await run('export -p')\n    return { cwd, env: parseExports(exportResult.stdout) }\n  }\n\n  async function dispose(): Promise<void> {\n    await proc.stdin.end()\n    await proc.kill()\n    // Drain the stdout iterator to completion so there are no dangling promises.\n    await drainPromise\n  }\n\n  return { run, forkState, dispose }\n}\n\n/**\n * Exec-backed {@link BootstrapShell} for providers WITHOUT a writable stdin.\n *\n * There is no persistent process to feed commands into, so persistence of `cd`\n * and exported variables is reproduced by threading state across discrete\n * {@link SandboxHandle.process.exec} calls: each `run()` executes the command in\n * the tracked cwd+env, then captures the resulting `pwd` and `export -p` (via\n * marker lines) so the NEXT command inherits any directory change or exports.\n */\nexport function createExecBootstrapShell(\n  handle: SandboxHandle,\n  opts: BootstrapShellOptions = {},\n): BootstrapShell {\n  let cwd = opts.cwd ?? '/'\n  let env: Record<string, string> = {}\n  let counter = 0\n\n  async function run(\n    command: string,\n  ): Promise<{ exitCode: number; stdout: string }> {\n    const id = counter\n    counter += 1\n    const sentinel = `__BSSH_${id}__`\n\n    // Run the command, then emit its exit code, cwd and exported env behind\n    // marker lines so we can recover state even when the command itself fails\n    // (no `set -e`). Capturing `$?` immediately after the command keeps the\n    // reported exit code the command's own, not the trailing introspection's.\n    const script = [\n      command,\n      `__bssh_rc=$?`,\n      `printf '\\\\n%s %s\\\\n' '${sentinel}' \"$__bssh_rc\"`,\n      `printf '%s\\\\n' '${sentinel}_CWD'`,\n      `pwd`,\n      `printf '%s\\\\n' '${sentinel}_ENV'`,\n      `export -p`,\n    ].join('\\n')\n\n    const res = await handle.process.exec(script, { cwd, env })\n\n    const cmdOut: Array<string> = []\n    const cwdLines: Array<string> = []\n    const envLines: Array<string> = []\n    let exitCode = res.exitCode\n    let phase: 'cmd' | 'await-cwd' | 'cwd' | 'env' = 'cmd'\n\n    for (const line of res.stdout.split('\\n')) {\n      if (phase === 'cmd') {\n        if (line.startsWith(`${sentinel} `)) {\n          const parsed = parseInt(line.slice(sentinel.length + 1).trim(), 10)\n          exitCode = Number.isFinite(parsed) ? parsed : res.exitCode\n          phase = 'await-cwd'\n          continue\n        }\n        cmdOut.push(line)\n      } else if (phase === 'await-cwd') {\n        if (line === `${sentinel}_CWD`) phase = 'cwd'\n      } else if (phase === 'cwd') {\n        if (line === `${sentinel}_ENV`) phase = 'env'\n        else cwdLines.push(line)\n      } else {\n        envLines.push(line)\n      }\n    }\n\n    // `pwd` prints a single line; the last non-empty one is the new cwd.\n    const newCwd = cwdLines\n      .map((l) => l.trim())\n      .filter(Boolean)\n      .pop()\n    if (newCwd) cwd = newCwd\n    const newEnv = parseExports(envLines.join('\\n'))\n    if (Object.keys(newEnv).length > 0) env = newEnv\n\n    return { exitCode, stdout: cmdOut.join('\\n') }\n  }\n\n  function forkState(): Promise<{ cwd: string; env: Record<string, string> }> {\n    return Promise.resolve({ cwd, env: { ...env } })\n  }\n\n  function dispose(): Promise<void> {\n    // Nothing to tear down — there is no persistent process.\n    return Promise.resolve()\n  }\n\n  return { run, forkState, dispose }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"shell.js","names":[],"sources":["../../src/shell.ts"],"sourcesContent":["/**\n * Internal persistent bootstrap shell.\n *\n * Spawns a single `sh` process via {@link SandboxHandle.process.spawn} and\n * drives it over stdin/stdout with a sentinel-echo protocol. Commands run\n * sequentially inside the same shell so `cd`, exported variables, etc. persist\n * across calls — exactly the exec model the bootstrap setup plan needs.\n *\n * Providers WITHOUT a writable host→process stdin (`capabilities.writableStdin\n * === false`, e.g. Cloudflare / Daytona / Vercel) can't be driven over stdin, so\n * {@link createBootstrapShell} transparently falls back to an exec-backed shell\n * ({@link createExecBootstrapShell}) that threads `cwd`/env across `exec` calls\n * to reproduce the same persistent-shell semantics.\n *\n * This module is internal-only and must NOT be re-exported from\n * `packages/ai-sandbox/src/index.ts`.\n */\nimport type { SandboxHandle } from './contracts'\n\n/**\n * Parse the output of `export -p` (or `declare -x`) into a plain env map.\n * Shared by the stdin shell's `forkState` and the exec-backed shell.\n */\nfunction parseExports(output: string): Record<string, string> {\n  const env: Record<string, string> = {}\n  for (const line of output.split('\\n')) {\n    const trimmed = line.trim()\n    // Match `declare -x KEY=...` or `export KEY=...` forms.\n    const match =\n      /^(?:declare\\s+-x\\s+|export\\s+)([A-Za-z_][A-Za-z0-9_]*)(?:=\"((?:[^\"\\\\]|\\\\.)*)\")?$/.exec(\n        trimmed,\n      )\n    if (match === null) continue\n    const key = match[1]\n    if (key === undefined) continue\n    // Value may be absent for exported-but-unset vars; skip those.\n    const raw = match[2]\n    if (raw === undefined) continue\n    // Unescape backslash-escaped chars inside double quotes.\n    env[key] = raw.replace(/\\\\(.)/g, '$1')\n  }\n  return env\n}\n\n/** The surface the bootstrap engine uses. */\nexport interface BootstrapShell {\n  /** Run a shell command and capture its stdout + exit code. */\n  run: (command: string) => Promise<{ exitCode: number; stdout: string }>\n  /**\n   * Snapshot the shell's current working directory and exported environment.\n   * Used to fork parallel exec calls that inherit the serial shell's state.\n   */\n  forkState: () => Promise<{ cwd: string; env: Record<string, string> }>\n  /** End the shell session (closes stdin, kills the process). */\n  dispose: () => Promise<void>\n}\n\n/** Options for {@link createBootstrapShell}. */\nexport interface BootstrapShellOptions {\n  /** Working directory to start the shell in (passed as ProcessOptions.cwd). */\n  cwd?: string\n  /**\n   * Belt-and-braces deadline for a single `run()` to see its sentinel. The\n   * primary termination condition is the stdout stream ending (see\n   * {@link createBootstrapShell}); this only catches a shell that is alive,\n   * silent, and never going to answer. Generous by default because setup steps\n   * legitimately run for a long time (`npm install`, image pulls).\n   */\n  commandTimeoutMs?: number\n}\n\n/** Default {@link BootstrapShellOptions.commandTimeoutMs} — 30 minutes. */\nconst DEFAULT_COMMAND_TIMEOUT_MS = 30 * 60 * 1000\n\n/** Race marker for the per-command deadline. A symbol cannot collide with a\n *  literal stdout line (a line of text `'timeout'` would). */\nconst TIMED_OUT = Symbol('bootstrap-shell-timeout')\n\n/**\n * Spawn one `sh` process and return a {@link BootstrapShell} that drives it\n * via the sentinel-echo protocol.\n *\n * Protocol: for each `run(cmd)` call, we write\n *   `<cmd>; printf \"\\n__BSSH_<N>__ $?\\n\"` to stdin, then read stdout lines\n * until we see a line matching `__BSSH_<N>__ <exitCode>`. Everything before\n * that line is the command's stdout; the trailing integer is the exit code.\n * The counter `N` is a module-level monotonic integer — no Date.now / random.\n */\nexport async function createBootstrapShell(\n  handle: SandboxHandle,\n  opts: BootstrapShellOptions = {},\n): Promise<BootstrapShell> {\n  // Providers without a writable host→process stdin can't run the sentinel-echo\n  // protocol below (it feeds commands over stdin), so use the exec-backed shell.\n  if (!handle.capabilities.writableStdin) {\n    return createExecBootstrapShell(handle, opts)\n  }\n  const proc = await handle.process.spawn('sh', { cwd: opts.cwd })\n\n  /*\n   * We need to read stdout lines across multiple run() calls while keeping\n   * the iterator open. Buffer chunks into lines manually.\n   */\n  const lineBuffer: Array<string> = []\n  // `null` means \"the stdout stream ended\" — distinct from an empty line, which\n  // `sh` emits constantly. Collapsing the two is what let a dead shell feed an\n  // infinite supply of `''` into a sentinel-hunting loop.\n  let pending: Array<(line: string | null) => void> = []\n  let streamDone = false\n  let streamError: unknown\n\n  /** Feed the stdout async-iterable into the shared line queue. */\n  async function drainStdout(): Promise<void> {\n    let partial = ''\n    try {\n      for await (const chunk of proc.stdout) {\n        partial += chunk\n        const parts = partial.split('\\n')\n        // All but the last element are complete lines.\n        for (let i = 0; i < parts.length - 1; i++) {\n          const line = parts[i] as string\n          const resolver = pending.shift()\n          if (resolver !== undefined) {\n            resolver(line)\n          } else {\n            lineBuffer.push(line)\n          }\n        }\n        partial = parts[parts.length - 1] as string\n      }\n      // Flush any trailing partial line.\n      if (partial.length > 0) {\n        const line = partial\n        const resolver = pending.shift()\n        if (resolver !== undefined) {\n          resolver(line)\n        } else {\n          lineBuffer.push(line)\n        }\n      }\n    } catch (error) {\n      // A throw while iterating stdout (transport reset, provider stream error)\n      // must NOT leave waiters parked on a promise nobody resolves. Record it so\n      // `run()` can name the cause, and fall through to the `finally` that\n      // unblocks everyone.\n      streamError = error\n    } finally {\n      streamDone = true\n      // Unblock any remaining waiters with the end-of-stream marker.\n      for (const resolver of pending) {\n        resolver(null)\n      }\n      pending = []\n    }\n  }\n\n  /*\n   * Start draining immediately; do NOT await — runs concurrently. The `try/catch`\n   * inside `drainStdout` means this promise never rejects, so there is no\n   * unhandled rejection while nothing is awaiting it, and `dispose()` can await\n   * it unconditionally.\n   */\n  const drainPromise = drainStdout()\n\n  /** Read the next line from the shared queue, or `null` once stdout ended. */\n  function nextLine(): Promise<string | null> {\n    const buffered = lineBuffer.shift()\n    if (buffered !== undefined) {\n      return Promise.resolve(buffered)\n    }\n    if (streamDone) {\n      return Promise.resolve(null)\n    }\n    return new Promise<string | null>((resolve) => {\n      pending.push(resolve)\n    })\n  }\n\n  let counter = 0\n\n  async function run(\n    command: string,\n  ): Promise<{ exitCode: number; stdout: string }> {\n    const id = counter\n    counter += 1\n    const sentinel = `__BSSH_${id}__`\n\n    // Write the command followed by a sentinel printf to stdin. Merge the\n    // command's stderr into stdout (`{ … ; } 2>&1`) so a failing setup step's\n    // error text is captured and can be surfaced — otherwise only the exit code\n    // is visible. `$?` after the group is still the command's own exit code.\n    await proc.stdin.write(\n      `{ ${command} ; } 2>&1; printf \"\\\\n${sentinel} $?\\\\n\"\\n`,\n    )\n\n    const outputLines: Array<string> = []\n\n    /*\n     * Read lines until we find the sentinel — but the wait MUST be able to end\n     * without one. `sh` can exit before it ever prints the sentinel (a missing\n     * binary, an OOM kill, the provider reaping the sandbox mid-bootstrap), and\n     * a loop whose only exit is the sentinel then spins on end-of-stream\n     * forever, pushing into `outputLines` until the host process dies of memory\n     * exhaustion. Two independent terminators:\n     *   1. `nextLine()` yields `null` the moment stdout is done — the real fix,\n     *      it fires as soon as the shell is gone.\n     *   2. A deadline, for a shell that stays alive and simply never answers.\n     */\n    let timer: ReturnType<typeof setTimeout> | undefined\n    const deadline = new Promise<typeof TIMED_OUT>((resolve) => {\n      timer = setTimeout(\n        () => resolve(TIMED_OUT),\n        opts.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS,\n      )\n    })\n\n    try {\n      for (;;) {\n        const line = await Promise.race([nextLine(), deadline])\n        if (line === TIMED_OUT) {\n          throw new Error(\n            `bootstrap shell: timed out after ${\n              opts.commandTimeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS\n            }ms waiting for the sentinel of command: ${command}`,\n          )\n        }\n        if (line === null) {\n          throw new Error(\n            `bootstrap shell: the shell exited before the sentinel was printed; command: ${command}`,\n            streamError === undefined ? undefined : { cause: streamError },\n          )\n        }\n        if (line.startsWith(`${sentinel} `)) {\n          const codeStr = line.slice(sentinel.length + 1).trim()\n          const exitCode = parseInt(codeStr, 10)\n          return {\n            exitCode: Number.isFinite(exitCode) ? exitCode : 1,\n            stdout: outputLines.join('\\n'),\n          }\n        }\n        outputLines.push(line)\n      }\n    } finally {\n      clearTimeout(timer)\n    }\n  }\n\n  async function forkState(): Promise<{\n    cwd: string\n    env: Record<string, string>\n  }> {\n    const pwdResult = await run('pwd')\n    const cwd = pwdResult.stdout.trim()\n\n    const exportResult = await run('export -p')\n    return { cwd, env: parseExports(exportResult.stdout) }\n  }\n\n  async function dispose(): Promise<void> {\n    await proc.stdin.end()\n    await proc.kill()\n    // Drain the stdout iterator to completion so there are no dangling promises.\n    await drainPromise\n  }\n\n  return { run, forkState, dispose }\n}\n\n/**\n * Exec-backed {@link BootstrapShell} for providers WITHOUT a writable stdin.\n *\n * There is no persistent process to feed commands into, so persistence of `cd`\n * and exported variables is reproduced by threading state across discrete\n * {@link SandboxHandle.process.exec} calls: each `run()` executes the command in\n * the tracked cwd+env, then captures the resulting `pwd` and `export -p` (via\n * marker lines) so the NEXT command inherits any directory change or exports.\n */\nexport function createExecBootstrapShell(\n  handle: SandboxHandle,\n  opts: BootstrapShellOptions = {},\n): BootstrapShell {\n  let cwd = opts.cwd ?? '/'\n  let env: Record<string, string> = {}\n  let counter = 0\n\n  async function run(\n    command: string,\n  ): Promise<{ exitCode: number; stdout: string }> {\n    const id = counter\n    counter += 1\n    const sentinel = `__BSSH_${id}__`\n\n    // Run the command, then emit its exit code, cwd and exported env behind\n    // marker lines so we can recover state even when the command itself fails\n    // (no `set -e`). Capturing `$?` immediately after the command keeps the\n    // reported exit code the command's own, not the trailing introspection's.\n    const script = [\n      command,\n      `__bssh_rc=$?`,\n      `printf '\\\\n%s %s\\\\n' '${sentinel}' \"$__bssh_rc\"`,\n      `printf '%s\\\\n' '${sentinel}_CWD'`,\n      `pwd`,\n      `printf '%s\\\\n' '${sentinel}_ENV'`,\n      `export -p`,\n    ].join('\\n')\n\n    const res = await handle.process.exec(script, { cwd, env })\n\n    const cmdOut: Array<string> = []\n    const cwdLines: Array<string> = []\n    const envLines: Array<string> = []\n    let exitCode = res.exitCode\n    let phase: 'cmd' | 'await-cwd' | 'cwd' | 'env' = 'cmd'\n\n    for (const line of res.stdout.split('\\n')) {\n      if (phase === 'cmd') {\n        if (line.startsWith(`${sentinel} `)) {\n          const parsed = parseInt(line.slice(sentinel.length + 1).trim(), 10)\n          exitCode = Number.isFinite(parsed) ? parsed : res.exitCode\n          phase = 'await-cwd'\n          continue\n        }\n        cmdOut.push(line)\n      } else if (phase === 'await-cwd') {\n        if (line === `${sentinel}_CWD`) phase = 'cwd'\n      } else if (phase === 'cwd') {\n        if (line === `${sentinel}_ENV`) phase = 'env'\n        else cwdLines.push(line)\n      } else {\n        envLines.push(line)\n      }\n    }\n\n    // `pwd` prints a single line; the last non-empty one is the new cwd.\n    const newCwd = cwdLines\n      .map((l) => l.trim())\n      .filter(Boolean)\n      .pop()\n    if (newCwd) cwd = newCwd\n    const newEnv = parseExports(envLines.join('\\n'))\n    if (Object.keys(newEnv).length > 0) env = newEnv\n\n    return { exitCode, stdout: cmdOut.join('\\n') }\n  }\n\n  function forkState(): Promise<{ cwd: string; env: Record<string, string> }> {\n    return Promise.resolve({ cwd, env: { ...env } })\n  }\n\n  function dispose(): Promise<void> {\n    // Nothing to tear down — there is no persistent process.\n    return Promise.resolve()\n  }\n\n  return { run, forkState, dispose }\n}\n"],"mappings":"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"}

package/dist/esm/testkit/conformance.d.ts

@@ -0,0 +1,16 @@
+import { SandboxInstanceStore } from '../instance-store.js';
+export { runJournalConformance } from './journal-conformance.js';
+export type { JournalConformanceConfig } from './journal-conformance.js';
+export { runTakeoverConformance } from './takeover-conformance.js';
+export type { TakeoverConformanceConfig } from './takeover-conformance.js';
+export { runReaperConformance } from './reaper-conformance.js';
+export type { ReaperConformanceConfig } from './reaper-conformance.js';
+export { runDurableRunFieldsConformance } from './durable-run-fields-conformance.js';
+export type { MakeRunStore } from './durable-run-fields-conformance.js';
+export { makeFakeShellSpawn } from './shell-spawn.js';
+/**
+ * Assert `makeStore()` produces a spec-compliant {@link SandboxInstanceStore}. Each
+ * `it` gets a fresh store, so implementations may share process state across
+ * calls without cross-test bleed only if `makeStore` returns an isolated store.
+ */
+export declare function runSandboxInstanceStoreConformance(name: string, makeStore: () => SandboxInstanceStore | Promise<SandboxInstanceStore>): void;

package/dist/esm/testkit/conformance.js

@@ -0,0 +1,97 @@
+import { runJournalConformance } from "./journal-conformance.js";
+import { runTakeoverConformance } from "./takeover-conformance.js";
+import { runReaperConformance } from "./reaper-conformance.js";
+import { runDurableRunFieldsConformance } from "./durable-run-fields-conformance.js";
+import { makeFakeShellSpawn } from "./shell-spawn.js";
+import { describe, expect, it } from "vitest";
+//#region src/testkit/conformance.ts
+/**
+* Conformance suite for a {@link SandboxInstanceStore} implementation.
+*
+* Run this against a fresh BYO store (or the in-memory reference) to prove it
+* satisfies the get / upsert / delete contract `@tanstack/ai-sandbox`'s ensure
+* algorithm relies on — including insert-vs-overwrite and optional-field
+* handling (full replace must clear omitted optionals).
+*
+* Vitest is an OPTIONAL peer dependency: this module is imported only from test
+* files, which already run under Vitest.
+*/
+function makeRecord(overrides) {
+	return {
+		key: "thread-1",
+		provider: "fake",
+		providerSandboxId: "sb-1",
+		threadId: "thread-1",
+		updatedAt: 1,
+		...overrides
+	};
+}
+/**
+* Assert `makeStore()` produces a spec-compliant {@link SandboxInstanceStore}. Each
+* `it` gets a fresh store, so implementations may share process state across
+* calls without cross-test bleed only if `makeStore` returns an isolated store.
+*/
+function runSandboxInstanceStoreConformance(name, makeStore) {
+	describe(`SandboxInstanceStore conformance: ${name}`, () => {
+		it("returns null for a missing key", async () => {
+			expect(await (await makeStore()).get("absent")).toBeNull();
+		});
+		it("round-trips an upserted record with all fields", async () => {
+			const store = await makeStore();
+			const record = makeRecord({
+				latestSnapshotId: "snap-1",
+				latestRunId: "run-1"
+			});
+			await store.upsert(record);
+			expect(await store.get(record.key)).toEqual(record);
+		});
+		it("omits absent optional fields on read", async () => {
+			const store = await makeStore();
+			const record = makeRecord();
+			await store.upsert(record);
+			const loaded = await store.get(record.key);
+			expect(loaded).toEqual(record);
+			expect(loaded && "latestSnapshotId" in loaded).toBe(false);
+			expect(loaded && "latestRunId" in loaded).toBe(false);
+		});
+		it("overwrites an existing record on re-upsert", async () => {
+			const store = await makeStore();
+			await store.upsert(makeRecord({ latestSnapshotId: "snap-1" }));
+			await store.upsert(makeRecord({
+				providerSandboxId: "sb-2",
+				updatedAt: 2
+			}));
+			const loaded = await store.get("thread-1");
+			expect(loaded?.providerSandboxId).toBe("sb-2");
+			expect(loaded?.updatedAt).toBe(2);
+			expect(loaded && "latestSnapshotId" in loaded).toBe(false);
+		});
+		it("isolates records by key", async () => {
+			const store = await makeStore();
+			await store.upsert(makeRecord({
+				key: "a",
+				threadId: "a"
+			}));
+			await store.upsert(makeRecord({
+				key: "b",
+				threadId: "b",
+				providerSandboxId: "sb-b"
+			}));
+			expect((await store.get("a"))?.providerSandboxId).toBe("sb-1");
+			expect((await store.get("b"))?.providerSandboxId).toBe("sb-b");
+		});
+		it("deletes a record", async () => {
+			const store = await makeStore();
+			await store.upsert(makeRecord());
+			await store.delete("thread-1");
+			expect(await store.get("thread-1")).toBeNull();
+		});
+		it("delete of a missing key is a no-op", async () => {
+			await expect((await makeStore()).delete("absent")).resolves.toBeUndefined();
+		});
+	});
+}
+//#endregion
+export { makeFakeShellSpawn, runDurableRunFieldsConformance, runJournalConformance, runReaperConformance, runSandboxInstanceStoreConformance, runTakeoverConformance };
+
+//# sourceMappingURL=conformance.js.map

package/dist/esm/testkit/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","names":[],"sources":["../../../src/testkit/conformance.ts"],"sourcesContent":["/**\n * Conformance suite for a {@link SandboxInstanceStore} implementation.\n *\n * Run this against a fresh BYO store (or the in-memory reference) to prove it\n * satisfies the get / upsert / delete contract `@tanstack/ai-sandbox`'s ensure\n * algorithm relies on — including insert-vs-overwrite and optional-field\n * handling (full replace must clear omitted optionals).\n *\n * Vitest is an OPTIONAL peer dependency: this module is imported only from test\n * files, which already run under Vitest.\n */\nimport { describe, expect, it } from 'vitest'\nimport type {\n  SandboxInstanceRecord,\n  SandboxInstanceStore,\n} from '../instance-store'\n\n// The `./testkit` package.json subpath resolves to THIS module's build output\n// only (`dist/esm/testkit/conformance.js`), not a barrel over `src/testkit/`.\n// Re-export the journal, takeover, and reaper conformance suites here so they\n// are reachable from `@tanstack/ai-sandbox/testkit` without changing that\n// mapping.\nexport { runJournalConformance } from './journal-conformance'\nexport type { JournalConformanceConfig } from './journal-conformance'\nexport { runTakeoverConformance } from './takeover-conformance'\nexport type { TakeoverConformanceConfig } from './takeover-conformance'\nexport { runReaperConformance } from './reaper-conformance'\nexport type { ReaperConformanceConfig } from './reaper-conformance'\nexport { runDurableRunFieldsConformance } from './durable-run-fields-conformance'\nexport type { MakeRunStore } from './durable-run-fields-conformance'\nexport { makeFakeShellSpawn } from './shell-spawn'\n\nfunction makeRecord(\n  overrides?: Partial<SandboxInstanceRecord>,\n): SandboxInstanceRecord {\n  return {\n    key: 'thread-1',\n    provider: 'fake',\n    providerSandboxId: 'sb-1',\n    threadId: 'thread-1',\n    updatedAt: 1,\n    ...overrides,\n  }\n}\n\n/**\n * Assert `makeStore()` produces a spec-compliant {@link SandboxInstanceStore}. Each\n * `it` gets a fresh store, so implementations may share process state across\n * calls without cross-test bleed only if `makeStore` returns an isolated store.\n */\nexport function runSandboxInstanceStoreConformance(\n  name: string,\n  makeStore: () => SandboxInstanceStore | Promise<SandboxInstanceStore>,\n): void {\n  describe(`SandboxInstanceStore conformance: ${name}`, () => {\n    it('returns null for a missing key', async () => {\n      const store = await makeStore()\n      expect(await store.get('absent')).toBeNull()\n    })\n\n    it('round-trips an upserted record with all fields', async () => {\n      const store = await makeStore()\n      const record = makeRecord({\n        latestSnapshotId: 'snap-1',\n        latestRunId: 'run-1',\n      })\n      await store.upsert(record)\n      expect(await store.get(record.key)).toEqual(record)\n    })\n\n    it('omits absent optional fields on read', async () => {\n      const store = await makeStore()\n      const record = makeRecord()\n      await store.upsert(record)\n      const loaded = await store.get(record.key)\n      expect(loaded).toEqual(record)\n      expect(loaded && 'latestSnapshotId' in loaded).toBe(false)\n      expect(loaded && 'latestRunId' in loaded).toBe(false)\n    })\n\n    it('overwrites an existing record on re-upsert', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord({ latestSnapshotId: 'snap-1' }))\n      await store.upsert(\n        makeRecord({ providerSandboxId: 'sb-2', updatedAt: 2 }),\n      )\n      const loaded = await store.get('thread-1')\n      expect(loaded?.providerSandboxId).toBe('sb-2')\n      expect(loaded?.updatedAt).toBe(2)\n      // The overwrite dropped latestSnapshotId — a durable store must clear it,\n      // not retain the prior value.\n      expect(loaded && 'latestSnapshotId' in loaded).toBe(false)\n    })\n\n    it('isolates records by key', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord({ key: 'a', threadId: 'a' }))\n      await store.upsert(\n        makeRecord({ key: 'b', threadId: 'b', providerSandboxId: 'sb-b' }),\n      )\n      expect((await store.get('a'))?.providerSandboxId).toBe('sb-1')\n      expect((await store.get('b'))?.providerSandboxId).toBe('sb-b')\n    })\n\n    it('deletes a record', async () => {\n      const store = await makeStore()\n      await store.upsert(makeRecord())\n      await store.delete('thread-1')\n      expect(await store.get('thread-1')).toBeNull()\n    })\n\n    it('delete of a missing key is a no-op', async () => {\n      const store = await makeStore()\n      await expect(store.delete('absent')).resolves.toBeUndefined()\n    })\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAgCA,SAAS,WACP,WACuB;CACvB,OAAO;EACL,KAAK;EACL,UAAU;EACV,mBAAmB;EACnB,UAAU;EACV,WAAW;EACX,GAAG;CACL;AACF;;;;;;AAOA,SAAgB,mCACd,MACA,WACM;CACN,SAAS,qCAAqC,cAAc;EAC1D,GAAG,kCAAkC,YAAY;GAE/C,OAAO,OAAM,MADO,UAAU,EAAA,CACX,IAAI,QAAQ,CAAC,CAAC,CAAC,SAAS;EAC7C,CAAC;EAED,GAAG,kDAAkD,YAAY;GAC/D,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,SAAS,WAAW;IACxB,kBAAkB;IAClB,aAAa;GACf,CAAC;GACD,MAAM,MAAM,OAAO,MAAM;GACzB,OAAO,MAAM,MAAM,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,QAAQ,MAAM;EACpD,CAAC;EAED,GAAG,wCAAwC,YAAY;GACrD,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,SAAS,WAAW;GAC1B,MAAM,MAAM,OAAO,MAAM;GACzB,MAAM,SAAS,MAAM,MAAM,IAAI,OAAO,GAAG;GACzC,OAAO,MAAM,CAAC,CAAC,QAAQ,MAAM;GAC7B,OAAO,UAAU,sBAAsB,MAAM,CAAC,CAAC,KAAK,KAAK;GACzD,OAAO,UAAU,iBAAiB,MAAM,CAAC,CAAC,KAAK,KAAK;EACtD,CAAC;EAED,GAAG,8CAA8C,YAAY;GAC3D,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW,EAAE,kBAAkB,SAAS,CAAC,CAAC;GAC7D,MAAM,MAAM,OACV,WAAW;IAAE,mBAAmB;IAAQ,WAAW;GAAE,CAAC,CACxD;GACA,MAAM,SAAS,MAAM,MAAM,IAAI,UAAU;GACzC,OAAO,QAAQ,iBAAiB,CAAC,CAAC,KAAK,MAAM;GAC7C,OAAO,QAAQ,SAAS,CAAC,CAAC,KAAK,CAAC;GAGhC,OAAO,UAAU,sBAAsB,MAAM,CAAC,CAAC,KAAK,KAAK;EAC3D,CAAC;EAED,GAAG,2BAA2B,YAAY;GACxC,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW;IAAE,KAAK;IAAK,UAAU;GAAI,CAAC,CAAC;GAC1D,MAAM,MAAM,OACV,WAAW;IAAE,KAAK;IAAK,UAAU;IAAK,mBAAmB;GAAO,CAAC,CACnE;GACA,QAAQ,MAAM,MAAM,IAAI,GAAG,EAAA,EAAI,iBAAiB,CAAC,CAAC,KAAK,MAAM;GAC7D,QAAQ,MAAM,MAAM,IAAI,GAAG,EAAA,EAAI,iBAAiB,CAAC,CAAC,KAAK,MAAM;EAC/D,CAAC;EAED,GAAG,oBAAoB,YAAY;GACjC,MAAM,QAAQ,MAAM,UAAU;GAC9B,MAAM,MAAM,OAAO,WAAW,CAAC;GAC/B,MAAM,MAAM,OAAO,UAAU;GAC7B,OAAO,MAAM,MAAM,IAAI,UAAU,CAAC,CAAC,CAAC,SAAS;EAC/C,CAAC;EAED,GAAG,sCAAsC,YAAY;GAEnD,MAAM,QAAO,MADO,UAAU,EAAA,CACX,OAAO,QAAQ,CAAC,CAAC,CAAC,SAAS,cAAc;EAC9D,CAAC;CACH,CAAC;AACH"}

package/dist/esm/testkit/durable-run-fields-conformance.d.ts

@@ -0,0 +1,4 @@
+import { RunStore } from '@tanstack/ai';
+/** Factory for the store under test. A fresh one per case keeps them isolated. */
+export type MakeRunStore = () => RunStore | Promise<RunStore>;
+export declare function runDurableRunFieldsConformance(name: string, makeStore: MakeRunStore): void;