@tanstack/ai-sandbox 0.2.3 → 0.3.0

package/dist/esm/middleware.js

@@ -1,219 +1,346 @@
-import { defineChatMiddleware } from "@tanstack/ai";
-import { getSandboxRuntime } from "@tanstack/ai/adapter-internals";
-import { SandboxStoreCapability, LocksCapability, SandboxCapability, provideSandbox, provideSandboxPolicy } from "./capabilities.js";
-import { computeWorkspaceHash } from "./key.js";
-import { resolveFileEvents, buildFileHookEvent } from "./file-diff.js";
+import { SandboxCapability, provideSandbox, provideSandboxPolicy } from "./capabilities.js";
+import { SandboxInstanceStoreCapability } from "./instance-store.js";
 import { ProjectionCapability, provideWorkspaceProjection } from "./projection.js";
+import { provideSandboxDurability, resolveSandboxDurability } from "./durability.js";
+import { computeWorkspaceHash } from "./key.js";
+import { buildFileHookEvent, resolveFileEvents } from "./file-diff.js";
 import { resolveSecret } from "./secrets.js";
+import { createToolHistoryRecorder, stripObservedToolCalls } from "./tool-history.js";
+import "./bootstrap.js";
 import { watchWorkspace } from "./watch.js";
-import { DEFAULT_WORKSPACE_ROOT } from "./bootstrap.js";
-const runState = /* @__PURE__ */ new WeakMap();
+import { defineChatMiddleware, provideDetachableRun, provideRunDetached, wasCancelRequested } from "@tanstack/ai";
+import { InMemoryLockStore, LocksCapability } from "@tanstack/ai/locks";
+import { getPendingTurn, getRunDisconnect, getSandboxRuntime } from "@tanstack/ai/adapter-internals";
+//#region src/middleware.ts
+/**
+* `withSandbox(definition, options?)` — the middleware that PROVIDES the
+* {@link SandboxCapability} a harness adapter requires.
+*
+* - `setup`: resume-or-create the sandbox (via the definition's ensure
+*   algorithm), provide the handle, using the durability seams from
+*   {@link SandboxMiddlewareOptions} (or, failing that, a bus-provided
+*   SandboxInstanceStoreCapability / LocksCapability, then an in-memory
+*   fallback). If `fileEvents` is not false, starts a
+*   watcher that dispatches to sandbox-scoped hooks and forwards to the runtime
+*   sink.
+* - `onFinish`/`onAbort`/`onError`: stop the watcher, snapshot (`after-run`)
+*   and/or destroy per lifecycle.
+*
+* NOTE: streamed sandbox lifecycle events (sandbox.created, workspace.setup.*)
+* are emitted by the harness adapter's chatStream (which can yield CUSTOM
+* chunks), not from here — middleware setup runs before streaming begins.
+*/
+var runState = /* @__PURE__ */ new WeakMap();
+/**
+* Stop the watcher and drain any in-flight `diff()` promises before teardown,
+* so the final file's diff isn't dropped when a run finishes/aborts/errors
+* mid-computation. The `pendingDiffs` await is the load-bearing line — without
+* it a deferred diff resolves after the run is gone and its chunk is lost.
+*/
 async function drainWatcher(state, phase) {
-  try {
-    await state.watcher?.stop();
-  } catch (error) {
-    state.logger?.warn("sandbox watcher stop failed", { phase, error });
-  }
-  await Promise.allSettled(state.pendingDiffs);
-  if (state.watcher) state.logger?.sandbox("sandbox watcher stopped", { phase });
+	try {
+		await state.watcher?.stop();
+	} catch (error) {
+		state.logger?.warn("sandbox watcher stop failed", {
+			phase,
+			error
+		});
+	}
+	await Promise.allSettled(state.pendingDiffs);
+	if (state.watcher) state.logger?.sandbox("sandbox watcher stopped", { phase });
+}
+/**
+* Record the two facts a later attach and the reaper both need, then publish the
+* detach verdict core reads.
+*
+* Shared by the DISCONNECT subscriber registered in `setup` (the run is still
+* going — the normal case) and `onAbort`'s detach branch (the run is being torn
+* down while detachable), so the two can never write a different shape of detach.
+*
+* GUARDED, and reports failure rather than throwing. `update` is a documented
+* no-op for an unknown runId, so a vanished record does not turn teardown into a
+* throw; a genuinely rejecting store is the caller's to react to — `onAbort` falls
+* through to destroying the sandbox, because a DESTROYED sandbox beats an
+* unreachable one, while the disconnect subscriber has nothing to fall back to
+* (the run is alive and still using the sandbox) and simply leaves the verdict
+* unpublished.
+*
+* The verdict is published ONLY on success. Publishing it after a failed record
+* write would leave core holding the log open for a takeover that can never be
+* found, since nothing in the store points at the run.
+*/
+async function recordDetach(definition, state, durability, ctx, phase) {
+	try {
+		await durability.runs.update(ctx.runId, {
+			detachedSince: Date.now(),
+			sandboxKey: definition.key(state.ensureCtx)
+		});
+	} catch (error) {
+		state.logger?.warn("sandbox detach record write failed", {
+			runId: ctx.runId,
+			phase,
+			error
+		});
+		return false;
+	}
+	provideRunDetached(ctx, true);
+	return true;
+}
+/**
+* Whether an out-of-band cancel has been recorded for this run, in EITHER band.
+* A user pressing Stop and a user closing the tab produce the IDENTICAL
+* connection close, so intent is never inferred from the disconnect itself: it
+* arrives in-process (the abort reason carried the cancel sentinel) or durably
+* (another host recorded it on the run record).
+*/
+async function cancelIntent(durability, runId, inProcess) {
+	if (inProcess) return true;
+	if (durability === void 0) return false;
+	return wasCancelRequested(durability.runs, runId);
 }
+/** Defensively pull tenant scoping out of the runtime context, if present. */
 function tenantFrom(context) {
-  if (context === null || typeof context !== "object") return void 0;
-  const c = context;
-  const userId = typeof c.userId === "string" ? c.userId : void 0;
-  const orgId = typeof c.orgId === "string" ? c.orgId : void 0;
-  if (userId === void 0 && orgId === void 0) return void 0;
-  return { userId, orgId };
+	if (context === null || typeof context !== "object") return void 0;
+	const c = context;
+	const userId = typeof c.userId === "string" ? c.userId : void 0;
+	const orgId = typeof c.orgId === "string" ? c.orgId : void 0;
+	if (userId === void 0 && orgId === void 0) return void 0;
+	return {
+		userId,
+		orgId
+	};
 }
-function buildEnsureCtx(ctx) {
-  return {
-    threadId: ctx.threadId,
-    runId: ctx.runId,
-    store: ctx.getOptional(SandboxStoreCapability),
-    locks: ctx.getOptional(LocksCapability),
-    tenant: tenantFrom(ctx.context),
-    signal: ctx.signal
-  };
+/**
+* Resolve the ensure seams. Precedence is explicit option → capability bus →
+* (in `ensure`) the in-memory fallback. The option wins because it is visible
+* at the call site; the bus remains for platform/framework injection.
+*/
+function buildEnsureCtx(ctx, options) {
+	return {
+		threadId: ctx.threadId,
+		runId: ctx.runId,
+		store: options?.instances ?? ctx.getOptional(SandboxInstanceStoreCapability),
+		locks: options?.locks ?? ctx.getOptional(LocksCapability),
+		tenant: tenantFrom(ctx.context),
+		signal: ctx.signal
+	};
 }
+/**
+* Dispatch a sandbox file event to the per-type hooks declared on the
+* definition. Errors in individual hooks are swallowed so one bad hook
+* cannot break the run — but are logged under the `errors` category first, so
+* a throwing hook is observable (matching the run-scoped path in the engine
+* and the behavior the observability docs promise).
+*/
 async function dispatchDefinitionHooks(hooks, event, logger) {
-  if (!hooks) return;
-  const typed = {
-    create: "onFileCreate",
-    change: "onFileChange",
-    delete: "onFileDelete"
-  }[event.type];
-  for (const fn of [hooks.onFile, hooks[typed]]) {
-    if (!fn) continue;
-    try {
-      await fn(event);
-    } catch (error) {
-      logger?.errors("sandbox file hook failed", {
-        path: event.path,
-        type: event.type,
-        error
-      });
-    }
-  }
+	if (!hooks) return;
+	const typed = {
+		create: "onFileCreate",
+		change: "onFileChange",
+		delete: "onFileDelete"
+	}[event.type];
+	for (const fn of [hooks.onFile, hooks[typed]]) {
+		if (!fn) continue;
+		try {
+			await fn(event);
+		} catch (error) {
+			logger?.errors("sandbox file hook failed", {
+				path: event.path,
+				type: event.type,
+				error
+			});
+		}
+	}
 }
-function withSandbox(definition) {
-  return defineChatMiddleware({
-    name: "sandbox",
-    provides: [SandboxCapability, ProjectionCapability],
-    // SandboxPolicyCapability is provided conditionally (only when the
-    // definition has a policy), so it is intentionally NOT declared here —
-    // consumers read it via `getOptional`.
-    optionalRequires: [SandboxStoreCapability, LocksCapability],
-    async setup(ctx) {
-      const ensureCtx = buildEnsureCtx(ctx);
-      const handle = await definition.ensure(ensureCtx);
-      provideSandbox(ctx, handle);
-      if (definition.policy) provideSandboxPolicy(ctx, definition.policy);
-      const runtime = getSandboxRuntime(ctx, { optional: true });
-      const logger = runtime?.logger;
-      const watchRoot = definition.workspace?.root ?? DEFAULT_WORKSPACE_ROOT;
-      let baseSha = "";
-      try {
-        const shaRes = await handle.process.exec("git rev-parse HEAD", {
-          cwd: watchRoot
-        });
-        if (shaRes.exitCode === 0) {
-          baseSha = shaRes.stdout.trim();
-          logger?.sandbox("sandbox git baseline captured", {
-            root: watchRoot,
-            baseSha
-          });
-        } else {
-          logger?.sandbox("sandbox git baseline unavailable (non-zero exit)", {
-            root: watchRoot,
-            exitCode: shaRes.exitCode,
-            stderr: shaRes.stderr
-          });
-        }
-      } catch (error) {
-        logger?.warn("sandbox git baseline capture failed", {
-          root: watchRoot,
-          error
-        });
-      }
-      const workspace = definition.workspace;
-      if (workspace !== void 0) {
-        const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT;
-        const workspaceHash = computeWorkspaceHash(workspace);
-        const secrets = workspace.secrets;
-        provideWorkspaceProjection(ctx, {
-          skills: workspace.skills ?? [],
-          plugins: workspace.plugins ?? [],
-          resolveSecret: (ref) => {
-            if (secrets === void 0) {
-              throw new Error(
-                `resolveSecret: no secrets defined on this workspace (ref: "${ref.__secretName}")`
-              );
-            }
-            return resolveSecret(secrets, ref);
-          },
-          markerPath: `${root}/.tanstack-projected-${workspaceHash}`,
-          root,
-          ...workspace.scripts !== void 0 ? { scripts: workspace.scripts } : {}
-        });
-      }
-      const hooks = definition.hooks;
-      await hooks?.onReady?.(handle);
-      const fe = resolveFileEvents(definition.fileEvents);
-      const pendingDiffs = [];
-      let watcher;
-      if (fe.enabled) {
-        watcher = await watchWorkspace(handle, {
-          onEvent: (event) => {
-            const enriched = buildFileHookEvent(
-              handle,
-              watchRoot,
-              baseSha,
-              event,
-              logger
-            );
-            void dispatchDefinitionHooks(hooks, enriched, logger);
-            runtime?.emit(enriched);
-            if (fe.diff) {
-              pendingDiffs.push(
-                enriched.diff().then((diff) => {
-                  runtime?.emitFileDiff({ path: event.path, diff });
-                }).catch((error) => {
-                  logger?.warn("sandbox file diff emit failed", {
-                    path: event.path,
-                    error
-                  });
-                })
-              );
-            }
-          },
-          // Watch the SAME root the enrichment layer relativizes against
-          // (`buildFileHookEvent(handle, watchRoot, …)` and the `baseSha`
-          // capture). Without this the watcher defaults to `/workspace` while
-          // enrichment uses `watchRoot`, so a custom `workspace.root` makes the
-          // two look at different directories and git pathspecs break.
-          root: watchRoot,
-          ...ctx.signal !== void 0 ? { signal: ctx.signal } : {},
-          ...logger !== void 0 ? { logger } : {}
-        });
-        logger?.sandbox("sandbox watcher started", {
-          root: watchRoot,
-          diff: fe.diff
-        });
-      }
-      runState.set(ctx, {
-        handle,
-        ensureCtx,
-        pendingDiffs,
-        ...watcher ? { watcher } : {},
-        ...logger !== void 0 ? { logger } : {}
-      });
-    },
-    async onFinish(ctx) {
-      const state = runState.get(ctx);
-      if (!state) return;
-      const { handle, ensureCtx } = state;
-      await drainWatcher(state, "finish");
-      const lifecycle = definition.lifecycle;
-      if (lifecycle?.snapshot === "after-run" && handle.capabilities.snapshots && handle.snapshot) {
-        const snapshot = await handle.snapshot(`after-run-${ctx.runId}`);
-        const store = ensureCtx.store;
-        if (store) {
-          const key = definition.key(ensureCtx);
-          const existing = await store.get(key);
-          if (existing) {
-            await store.upsert({
-              ...existing,
-              latestSnapshotId: snapshot.id,
-              updatedAt: Date.now()
-            });
-          }
-        }
-      }
-      if (lifecycle?.destroyOnComplete) {
-        await definition.destroy(ensureCtx);
-        await definition.hooks?.onDestroy?.();
-      }
-    },
-    async onAbort(ctx, _info) {
-      const state = runState.get(ctx);
-      if (!state) return;
-      await drainWatcher(state, "abort");
-      await definition.destroy(state.ensureCtx);
-      await definition.hooks?.onDestroy?.();
-    },
-    async onError(ctx, info) {
-      const state = runState.get(ctx);
-      if (!state) return;
-      await drainWatcher(state, "error");
-      await definition.hooks?.onError?.(info.error);
-      if (definition.lifecycle?.destroyOnComplete) {
-        await definition.destroy(state.ensureCtx);
-        await definition.hooks?.onDestroy?.();
-      }
-    }
-  });
+function withSandbox(definition, options) {
+	return defineChatMiddleware({
+		name: "sandbox",
+		provides: [SandboxCapability, ProjectionCapability],
+		optionalRequires: [SandboxInstanceStoreCapability, LocksCapability],
+		async setup(ctx) {
+			const ensureCtx = buildEnsureCtx(ctx, options);
+			const durability = resolveSandboxDurability(options);
+			if (durability !== void 0) {
+				provideSandboxDurability(ctx, durability);
+				provideDetachableRun(ctx, true);
+			}
+			const runtime = getSandboxRuntime(ctx, { optional: true });
+			const logger = runtime?.logger;
+			const state = {
+				ensureCtx,
+				pendingDiffs: [],
+				toolHistory: createToolHistoryRecorder(),
+				...logger ? { logger } : {},
+				...durability ? { durability } : {}
+			};
+			runState.set(ctx, state);
+			if (durability !== void 0) {
+				try {
+					await durability.runs.createOrResume({
+						runId: ctx.runId,
+						threadId: ctx.threadId,
+						startedAt: Date.now()
+					});
+				} catch (error) {
+					logger?.warn("sandbox run record pre-create failed", {
+						runId: ctx.runId,
+						error
+					});
+				}
+				try {
+					await getPendingTurn(ctx, { optional: true })?.snapshot();
+				} catch (error) {
+					logger?.warn("sandbox pending-turn snapshot failed", {
+						runId: ctx.runId,
+						error
+					});
+				}
+			}
+			if (durability !== void 0 && durability.detachOnDisconnect) getRunDisconnect(ctx, { optional: true })?.subscribe(async () => {
+				if (await cancelIntent(durability, ctx.runId, false)) return;
+				if (await recordDetach(definition, state, durability, ctx, "disconnect")) state.logger?.sandbox("sandbox run detached on disconnect; the run continues", { runId: ctx.runId });
+			});
+			const handle = await definition.ensure(ensureCtx);
+			state.handle = handle;
+			provideSandbox(ctx, handle);
+			if (definition.policy) provideSandboxPolicy(ctx, definition.policy);
+			if (durability !== void 0 && (ensureCtx.locks === void 0 || ensureCtx.locks instanceof InMemoryLockStore)) logger?.warn("sandbox durability is wired over an InMemoryLockStore: run claims are serialized within this process only and the lease never signals loss, so two hosts can drive one run and duplicate its event log. Use a distributed LockStore via withLocks for any multi-replica deploy.", { runId: ctx.runId });
+			const watchRoot = definition.workspace?.root ?? "/workspace";
+			let baseSha = "";
+			try {
+				const shaRes = await handle.process.exec("git rev-parse HEAD", { cwd: watchRoot });
+				if (shaRes.exitCode === 0) {
+					baseSha = shaRes.stdout.trim();
+					logger?.sandbox("sandbox git baseline captured", {
+						root: watchRoot,
+						baseSha
+					});
+				} else logger?.sandbox("sandbox git baseline unavailable (non-zero exit)", {
+					root: watchRoot,
+					exitCode: shaRes.exitCode,
+					stderr: shaRes.stderr
+				});
+			} catch (error) {
+				logger?.warn("sandbox git baseline capture failed", {
+					root: watchRoot,
+					error
+				});
+			}
+			const workspace = definition.workspace;
+			if (workspace !== void 0) {
+				const root = workspace.root ?? "/workspace";
+				const workspaceHash = computeWorkspaceHash(workspace);
+				const secrets = workspace.secrets;
+				provideWorkspaceProjection(ctx, {
+					skills: workspace.skills ?? [],
+					plugins: workspace.plugins ?? [],
+					resolveSecret: (ref) => {
+						if (secrets === void 0) throw new Error(`resolveSecret: no secrets defined on this workspace (ref: "${ref.__secretName}")`);
+						return resolveSecret(secrets, ref);
+					},
+					markerPath: `${root}/.tanstack-projected-${workspaceHash}`,
+					root,
+					...workspace.scripts !== void 0 ? { scripts: workspace.scripts } : {}
+				});
+			}
+			const hooks = definition.hooks;
+			await hooks?.onReady?.(handle);
+			const fe = resolveFileEvents(definition.fileEvents);
+			const pendingDiffs = state.pendingDiffs;
+			let watcher;
+			if (fe.enabled) {
+				watcher = await watchWorkspace(handle, {
+					onEvent: (event) => {
+						const enriched = buildFileHookEvent(handle, watchRoot, baseSha, event, logger);
+						dispatchDefinitionHooks(hooks, enriched, logger);
+						runtime?.emit(enriched);
+						if (fe.diff) pendingDiffs.push(enriched.diff().then((diff) => {
+							runtime?.emitFileDiff({
+								path: event.path,
+								diff
+							});
+						}).catch((error) => {
+							logger?.warn("sandbox file diff emit failed", {
+								path: event.path,
+								error
+							});
+						}));
+					},
+					root: watchRoot,
+					...ctx.signal !== void 0 ? { signal: ctx.signal } : {},
+					...logger !== void 0 ? { logger } : {}
+				});
+				logger?.sandbox("sandbox watcher started", {
+					root: watchRoot,
+					diff: fe.diff
+				});
+			}
+			if (watcher) state.watcher = watcher;
+		},
+		onConfig(_ctx, config) {
+			const messages = stripObservedToolCalls(config.messages);
+			if (messages.length === config.messages.length) return;
+			return { messages };
+		},
+		onIteration(ctx) {
+			runState.get(ctx)?.toolHistory.reconcile(ctx);
+		},
+		onChunk(ctx, chunk) {
+			runState.get(ctx)?.toolHistory.observe(chunk, ctx);
+		},
+		async onFinish(ctx) {
+			const state = runState.get(ctx);
+			if (!state) return;
+			const { handle, ensureCtx } = state;
+			state.toolHistory.reconcile(ctx);
+			await drainWatcher(state, "finish");
+			const lifecycle = definition.lifecycle;
+			if (lifecycle?.snapshot === "after-run" && handle?.capabilities.snapshots && handle.snapshot) {
+				const snapshot = await handle.snapshot(`after-run-${ctx.runId}`);
+				const store = ensureCtx.store;
+				if (store) {
+					const key = definition.key(ensureCtx);
+					const existing = await store.get(key);
+					if (existing) await store.upsert({
+						...existing,
+						latestSnapshotId: snapshot.id,
+						updatedAt: Date.now()
+					});
+				}
+			}
+			if (lifecycle?.destroyOnComplete) {
+				await definition.destroy(ensureCtx);
+				await definition.hooks?.onDestroy?.();
+			}
+		},
+		async onAbort(ctx, info) {
+			const state = runState.get(ctx);
+			if (!state) return;
+			await drainWatcher(state, "abort");
+			const durability = state.durability;
+			const cancelled = await cancelIntent(durability, ctx.runId, info.cancelRequested === true);
+			if (durability !== void 0 && !cancelled && durability.detachOnDisconnect) {
+				if (await recordDetach(definition, state, durability, ctx, "abort")) return;
+				await definition.destroy(state.ensureCtx);
+				await definition.hooks?.onDestroy?.();
+				return;
+			}
+			await definition.destroy(state.ensureCtx);
+			await definition.hooks?.onDestroy?.();
+		},
+		async onError(ctx, info) {
+			const state = runState.get(ctx);
+			if (!state) return;
+			await drainWatcher(state, "error");
+			await definition.hooks?.onError?.(info.error);
+			if (definition.lifecycle?.destroyOnComplete) {
+				await definition.destroy(state.ensureCtx);
+				await definition.hooks?.onDestroy?.();
+			}
+		}
+	});
 }
-export {
-  withSandbox
-};
-//# sourceMappingURL=middleware.js.map
+//#endregion
+export { withSandbox };
+
+//# sourceMappingURL=middleware.js.map