@tanstack/ai-sandbox 0.2.4 → 0.3.0

package/dist/esm/sandbox.js

@@ -1,128 +1,144 @@
-import { bootstrapWorkspace } from "./bootstrap.js";
-import { resolveAllSecrets } from "./secrets.js";
+import { InMemorySandboxInstanceStore } from "./instance-store.js";
 import { computeSandboxKey } from "./key.js";
-import { InMemorySandboxStore, InMemoryLockStore } from "./store.js";
+import { resolveAllSecrets } from "./secrets.js";
+import { bootstrapWorkspace } from "./bootstrap.js";
+import { InMemoryLockStore } from "@tanstack/ai/locks";
+//#region src/sandbox.ts
+/**
+* `defineSandbox()` returns a LAZY controller — it never creates a sandbox at
+* definition time. `withSandbox()` (and advanced users) call `ensure()` to
+* resume-or-create, following: provider.resume → provider.restoreSnapshot →
+* create + bootstrap. The controller folds provider/workspace/policy/lifecycle
+* into a stable instance key and coordinates through the (optional) lock +
+* sandbox stores.
+*/
+/**
+* Parse a human-readable duration string into milliseconds.
+* Supports `'<n>h'` (hours) and `'<n>m'` (minutes).
+* Returns `undefined` when the input is undefined or the format is unrecognised.
+*/
 function parseMaxAgeMs(value) {
-  if (value === void 0) return void 0;
-  const hourMatch = /^(\d+)h$/.exec(value);
-  if (hourMatch) return Number(hourMatch[1]) * 60 * 60 * 1e3;
-  const minuteMatch = /^(\d+)m$/.exec(value);
-  if (minuteMatch) return Number(minuteMatch[1]) * 60 * 1e3;
-  return void 0;
+	if (value === void 0) return void 0;
+	const hourMatch = /^(\d+)h$/.exec(value);
+	if (hourMatch) return Number(hourMatch[1]) * 60 * 60 * 1e3;
+	const minuteMatch = /^(\d+)m$/.exec(value);
+	if (minuteMatch) return Number(minuteMatch[1]) * 60 * 1e3;
 }
-const fallbackStore = new InMemorySandboxStore();
-const fallbackLocks = new InMemoryLockStore();
+/**
+* Bound for the unfenced teardown `destroy` call (see `destroy` below). Long
+* enough that a slow provider API still completes, short enough that a wedged
+* one cannot pin the process forever.
+*/
+var DESTROY_TIMEOUT_MS = 60 * 1e3;
+var fallbackStore = new InMemorySandboxInstanceStore();
+var fallbackLocks = new InMemoryLockStore();
 function defineSandbox(config) {
-  const keyInputFor = (ctx) => ({
-    threadId: config.lifecycle?.reuse === "none" ? `${ctx.threadId}:${ctx.runId}` : ctx.threadId,
-    sandboxId: config.id,
-    providerName: config.provider.name,
-    workspace: config.workspace,
-    tenant: ctx.tenant
-  });
-  const ensure = async (ctx) => {
-    const store = ctx.store ?? fallbackStore;
-    const locks = ctx.locks ?? fallbackLocks;
-    const key = computeSandboxKey(keyInputFor(ctx));
-    const caps = config.provider.capabilities();
-    return locks.withLock(`sandbox:${key}`, async () => {
-      const effectiveSnapshot = config.lifecycle?.snapshot ?? (caps.snapshots ? "after-setup" : "none");
-      const maxAgeMs = parseMaxAgeMs(config.lifecycle?.snapshotMaxAge);
-      const existing = await store.get(key);
-      if (existing) {
-        const tooOld = maxAgeMs !== void 0 && Date.now() - existing.updatedAt > maxAgeMs;
-        if (!tooOld) {
-          const resumed = await config.provider.resume({
-            id: existing.providerSandboxId,
-            signal: ctx.signal
-          });
-          if (resumed) {
-            await store.upsert({
-              ...existing,
-              latestRunId: ctx.runId,
-              updatedAt: Date.now()
-            });
-            return resumed;
-          }
-          if (existing.latestSnapshotId && caps.snapshots && config.provider.restoreSnapshot) {
-            const restored = await config.provider.restoreSnapshot({
-              snapshotId: existing.latestSnapshotId,
-              workspace: config.workspace,
-              policy: config.policy,
-              env: config.workspace?.secrets !== void 0 ? resolveAllSecrets(config.workspace.secrets) : void 0,
-              signal: ctx.signal
-            });
-            await store.upsert({
-              ...existing,
-              providerSandboxId: restored.id,
-              latestRunId: ctx.runId,
-              updatedAt: Date.now()
-            });
-            return restored;
-          }
-        }
-      }
-      const created = await config.provider.create({
-        // Deterministic id so consumers can reconstruct the provider sandbox
-        // address from run context (not just from the store record).
-        id: key,
-        workspace: config.workspace,
-        policy: config.policy,
-        env: config.workspace?.secrets !== void 0 ? resolveAllSecrets(config.workspace.secrets) : void 0,
-        signal: ctx.signal
-      });
-      if (config.workspace) {
-        try {
-          await bootstrapWorkspace(created, config.workspace, {
-            signal: ctx.signal
-          });
-        } catch (error) {
-          await created.destroy().catch(() => {
-          });
-          throw error;
-        }
-      }
-      let latestSnapshotId;
-      if (effectiveSnapshot === "after-setup" && caps.snapshots && created.snapshot) {
-        latestSnapshotId = (await created.snapshot("after-setup")).id;
-      }
-      await store.upsert({
-        key,
-        provider: config.provider.name,
-        providerSandboxId: created.id,
-        latestSnapshotId,
-        threadId: ctx.threadId,
-        latestRunId: ctx.runId,
-        updatedAt: Date.now()
-      });
-      return created;
-    });
-  };
-  const destroy = async (ctx) => {
-    const store = ctx.store ?? fallbackStore;
-    const key = computeSandboxKey(keyInputFor(ctx));
-    const existing = await store.get(key);
-    if (!existing) return;
-    await config.provider.destroy({
-      id: existing.providerSandboxId,
-      signal: ctx.signal
-    });
-    await store.delete(key);
-  };
-  return {
-    id: config.id,
-    provider: config.provider,
-    workspace: config.workspace,
-    policy: config.policy,
-    lifecycle: config.lifecycle,
-    hooks: config.hooks,
-    fileEvents: config.fileEvents,
-    key: (ctx) => computeSandboxKey(keyInputFor(ctx)),
-    ensure,
-    destroy
-  };
+	const keyInputFor = (ctx) => ({
+		threadId: config.lifecycle?.reuse === "none" ? `${ctx.threadId}:${ctx.runId}` : ctx.threadId,
+		sandboxId: config.id,
+		providerName: config.provider.name,
+		workspace: config.workspace,
+		tenant: ctx.tenant
+	});
+	const ensure = async (ctx) => {
+		const store = ctx.store ?? fallbackStore;
+		const locks = ctx.locks ?? fallbackLocks;
+		const key = computeSandboxKey(keyInputFor(ctx));
+		const caps = config.provider.capabilities();
+		return locks.withLock(`sandbox:${key}`, async () => {
+			const effectiveSnapshot = config.lifecycle?.snapshot ?? (caps.snapshots ? "after-setup" : "none");
+			const maxAgeMs = parseMaxAgeMs(config.lifecycle?.snapshotMaxAge);
+			const existing = await store.get(key);
+			if (existing) {
+				if (!(maxAgeMs !== void 0 && Date.now() - existing.updatedAt > maxAgeMs)) {
+					const resumed = await config.provider.resume({
+						id: existing.providerSandboxId,
+						signal: ctx.signal
+					});
+					if (resumed) {
+						await store.upsert({
+							...existing,
+							latestRunId: ctx.runId,
+							updatedAt: Date.now()
+						});
+						return resumed;
+					}
+					if (existing.latestSnapshotId && caps.snapshots && config.provider.restoreSnapshot) {
+						const restored = await config.provider.restoreSnapshot({
+							snapshotId: existing.latestSnapshotId,
+							workspace: config.workspace,
+							policy: config.policy,
+							env: config.workspace?.secrets !== void 0 ? resolveAllSecrets(config.workspace.secrets) : void 0,
+							signal: ctx.signal
+						});
+						await store.upsert({
+							...existing,
+							providerSandboxId: restored.id,
+							latestRunId: ctx.runId,
+							updatedAt: Date.now()
+						});
+						return restored;
+					}
+				}
+			}
+			const created = await config.provider.create({
+				id: key,
+				workspace: config.workspace,
+				policy: config.policy,
+				env: config.workspace?.secrets !== void 0 ? resolveAllSecrets(config.workspace.secrets) : void 0,
+				signal: ctx.signal
+			});
+			if (config.workspace) try {
+				await bootstrapWorkspace(created, config.workspace, { signal: ctx.signal });
+			} catch (error) {
+				await created.destroy().catch(() => {});
+				throw error;
+			}
+			let latestSnapshotId;
+			if (effectiveSnapshot === "after-setup" && caps.snapshots && created.snapshot) latestSnapshotId = (await created.snapshot("after-setup")).id;
+			await store.upsert({
+				key,
+				provider: config.provider.name,
+				providerSandboxId: created.id,
+				latestSnapshotId,
+				threadId: ctx.threadId,
+				latestRunId: ctx.runId,
+				updatedAt: Date.now()
+			});
+			return created;
+		});
+	};
+	const destroy = async (ctx) => {
+		const store = ctx.store ?? fallbackStore;
+		const key = computeSandboxKey(keyInputFor(ctx));
+		const existing = await store.get(key);
+		if (!existing) return;
+		const teardown = new AbortController();
+		const timer = setTimeout(() => teardown.abort(), DESTROY_TIMEOUT_MS);
+		try {
+			await config.provider.destroy({
+				id: existing.providerSandboxId,
+				signal: teardown.signal
+			});
+		} finally {
+			clearTimeout(timer);
+		}
+		await store.delete(key);
+	};
+	return {
+		id: config.id,
+		provider: config.provider,
+		workspace: config.workspace,
+		policy: config.policy,
+		lifecycle: config.lifecycle,
+		hooks: config.hooks,
+		fileEvents: config.fileEvents,
+		key: (ctx) => computeSandboxKey(keyInputFor(ctx)),
+		ensure,
+		destroy
+	};
 }
-export {
-  defineSandbox
-};
-//# sourceMappingURL=sandbox.js.map
+//#endregion
+export { defineSandbox };
+
+//# sourceMappingURL=sandbox.js.map

package/dist/esm/sandbox.js.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox.js","sources":["../../src/sandbox.ts"],"sourcesContent":["/**\n * `defineSandbox()` returns a LAZY controller — it never creates a sandbox at\n * definition time. `withSandbox()` (and advanced users) call `ensure()` to\n * resume-or-create, following: provider.resume → provider.restoreSnapshot →\n * create + bootstrap. The controller folds provider/workspace/policy/lifecycle\n * into a stable instance key and coordinates through the (optional) lock +\n * sandbox stores.\n */\nimport { bootstrapWorkspace } from './bootstrap'\nimport { resolveAllSecrets } from './secrets'\nimport { computeSandboxKey } from './key'\nimport { InMemoryLockStore, InMemorySandboxStore } from './store'\nimport type { SandboxFileHookEvent } from '@tanstack/ai'\nimport type { SandboxHandle, SandboxProvider } from './contracts'\nimport type { SandboxKeyInput } from './key'\nimport type { LockStore, SandboxStore } from './store'\nimport type { SandboxPolicy } from './policy'\nimport type { WorkspaceDefinition } from './workspace'\n\n/**\n * Sandbox-scoped hooks declared on `defineSandbox`. File hooks fire for every\n * create/change/delete during a chat run; lifecycle hooks fire server-side.\n */\nexport interface SandboxHooks {\n  onFile?: (e: SandboxFileHookEvent) => void | Promise<void>\n  onFileCreate?: (e: SandboxFileHookEvent) => void | Promise<void>\n  onFileChange?: (e: SandboxFileHookEvent) => void | Promise<void>\n  onFileDelete?: (e: SandboxFileHookEvent) => void | Promise<void>\n  onReady?: (handle: SandboxHandle) => void | Promise<void>\n  onError?: (err: unknown) => void | Promise<void>\n  onDestroy?: () => void | Promise<void>\n}\n\nexport type ReuseStrategy = 'thread' | 'none'\nexport type SnapshotStrategy = 'after-setup' | 'after-run' | 'none'\n\nexport interface SandboxLifecycle {\n  /** `'thread'` resumes one sandbox per thread; `'none'` is fresh per run. */\n  reuse?: ReuseStrategy\n  /** When to snapshot (provider-permitting). */\n  snapshot?: SnapshotStrategy\n  /** Hint for how long a provider should keep the sandbox warm between runs. */\n  keepAlive?: string\n  /** Destroy the sandbox after the run completes. */\n  destroyOnComplete?: boolean\n  /**\n   * Maximum age of a sandbox record before it is discarded and re-created\n   * instead of resumed. Accepts `'<n>h'` (hours) or `'<n>m'` (minutes),\n   * e.g. `'2h'` or `'30m'`.\n   */\n  snapshotMaxAge?: string\n}\n\nexport interface SandboxConfig {\n  id: string\n  provider: SandboxProvider\n  workspace?: WorkspaceDefinition\n  policy?: SandboxPolicy\n  lifecycle?: SandboxLifecycle\n  /** Sandbox-scoped file/lifecycle hooks. */\n  hooks?: SandboxHooks\n  /** Watch the workspace for file events (default true). `false` disables the\n   *  watcher; `{ diff: true }` also emits a per-file `sandbox.file.diff` event. */\n  fileEvents?: boolean | { diff?: boolean }\n}\n\n/** Context passed to `ensure()` by `withSandbox` (or advanced callers). */\nexport interface SandboxEnsureContext {\n  threadId: string\n  runId: string\n  /** Persistence seam; falls back to an in-memory store when absent. */\n  store?: SandboxStore\n  /** Lock seam; falls back to an in-memory lock when absent. */\n  locks?: LockStore\n  tenant?: { userId?: string; orgId?: string }\n  signal?: AbortSignal\n}\n\nexport interface SandboxDefinition {\n  readonly id: string\n  readonly provider: SandboxProvider\n  readonly workspace?: WorkspaceDefinition\n  readonly policy?: SandboxPolicy\n  readonly lifecycle?: SandboxLifecycle\n  /** Sandbox-scoped file/lifecycle hooks. */\n  readonly hooks?: SandboxHooks\n  /** Watch the workspace for file events (default true). `false` disables the\n   *  watcher; `{ diff: true }` also emits a per-file `sandbox.file.diff` event. */\n  readonly fileEvents?: boolean | { diff?: boolean }\n  /** Compound instance key for a given run context. */\n  key: (ctx: SandboxEnsureContext) => string\n  /** Resume-or-create the sandbox for this thread/run. */\n  ensure: (ctx: SandboxEnsureContext) => Promise<SandboxHandle>\n  /** Tear down the sandbox recorded for this key. */\n  destroy: (ctx: SandboxEnsureContext) => Promise<void>\n}\n\n/**\n * Parse a human-readable duration string into milliseconds.\n * Supports `'<n>h'` (hours) and `'<n>m'` (minutes).\n * Returns `undefined` when the input is undefined or the format is unrecognised.\n */\nfunction parseMaxAgeMs(value: string | undefined): number | undefined {\n  if (value === undefined) return undefined\n  const hourMatch = /^(\\d+)h$/.exec(value)\n  if (hourMatch) return Number(hourMatch[1]) * 60 * 60 * 1000\n  const minuteMatch = /^(\\d+)m$/.exec(value)\n  if (minuteMatch) return Number(minuteMatch[1]) * 60 * 1000\n  return undefined\n}\n\n// Process-lifetime fallbacks shared across all definitions so concurrent\n// ensures for the same key serialize even without an injected store/lock.\nconst fallbackStore = new InMemorySandboxStore()\nconst fallbackLocks = new InMemoryLockStore()\n\nexport function defineSandbox(config: SandboxConfig): SandboxDefinition {\n  const keyInputFor = (ctx: SandboxEnsureContext): SandboxKeyInput => ({\n    threadId:\n      config.lifecycle?.reuse === 'none'\n        ? `${ctx.threadId}:${ctx.runId}`\n        : ctx.threadId,\n    sandboxId: config.id,\n    providerName: config.provider.name,\n    workspace: config.workspace,\n    tenant: ctx.tenant,\n  })\n\n  const ensure = async (ctx: SandboxEnsureContext): Promise<SandboxHandle> => {\n    const store = ctx.store ?? fallbackStore\n    const locks = ctx.locks ?? fallbackLocks\n    const key = computeSandboxKey(keyInputFor(ctx))\n    const caps = config.provider.capabilities()\n\n    return locks.withLock(`sandbox:${key}`, async () => {\n      const effectiveSnapshot: SnapshotStrategy =\n        config.lifecycle?.snapshot ?? (caps.snapshots ? 'after-setup' : 'none')\n      const maxAgeMs = parseMaxAgeMs(config.lifecycle?.snapshotMaxAge)\n\n      const existing = await store.get(key)\n      if (existing) {\n        // Check whether the record has exceeded snapshotMaxAge; if so,\n        // discard and fall through to a fresh create.\n        const tooOld =\n          maxAgeMs !== undefined && Date.now() - existing.updatedAt > maxAgeMs\n\n        if (!tooOld) {\n          // 1) Try to reconnect to the still-running sandbox.\n          const resumed = await config.provider.resume({\n            id: existing.providerSandboxId,\n            signal: ctx.signal,\n          })\n          if (resumed) {\n            await store.upsert({\n              ...existing,\n              latestRunId: ctx.runId,\n              updatedAt: Date.now(),\n            })\n            return resumed\n          }\n          // 2) Else restore from the latest snapshot, if supported.\n          if (\n            existing.latestSnapshotId &&\n            caps.snapshots &&\n            config.provider.restoreSnapshot\n          ) {\n            const restored = await config.provider.restoreSnapshot({\n              snapshotId: existing.latestSnapshotId,\n              workspace: config.workspace,\n              policy: config.policy,\n              env:\n                config.workspace?.secrets !== undefined\n                  ? resolveAllSecrets(config.workspace.secrets)\n                  : undefined,\n              signal: ctx.signal,\n            })\n            await store.upsert({\n              ...existing,\n              providerSandboxId: restored.id,\n              latestRunId: ctx.runId,\n              updatedAt: Date.now(),\n            })\n            return restored\n          }\n        }\n        // 3) Else fall through and re-create under the same identity\n        //    (capability-aware degradation for ephemeral-disk providers, or\n        //    snapshotMaxAge TTL exceeded).\n      }\n\n      const created = await config.provider.create({\n        // Deterministic id so consumers can reconstruct the provider sandbox\n        // address from run context (not just from the store record).\n        id: key,\n        workspace: config.workspace,\n        policy: config.policy,\n        env:\n          config.workspace?.secrets !== undefined\n            ? resolveAllSecrets(config.workspace.secrets)\n            : undefined,\n        signal: ctx.signal,\n      })\n\n      if (config.workspace) {\n        try {\n          await bootstrapWorkspace(created, config.workspace, {\n            signal: ctx.signal,\n          })\n        } catch (error) {\n          // Bootstrap failed after the sandbox was created but before it was\n          // recorded — destroy the orphan so a failed/retried run doesn't leak\n          // a (billed) sandbox, then surface the original error.\n          await created.destroy().catch(() => {})\n          throw error\n        }\n      }\n\n      let latestSnapshotId: string | undefined\n      if (\n        effectiveSnapshot === 'after-setup' &&\n        caps.snapshots &&\n        created.snapshot\n      ) {\n        latestSnapshotId = (await created.snapshot('after-setup')).id\n      }\n\n      await store.upsert({\n        key,\n        provider: config.provider.name,\n        providerSandboxId: created.id,\n        latestSnapshotId,\n        threadId: ctx.threadId,\n        latestRunId: ctx.runId,\n        updatedAt: Date.now(),\n      })\n      return created\n    })\n  }\n\n  const destroy = async (ctx: SandboxEnsureContext): Promise<void> => {\n    const store = ctx.store ?? fallbackStore\n    const key = computeSandboxKey(keyInputFor(ctx))\n    const existing = await store.get(key)\n    if (!existing) return\n    await config.provider.destroy({\n      id: existing.providerSandboxId,\n      signal: ctx.signal,\n    })\n    await store.delete(key)\n  }\n\n  return {\n    id: config.id,\n    provider: config.provider,\n    workspace: config.workspace,\n    policy: config.policy,\n    lifecycle: config.lifecycle,\n    hooks: config.hooks,\n    fileEvents: config.fileEvents,\n    key: (ctx) => computeSandboxKey(keyInputFor(ctx)),\n    ensure,\n    destroy,\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"sandbox.js","names":[],"sources":["../../src/sandbox.ts"],"sourcesContent":["/**\n * `defineSandbox()` returns a LAZY controller — it never creates a sandbox at\n * definition time. `withSandbox()` (and advanced users) call `ensure()` to\n * resume-or-create, following: provider.resume → provider.restoreSnapshot →\n * create + bootstrap. The controller folds provider/workspace/policy/lifecycle\n * into a stable instance key and coordinates through the (optional) lock +\n * sandbox stores.\n */\nimport { bootstrapWorkspace } from './bootstrap'\nimport { resolveAllSecrets } from './secrets'\nimport { computeSandboxKey } from './key'\nimport { InMemoryLockStore } from '@tanstack/ai/locks'\nimport type { LockStore } from '@tanstack/ai/locks'\nimport type { SandboxFileHookEvent } from '@tanstack/ai'\nimport { InMemorySandboxInstanceStore } from './instance-store'\nimport type { SandboxInstanceStore } from './instance-store'\nimport type { SandboxHandle, SandboxProvider } from './contracts'\nimport type { SandboxKeyInput } from './key'\nimport type { SandboxPolicy } from './policy'\nimport type { WorkspaceDefinition } from './workspace'\n\n/**\n * Sandbox-scoped hooks declared on `defineSandbox`. File hooks fire for every\n * create/change/delete during a chat run; lifecycle hooks fire server-side.\n */\nexport interface SandboxHooks {\n  onFile?: (e: SandboxFileHookEvent) => void | Promise<void>\n  onFileCreate?: (e: SandboxFileHookEvent) => void | Promise<void>\n  onFileChange?: (e: SandboxFileHookEvent) => void | Promise<void>\n  onFileDelete?: (e: SandboxFileHookEvent) => void | Promise<void>\n  onReady?: (handle: SandboxHandle) => void | Promise<void>\n  onError?: (err: unknown) => void | Promise<void>\n  onDestroy?: () => void | Promise<void>\n}\n\nexport type ReuseStrategy = 'thread' | 'none'\nexport type SnapshotStrategy = 'after-setup' | 'after-run' | 'none'\n\nexport interface SandboxLifecycle {\n  /** `'thread'` resumes one sandbox per thread; `'none'` is fresh per run. */\n  reuse?: ReuseStrategy\n  /** When to snapshot (provider-permitting). */\n  snapshot?: SnapshotStrategy\n  /** Hint for how long a provider should keep the sandbox warm between runs. */\n  keepAlive?: string\n  /** Destroy the sandbox after the run completes. */\n  destroyOnComplete?: boolean\n  /**\n   * Maximum age of a sandbox record before it is discarded and re-created\n   * instead of resumed. Accepts `'<n>h'` (hours) or `'<n>m'` (minutes),\n   * e.g. `'2h'` or `'30m'`.\n   */\n  snapshotMaxAge?: string\n}\n\nexport interface SandboxConfig {\n  id: string\n  provider: SandboxProvider\n  workspace?: WorkspaceDefinition\n  policy?: SandboxPolicy\n  lifecycle?: SandboxLifecycle\n  /** Sandbox-scoped file/lifecycle hooks. */\n  hooks?: SandboxHooks\n  /** Watch the workspace for file events (default true). `false` disables the\n   *  watcher; `{ diff: true }` also emits a per-file `sandbox.file.diff` event. */\n  fileEvents?: boolean | { diff?: boolean }\n}\n\n/** Context passed to `ensure()` by `withSandbox` (or advanced callers). */\nexport interface SandboxEnsureContext {\n  threadId: string\n  runId: string\n  /** Persistence seam; falls back to an in-memory store when absent. */\n  store?: SandboxInstanceStore\n  /** Lock seam; falls back to an in-memory lock when absent. */\n  locks?: LockStore\n  tenant?: { userId?: string; orgId?: string }\n  signal?: AbortSignal\n}\n\nexport interface SandboxDefinition {\n  readonly id: string\n  readonly provider: SandboxProvider\n  readonly workspace?: WorkspaceDefinition\n  readonly policy?: SandboxPolicy\n  readonly lifecycle?: SandboxLifecycle\n  /** Sandbox-scoped file/lifecycle hooks. */\n  readonly hooks?: SandboxHooks\n  /** Watch the workspace for file events (default true). `false` disables the\n   *  watcher; `{ diff: true }` also emits a per-file `sandbox.file.diff` event. */\n  readonly fileEvents?: boolean | { diff?: boolean }\n  /** Compound instance key for a given run context. */\n  key: (ctx: SandboxEnsureContext) => string\n  /** Resume-or-create the sandbox for this thread/run. */\n  ensure: (ctx: SandboxEnsureContext) => Promise<SandboxHandle>\n  /** Tear down the sandbox recorded for this key. */\n  destroy: (ctx: SandboxEnsureContext) => Promise<void>\n}\n\n/**\n * Parse a human-readable duration string into milliseconds.\n * Supports `'<n>h'` (hours) and `'<n>m'` (minutes).\n * Returns `undefined` when the input is undefined or the format is unrecognised.\n */\nfunction parseMaxAgeMs(value: string | undefined): number | undefined {\n  if (value === undefined) return undefined\n  const hourMatch = /^(\\d+)h$/.exec(value)\n  if (hourMatch) return Number(hourMatch[1]) * 60 * 60 * 1000\n  const minuteMatch = /^(\\d+)m$/.exec(value)\n  if (minuteMatch) return Number(minuteMatch[1]) * 60 * 1000\n  return undefined\n}\n\n/**\n * Bound for the unfenced teardown `destroy` call (see `destroy` below). Long\n * enough that a slow provider API still completes, short enough that a wedged\n * one cannot pin the process forever.\n */\nconst DESTROY_TIMEOUT_MS = 60 * 1000\n\n// Process-lifetime fallbacks shared across all definitions so concurrent\n// ensures for the same key serialize even without an injected store/lock.\nconst fallbackStore = new InMemorySandboxInstanceStore()\nconst fallbackLocks = new InMemoryLockStore()\n\nexport function defineSandbox(config: SandboxConfig): SandboxDefinition {\n  const keyInputFor = (ctx: SandboxEnsureContext): SandboxKeyInput => ({\n    threadId:\n      config.lifecycle?.reuse === 'none'\n        ? `${ctx.threadId}:${ctx.runId}`\n        : ctx.threadId,\n    sandboxId: config.id,\n    providerName: config.provider.name,\n    workspace: config.workspace,\n    tenant: ctx.tenant,\n  })\n\n  const ensure = async (ctx: SandboxEnsureContext): Promise<SandboxHandle> => {\n    const store = ctx.store ?? fallbackStore\n    const locks = ctx.locks ?? fallbackLocks\n    const key = computeSandboxKey(keyInputFor(ctx))\n    const caps = config.provider.capabilities()\n\n    return locks.withLock(`sandbox:${key}`, async () => {\n      const effectiveSnapshot: SnapshotStrategy =\n        config.lifecycle?.snapshot ?? (caps.snapshots ? 'after-setup' : 'none')\n      const maxAgeMs = parseMaxAgeMs(config.lifecycle?.snapshotMaxAge)\n\n      const existing = await store.get(key)\n      if (existing) {\n        // Check whether the record has exceeded snapshotMaxAge; if so,\n        // discard and fall through to a fresh create.\n        const tooOld =\n          maxAgeMs !== undefined && Date.now() - existing.updatedAt > maxAgeMs\n\n        if (!tooOld) {\n          // 1) Try to reconnect to the still-running sandbox.\n          const resumed = await config.provider.resume({\n            id: existing.providerSandboxId,\n            signal: ctx.signal,\n          })\n          if (resumed) {\n            await store.upsert({\n              ...existing,\n              latestRunId: ctx.runId,\n              updatedAt: Date.now(),\n            })\n            return resumed\n          }\n          // 2) Else restore from the latest snapshot, if supported.\n          if (\n            existing.latestSnapshotId &&\n            caps.snapshots &&\n            config.provider.restoreSnapshot\n          ) {\n            const restored = await config.provider.restoreSnapshot({\n              snapshotId: existing.latestSnapshotId,\n              workspace: config.workspace,\n              policy: config.policy,\n              env:\n                config.workspace?.secrets !== undefined\n                  ? resolveAllSecrets(config.workspace.secrets)\n                  : undefined,\n              signal: ctx.signal,\n            })\n            await store.upsert({\n              ...existing,\n              providerSandboxId: restored.id,\n              latestRunId: ctx.runId,\n              updatedAt: Date.now(),\n            })\n            return restored\n          }\n        }\n        // 3) Else fall through and re-create under the same identity\n        //    (capability-aware degradation for ephemeral-disk providers, or\n        //    snapshotMaxAge TTL exceeded).\n      }\n\n      const created = await config.provider.create({\n        // Deterministic id so consumers can reconstruct the provider sandbox\n        // address from run context (not just from the store record).\n        id: key,\n        workspace: config.workspace,\n        policy: config.policy,\n        env:\n          config.workspace?.secrets !== undefined\n            ? resolveAllSecrets(config.workspace.secrets)\n            : undefined,\n        signal: ctx.signal,\n      })\n\n      if (config.workspace) {\n        try {\n          await bootstrapWorkspace(created, config.workspace, {\n            signal: ctx.signal,\n          })\n        } catch (error) {\n          // Bootstrap failed after the sandbox was created but before it was\n          // recorded — destroy the orphan so a failed/retried run doesn't leak\n          // a (billed) sandbox, then surface the original error.\n          await created.destroy().catch(() => {})\n          throw error\n        }\n      }\n\n      let latestSnapshotId: string | undefined\n      if (\n        effectiveSnapshot === 'after-setup' &&\n        caps.snapshots &&\n        created.snapshot\n      ) {\n        latestSnapshotId = (await created.snapshot('after-setup')).id\n      }\n\n      await store.upsert({\n        key,\n        provider: config.provider.name,\n        providerSandboxId: created.id,\n        latestSnapshotId,\n        threadId: ctx.threadId,\n        latestRunId: ctx.runId,\n        updatedAt: Date.now(),\n      })\n      return created\n    })\n  }\n\n  const destroy = async (ctx: SandboxEnsureContext): Promise<void> => {\n    const store = ctx.store ?? fallbackStore\n    const key = computeSandboxKey(keyInputFor(ctx))\n    const existing = await store.get(key)\n    if (!existing) return\n    /*\n     * TEARDOWN IS DELIBERATELY NOT FENCED BY `ctx.signal`.\n     *\n     * `destroy` runs on every teardown path INCLUDING the one caused by that\n     * very signal aborting, so forwarding it hands the provider a signal that is\n     * already aborted: a provider that honors it does nothing and returns\n     * successfully, and `store.delete` below then removes the only pointer to a\n     * live, billed sandbox. `SandboxInstanceStore` has no `list` (see the note\n     * at the top of `reclaim.ts`), so that sandbox is unreachable from then on.\n     *\n     * Same reasoning as `close()` never being fenced by the run claim (see\n     * `fenceDurability` in `claim.ts`): cleanup must outlive whatever cancelled\n     * the work. A fresh controller with its own bounded timeout keeps the call\n     * from hanging forever without letting the caller's abort cancel it.\n     */\n    const teardown = new AbortController()\n    const timer = setTimeout(() => teardown.abort(), DESTROY_TIMEOUT_MS)\n    try {\n      await config.provider.destroy({\n        id: existing.providerSandboxId,\n        signal: teardown.signal,\n      })\n    } finally {\n      clearTimeout(timer)\n    }\n    await store.delete(key)\n  }\n\n  return {\n    id: config.id,\n    provider: config.provider,\n    workspace: config.workspace,\n    policy: config.policy,\n    lifecycle: config.lifecycle,\n    hooks: config.hooks,\n    fileEvents: config.fileEvents,\n    key: (ctx) => computeSandboxKey(keyInputFor(ctx)),\n    ensure,\n    destroy,\n  }\n}\n"],"mappings":"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"}

package/dist/esm/secrets.js

@@ -1,59 +1,51 @@
-const REGISTRY = /* @__PURE__ */ Symbol("secrets.registry");
+//#region src/secrets.ts
+/** Internal symbol used to store the value registry on a Secrets object. */
+var REGISTRY = Symbol("secrets.registry");
+/** Create a typed secrets object from a plain record of name→value pairs. */
 function createSecrets(values) {
-  const registry = new Map(Object.entries(values));
-  const obj = {};
-  for (const name of Object.keys(values)) {
-    obj[name] = Object.freeze({ __secretName: name });
-  }
-  Object.defineProperty(obj, REGISTRY, {
-    value: registry,
-    enumerable: false,
-    configurable: false,
-    writable: false
-  });
-  return obj;
+	const registry = new Map(Object.entries(values));
+	const obj = {};
+	for (const name of Object.keys(values)) obj[name] = Object.freeze({ __secretName: name });
+	Object.defineProperty(obj, REGISTRY, {
+		value: registry,
+		enumerable: false,
+		configurable: false,
+		writable: false
+	});
+	return obj;
 }
+/** Create a bearer-token marker that resolves to `Bearer <value>` at runtime. */
 function bearer(ref) {
-  return Object.freeze({ __bearerRef: ref });
+	return Object.freeze({ __bearerRef: ref });
 }
+/** Return true when `x` is a SecretRef. */
 function isSecretRef(x) {
-  return typeof x === "object" && x !== null && typeof x["__secretName"] === "string";
+	return typeof x === "object" && x !== null && typeof x["__secretName"] === "string";
 }
+/** Resolve a SecretRef to its plaintext value using the secrets object. */
 function resolveSecret(secrets, ref) {
-  const registry = Reflect.get(secrets, REGISTRY);
-  if (registry === void 0) {
-    throw new Error(
-      "resolveSecret: secrets object was not created by createSecrets"
-    );
-  }
-  const value = registry.get(ref.__secretName);
-  if (value === void 0) {
-    throw new Error(`resolveSecret: unknown secret "${ref.__secretName}"`);
-  }
-  return value;
+	const registry = Reflect.get(secrets, REGISTRY);
+	if (registry === void 0) throw new Error("resolveSecret: secrets object was not created by createSecrets");
+	const value = registry.get(ref.__secretName);
+	if (value === void 0) throw new Error(`resolveSecret: unknown secret "${ref.__secretName}"`);
+	return value;
 }
+/** Resolve a BearerRef to a `Bearer <value>` string. */
 function resolveBearer(secrets, ref) {
-  return `Bearer ${resolveSecret(secrets, ref.__bearerRef)}`;
+	return `Bearer ${resolveSecret(secrets, ref.__bearerRef)}`;
 }
+/**
+* Resolve all secrets in a Secrets object to a plain `Record<string, string>`
+* suitable for injecting into a process environment.
+*/
 function resolveAllSecrets(secrets) {
-  const registry = Reflect.get(secrets, REGISTRY);
-  if (registry === void 0) {
-    throw new Error(
-      "resolveAllSecrets: secrets object was not created by createSecrets"
-    );
-  }
-  const result = {};
-  for (const [key, value] of registry.entries()) {
-    result[key] = value;
-  }
-  return result;
+	const registry = Reflect.get(secrets, REGISTRY);
+	if (registry === void 0) throw new Error("resolveAllSecrets: secrets object was not created by createSecrets");
+	const result = {};
+	for (const [key, value] of registry.entries()) result[key] = value;
+	return result;
 }
-export {
-  bearer,
-  createSecrets,
-  isSecretRef,
-  resolveAllSecrets,
-  resolveBearer,
-  resolveSecret
-};
-//# sourceMappingURL=secrets.js.map
+//#endregion
+export { bearer, createSecrets, isSecretRef, resolveAllSecrets, resolveBearer, resolveSecret };
+
+//# sourceMappingURL=secrets.js.map

package/dist/esm/secrets.js.map

@@ -1 +1 @@
-{"version":3,"file":"secrets.js","sources":["../../src/secrets.ts"],"sourcesContent":["/**\n * Type-safe secret references for sandbox workspace definitions.\n *\n * Values are stored in a Map under a non-enumerable symbol key on the returned\n * object so that `Object.keys(secrets)` only yields the ref names, never the\n * registry or the underlying plaintext values.\n */\n\n/** A reference to a named secret — carries only the name, never the value. */\nexport type SecretRef = { readonly __secretName: string }\n\n/**\n * A map of named SecretRef properties. The underlying value registry is stored\n * under a non-enumerable symbol so iterating the object never exposes it.\n */\nexport type Secrets<TKeys extends string = string> = {\n  readonly [P in TKeys]: SecretRef\n}\n\n/** Internal symbol used to store the value registry on a Secrets object. */\nconst REGISTRY = Symbol('secrets.registry')\n\n/** Create a typed secrets object from a plain record of name→value pairs. */\nexport function createSecrets<T extends Record<string, string>>(\n  values: T,\n): Secrets<keyof T & string> {\n  const registry = new Map<string, string>(Object.entries(values))\n  const obj = {} as Record<string, SecretRef>\n\n  for (const name of Object.keys(values)) {\n    obj[name] = Object.freeze({ __secretName: name })\n  }\n\n  Object.defineProperty(obj, REGISTRY, {\n    value: registry,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  })\n\n  return obj as Secrets<keyof T & string>\n}\n\n/** Marker type for a bearer-token value derived from a SecretRef. */\nexport type BearerRef = { readonly __bearerRef: SecretRef }\n\n/** Create a bearer-token marker that resolves to `Bearer <value>` at runtime. */\nexport function bearer(ref: SecretRef): BearerRef {\n  return Object.freeze({ __bearerRef: ref })\n}\n\n/** Return true when `x` is a SecretRef. */\nexport function isSecretRef(x: unknown): x is SecretRef {\n  return (\n    typeof x === 'object' &&\n    x !== null &&\n    typeof (x as Record<string, unknown>)['__secretName'] === 'string'\n  )\n}\n\n/** Resolve a SecretRef to its plaintext value using the secrets object. */\nexport function resolveSecret(secrets: Secrets, ref: SecretRef): string {\n  const registry = Reflect.get(secrets, REGISTRY) as\n    | Map<string, string>\n    | undefined\n  if (registry === undefined) {\n    throw new Error(\n      'resolveSecret: secrets object was not created by createSecrets',\n    )\n  }\n  const value = registry.get(ref.__secretName)\n  if (value === undefined) {\n    throw new Error(`resolveSecret: unknown secret \"${ref.__secretName}\"`)\n  }\n  return value\n}\n\n/** Resolve a BearerRef to a `Bearer <value>` string. */\nexport function resolveBearer(secrets: Secrets, ref: BearerRef): string {\n  return `Bearer ${resolveSecret(secrets, ref.__bearerRef)}`\n}\n\n/**\n * Resolve all secrets in a Secrets object to a plain `Record<string, string>`\n * suitable for injecting into a process environment.\n */\nexport function resolveAllSecrets(secrets: Secrets): Record<string, string> {\n  const registry = Reflect.get(secrets, REGISTRY) as\n    | Map<string, string>\n    | undefined\n  if (registry === undefined) {\n    throw new Error(\n      'resolveAllSecrets: secrets object was not created by createSecrets',\n    )\n  }\n  const result: Record<string, string> = {}\n  for (const [key, value] of registry.entries()) {\n    result[key] = value\n  }\n  return result\n}\n"],"names":[],"mappings":"AAoBA,MAAM,kCAAkB,kBAAkB;AAGnC,SAAS,cACd,QAC2B;AAC3B,QAAM,WAAW,IAAI,IAAoB,OAAO,QAAQ,MAAM,CAAC;AAC/D,QAAM,MAAM,CAAA;AAEZ,aAAW,QAAQ,OAAO,KAAK,MAAM,GAAG;AACtC,QAAI,IAAI,IAAI,OAAO,OAAO,EAAE,cAAc,MAAM;AAAA,EAClD;AAEA,SAAO,eAAe,KAAK,UAAU;AAAA,IACnC,OAAO;AAAA,IACP,YAAY;AAAA,IACZ,cAAc;AAAA,IACd,UAAU;AAAA,EAAA,CACX;AAED,SAAO;AACT;AAMO,SAAS,OAAO,KAA2B;AAChD,SAAO,OAAO,OAAO,EAAE,aAAa,KAAK;AAC3C;AAGO,SAAS,YAAY,GAA4B;AACtD,SACE,OAAO,MAAM,YACb,MAAM,QACN,OAAQ,EAA8B,cAAc,MAAM;AAE9D;AAGO,SAAS,cAAc,SAAkB,KAAwB;AACtE,QAAM,WAAW,QAAQ,IAAI,SAAS,QAAQ;AAG9C,MAAI,aAAa,QAAW;AAC1B,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AACA,QAAM,QAAQ,SAAS,IAAI,IAAI,YAAY;AAC3C,MAAI,UAAU,QAAW;AACvB,UAAM,IAAI,MAAM,kCAAkC,IAAI,YAAY,GAAG;AAAA,EACvE;AACA,SAAO;AACT;AAGO,SAAS,cAAc,SAAkB,KAAwB;AACtE,SAAO,UAAU,cAAc,SAAS,IAAI,WAAW,CAAC;AAC1D;AAMO,SAAS,kBAAkB,SAA0C;AAC1E,QAAM,WAAW,QAAQ,IAAI,SAAS,QAAQ;AAG9C,MAAI,aAAa,QAAW;AAC1B,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AACA,QAAM,SAAiC,CAAA;AACvC,aAAW,CAAC,KAAK,KAAK,KAAK,SAAS,WAAW;AAC7C,WAAO,GAAG,IAAI;AAAA,EAChB;AACA,SAAO;AACT;"}
+{"version":3,"file":"secrets.js","names":[],"sources":["../../src/secrets.ts"],"sourcesContent":["/**\n * Type-safe secret references for sandbox workspace definitions.\n *\n * Values are stored in a Map under a non-enumerable symbol key on the returned\n * object so that `Object.keys(secrets)` only yields the ref names, never the\n * registry or the underlying plaintext values.\n */\n\n/** A reference to a named secret — carries only the name, never the value. */\nexport type SecretRef = { readonly __secretName: string }\n\n/**\n * A map of named SecretRef properties. The underlying value registry is stored\n * under a non-enumerable symbol so iterating the object never exposes it.\n */\nexport type Secrets<TKeys extends string = string> = {\n  readonly [P in TKeys]: SecretRef\n}\n\n/** Internal symbol used to store the value registry on a Secrets object. */\nconst REGISTRY = Symbol('secrets.registry')\n\n/** Create a typed secrets object from a plain record of name→value pairs. */\nexport function createSecrets<T extends Record<string, string>>(\n  values: T,\n): Secrets<keyof T & string> {\n  const registry = new Map<string, string>(Object.entries(values))\n  const obj = {} as Record<string, SecretRef>\n\n  for (const name of Object.keys(values)) {\n    obj[name] = Object.freeze({ __secretName: name })\n  }\n\n  Object.defineProperty(obj, REGISTRY, {\n    value: registry,\n    enumerable: false,\n    configurable: false,\n    writable: false,\n  })\n\n  return obj as Secrets<keyof T & string>\n}\n\n/** Marker type for a bearer-token value derived from a SecretRef. */\nexport type BearerRef = { readonly __bearerRef: SecretRef }\n\n/** Create a bearer-token marker that resolves to `Bearer <value>` at runtime. */\nexport function bearer(ref: SecretRef): BearerRef {\n  return Object.freeze({ __bearerRef: ref })\n}\n\n/** Return true when `x` is a SecretRef. */\nexport function isSecretRef(x: unknown): x is SecretRef {\n  return (\n    typeof x === 'object' &&\n    x !== null &&\n    typeof (x as Record<string, unknown>)['__secretName'] === 'string'\n  )\n}\n\n/** Resolve a SecretRef to its plaintext value using the secrets object. */\nexport function resolveSecret(secrets: Secrets, ref: SecretRef): string {\n  const registry = Reflect.get(secrets, REGISTRY) as\n    | Map<string, string>\n    | undefined\n  if (registry === undefined) {\n    throw new Error(\n      'resolveSecret: secrets object was not created by createSecrets',\n    )\n  }\n  const value = registry.get(ref.__secretName)\n  if (value === undefined) {\n    throw new Error(`resolveSecret: unknown secret \"${ref.__secretName}\"`)\n  }\n  return value\n}\n\n/** Resolve a BearerRef to a `Bearer <value>` string. */\nexport function resolveBearer(secrets: Secrets, ref: BearerRef): string {\n  return `Bearer ${resolveSecret(secrets, ref.__bearerRef)}`\n}\n\n/**\n * Resolve all secrets in a Secrets object to a plain `Record<string, string>`\n * suitable for injecting into a process environment.\n */\nexport function resolveAllSecrets(secrets: Secrets): Record<string, string> {\n  const registry = Reflect.get(secrets, REGISTRY) as\n    | Map<string, string>\n    | undefined\n  if (registry === undefined) {\n    throw new Error(\n      'resolveAllSecrets: secrets object was not created by createSecrets',\n    )\n  }\n  const result: Record<string, string> = {}\n  for (const [key, value] of registry.entries()) {\n    result[key] = value\n  }\n  return result\n}\n"],"mappings":";;AAoBA,IAAM,WAAW,OAAO,kBAAkB;;AAG1C,SAAgB,cACd,QAC2B;CAC3B,MAAM,WAAW,IAAI,IAAoB,OAAO,QAAQ,MAAM,CAAC;CAC/D,MAAM,MAAM,CAAC;CAEb,KAAK,MAAM,QAAQ,OAAO,KAAK,MAAM,GACnC,IAAI,QAAQ,OAAO,OAAO,EAAE,cAAc,KAAK,CAAC;CAGlD,OAAO,eAAe,KAAK,UAAU;EACnC,OAAO;EACP,YAAY;EACZ,cAAc;EACd,UAAU;CACZ,CAAC;CAED,OAAO;AACT;;AAMA,SAAgB,OAAO,KAA2B;CAChD,OAAO,OAAO,OAAO,EAAE,aAAa,IAAI,CAAC;AAC3C;;AAGA,SAAgB,YAAY,GAA4B;CACtD,OACE,OAAO,MAAM,YACb,MAAM,QACN,OAAQ,EAA8B,oBAAoB;AAE9D;;AAGA,SAAgB,cAAc,SAAkB,KAAwB;CACtE,MAAM,WAAW,QAAQ,IAAI,SAAS,QAAQ;CAG9C,IAAI,aAAa,KAAA,GACf,MAAM,IAAI,MACR,gEACF;CAEF,MAAM,QAAQ,SAAS,IAAI,IAAI,YAAY;CAC3C,IAAI,UAAU,KAAA,GACZ,MAAM,IAAI,MAAM,kCAAkC,IAAI,aAAa,EAAE;CAEvE,OAAO;AACT;;AAGA,SAAgB,cAAc,SAAkB,KAAwB;CACtE,OAAO,UAAU,cAAc,SAAS,IAAI,WAAW;AACzD;;;;;AAMA,SAAgB,kBAAkB,SAA0C;CAC1E,MAAM,WAAW,QAAQ,IAAI,SAAS,QAAQ;CAG9C,IAAI,aAAa,KAAA,GACf,MAAM,IAAI,MACR,oEACF;CAEF,MAAM,SAAiC,CAAC;CACxC,KAAK,MAAM,CAAC,KAAK,UAAU,SAAS,QAAQ,GAC1C,OAAO,OAAO;CAEhB,OAAO;AACT"}

package/dist/esm/setup-plan.js

@@ -1,16 +1,24 @@
+//#region src/setup-plan.ts
 function buildSetupPlan(input) {
-  if (input === void 0) return [];
-  if (Array.isArray(input)) {
-    return input.map((command) => ({ kind: "serial", command }));
-  }
-  const groups = [];
-  input({
-    serial: (command) => groups.push({ kind: "serial", command }),
-    parallel: (commands) => groups.push({ kind: "parallel", commands })
-  });
-  return groups;
+	if (input === void 0) return [];
+	if (Array.isArray(input)) return input.map((command) => ({
+		kind: "serial",
+		command
+	}));
+	const groups = [];
+	input({
+		serial: (command) => groups.push({
+			kind: "serial",
+			command
+		}),
+		parallel: (commands) => groups.push({
+			kind: "parallel",
+			commands
+		})
+	});
+	return groups;
 }
-export {
-  buildSetupPlan
-};
-//# sourceMappingURL=setup-plan.js.map
+//#endregion
+export { buildSetupPlan };
+
+//# sourceMappingURL=setup-plan.js.map

package/dist/esm/setup-plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup-plan.js","sources":["../../src/setup-plan.ts"],"sourcesContent":["export type SetupGroup =\n  | { kind: 'serial'; command: string }\n  | { kind: 'parallel'; commands: Array<string> }\n\nexport interface SetupBuilder {\n  serial: (command: string) => void\n  parallel: (commands: Array<string>) => void\n}\n\nexport type SetupInput = Array<string> | ((builder: SetupBuilder) => void)\n\nexport function buildSetupPlan(\n  input: SetupInput | undefined,\n): Array<SetupGroup> {\n  if (input === undefined) return []\n  if (Array.isArray(input)) {\n    return input.map((command) => ({ kind: 'serial', command }))\n  }\n  const groups: Array<SetupGroup> = []\n  input({\n    serial: (command) => groups.push({ kind: 'serial', command }),\n    parallel: (commands) => groups.push({ kind: 'parallel', commands }),\n  })\n  return groups\n}\n"],"names":[],"mappings":"AAWO,SAAS,eACd,OACmB;AACnB,MAAI,UAAU,OAAW,QAAO,CAAA;AAChC,MAAI,MAAM,QAAQ,KAAK,GAAG;AACxB,WAAO,MAAM,IAAI,CAAC,aAAa,EAAE,MAAM,UAAU,UAAU;AAAA,EAC7D;AACA,QAAM,SAA4B,CAAA;AAClC,QAAM;AAAA,IACJ,QAAQ,CAAC,YAAY,OAAO,KAAK,EAAE,MAAM,UAAU,SAAS;AAAA,IAC5D,UAAU,CAAC,aAAa,OAAO,KAAK,EAAE,MAAM,YAAY,SAAA,CAAU;AAAA,EAAA,CACnE;AACD,SAAO;AACT;"}
+{"version":3,"file":"setup-plan.js","names":[],"sources":["../../src/setup-plan.ts"],"sourcesContent":["export type SetupGroup =\n  | { kind: 'serial'; command: string }\n  | { kind: 'parallel'; commands: Array<string> }\n\nexport interface SetupBuilder {\n  serial: (command: string) => void\n  parallel: (commands: Array<string>) => void\n}\n\nexport type SetupInput = Array<string> | ((builder: SetupBuilder) => void)\n\nexport function buildSetupPlan(\n  input: SetupInput | undefined,\n): Array<SetupGroup> {\n  if (input === undefined) return []\n  if (Array.isArray(input)) {\n    return input.map((command) => ({ kind: 'serial', command }))\n  }\n  const groups: Array<SetupGroup> = []\n  input({\n    serial: (command) => groups.push({ kind: 'serial', command }),\n    parallel: (commands) => groups.push({ kind: 'parallel', commands }),\n  })\n  return groups\n}\n"],"mappings":";AAWA,SAAgB,eACd,OACmB;CACnB,IAAI,UAAU,KAAA,GAAW,OAAO,CAAC;CACjC,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,aAAa;EAAE,MAAM;EAAU;CAAQ,EAAE;CAE7D,MAAM,SAA4B,CAAC;CACnC,MAAM;EACJ,SAAS,YAAY,OAAO,KAAK;GAAE,MAAM;GAAU;EAAQ,CAAC;EAC5D,WAAW,aAAa,OAAO,KAAK;GAAE,MAAM;GAAY;EAAS,CAAC;CACpE,CAAC;CACD,OAAO;AACT"}

package/dist/esm/shell.d.ts

@@ -21,6 +21,14 @@ export interface BootstrapShell {
 export interface BootstrapShellOptions {
     /** Working directory to start the shell in (passed as ProcessOptions.cwd). */
     cwd?: string;
+    /**
+     * Belt-and-braces deadline for a single `run()` to see its sentinel. The
+     * primary termination condition is the stdout stream ending (see
+     * {@link createBootstrapShell}); this only catches a shell that is alive,
+     * silent, and never going to answer. Generous by default because setup steps
+     * legitimately run for a long time (`npm install`, image pulls).
+     */
+    commandTimeoutMs?: number;
 }
 /**
  * Spawn one `sh` process and return a {@link BootstrapShell} that drives it