@tanstack/ai-sandbox 0.2.1 → 0.2.2

package/dist/esm/file-diff.d.ts

@@ -0,0 +1,16 @@
+import { SandboxFileEvent, SandboxFileHookEvent } from '@tanstack/ai';
+import { SandboxHandle } from './contracts.js';
+/**
+ * Wrap a raw {@link SandboxFileEvent} with lazy git-backed accessors bound to
+ * the live handle. `baseSha` is the session baseline (`''` when the workspace
+ * isn't a git repo). Never throws.
+ */
+export declare function buildFileHookEvent(handle: SandboxHandle, root: string, baseSha: string, event: SandboxFileEvent): SandboxFileHookEvent;
+export interface ResolvedFileEvents {
+    enabled: boolean;
+    diff: boolean;
+}
+/** Normalize the `fileEvents` option (`boolean | { diff?: boolean }`). */
+export declare function resolveFileEvents(opt: boolean | {
+    diff?: boolean;
+} | undefined): ResolvedFileEvents;

package/dist/esm/file-diff.js

@@ -0,0 +1,67 @@
+function relTo(root, path) {
+  const prefix = root.endsWith("/") ? root : `${root}/`;
+  return path.startsWith(prefix) ? path.slice(prefix.length) : path;
+}
+function q(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function synthesizeAddPatch(path, content) {
+  const lines = content === "" ? [] : content.replace(/\n$/, "").split("\n");
+  const body = lines.map((l) => `+${l}`).join("\n");
+  return `--- /dev/null
++++ ${path}
+@@ -0,0 +1,${lines.length} @@
+${body}${body ? "\n" : ""}`;
+}
+function buildFileHookEvent(handle, root, baseSha, event) {
+  const after = async () => {
+    if (event.type === "delete") return "";
+    try {
+      return await handle.fs.read(event.path);
+    } catch {
+      return "";
+    }
+  };
+  const before = async () => {
+    if (baseSha === "") return "";
+    const rel = relTo(root, event.path);
+    try {
+      const res = await handle.process.exec(
+        `git show ${q(baseSha)}:${q(rel)}`,
+        { cwd: root }
+      );
+      return res.exitCode === 0 ? res.stdout : "";
+    } catch {
+      return "";
+    }
+  };
+  const diff = async () => {
+    if (baseSha === "") {
+      if (event.type === "delete") return "";
+      return synthesizeAddPatch(event.path, await after());
+    }
+    const rel = relTo(root, event.path);
+    try {
+      const res = await handle.process.exec(
+        `git diff ${q(baseSha)} -- ${q(rel)}`,
+        {
+          cwd: root
+        }
+      );
+      return res.exitCode === 0 ? res.stdout : "";
+    } catch {
+      return "";
+    }
+  };
+  return { ...event, before, after, diff };
+}
+function resolveFileEvents(opt) {
+  if (opt === false) return { enabled: false, diff: false };
+  if (opt === void 0 || opt === true) return { enabled: true, diff: false };
+  return { enabled: true, diff: opt.diff === true };
+}
+export {
+  buildFileHookEvent,
+  resolveFileEvents
+};
+//# sourceMappingURL=file-diff.js.map

package/dist/esm/file-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-diff.js","sources":["../../src/file-diff.ts"],"sourcesContent":["import type { SandboxFileEvent, SandboxFileHookEvent } from '@tanstack/ai'\nimport type { SandboxHandle } from './contracts'\n\n/** Path relative to the repo/workspace root, POSIX form. */\nfunction relTo(root: string, path: string): string {\n  const prefix = root.endsWith('/') ? root : `${root}/`\n  return path.startsWith(prefix) ? path.slice(prefix.length) : path\n}\n\n/**\n * POSIX single-quote escape for embedding a value in a shell command.\n */\nfunction q(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`\n}\n\n/** Minimal unified add-patch for a brand-new file (non-git workspaces). */\nfunction synthesizeAddPatch(path: string, content: string): string {\n  const lines = content === '' ? [] : content.replace(/\\n$/, '').split('\\n')\n  const body = lines.map((l) => `+${l}`).join('\\n')\n  return `--- /dev/null\\n+++ ${path}\\n@@ -0,0 +1,${lines.length} @@\\n${body}${body ? '\\n' : ''}`\n}\n\n/**\n * Wrap a raw {@link SandboxFileEvent} with lazy git-backed accessors bound to\n * the live handle. `baseSha` is the session baseline (`''` when the workspace\n * isn't a git repo). Never throws.\n */\nexport function buildFileHookEvent(\n  handle: SandboxHandle,\n  root: string,\n  baseSha: string,\n  event: SandboxFileEvent,\n): SandboxFileHookEvent {\n  const after = async (): Promise<string> => {\n    if (event.type === 'delete') return ''\n    try {\n      return await handle.fs.read(event.path)\n    } catch {\n      return ''\n    }\n  }\n  const before = async (): Promise<string> => {\n    if (baseSha === '') return ''\n    const rel = relTo(root, event.path)\n    try {\n      const res = await handle.process.exec(\n        `git show ${q(baseSha)}:${q(rel)}`,\n        { cwd: root },\n      )\n      return res.exitCode === 0 ? res.stdout : ''\n    } catch {\n      return ''\n    }\n  }\n  const diff = async (): Promise<string> => {\n    if (baseSha === '') {\n      if (event.type === 'delete') return ''\n      return synthesizeAddPatch(event.path, await after())\n    }\n    // Pathspec must be relative to `root` (like `before()` above) — a bare\n    // leading `/` (e.g. the virtual `/workspace/x.ts`) is resolved by git\n    // against the filesystem root, not the repo root, and fails with\n    // \"fatal: Invalid path\" whenever the real repo root differs from\n    // `/workspace` (e.g. every local-process sandbox).\n    const rel = relTo(root, event.path)\n    try {\n      const res = await handle.process.exec(\n        `git diff ${q(baseSha)} -- ${q(rel)}`,\n        {\n          cwd: root,\n        },\n      )\n      return res.exitCode === 0 ? res.stdout : ''\n    } catch {\n      return ''\n    }\n  }\n  return { ...event, before, after, diff }\n}\n\nexport interface ResolvedFileEvents {\n  enabled: boolean\n  diff: boolean\n}\n\n/** Normalize the `fileEvents` option (`boolean | { diff?: boolean }`). */\nexport function resolveFileEvents(\n  opt: boolean | { diff?: boolean } | undefined,\n): ResolvedFileEvents {\n  if (opt === false) return { enabled: false, diff: false }\n  if (opt === undefined || opt === true) return { enabled: true, diff: false }\n  return { enabled: true, diff: opt.diff === true }\n}\n"],"names":[],"mappings":"AAIA,SAAS,MAAM,MAAc,MAAsB;AACjD,QAAM,SAAS,KAAK,SAAS,GAAG,IAAI,OAAO,GAAG,IAAI;AAClD,SAAO,KAAK,WAAW,MAAM,IAAI,KAAK,MAAM,OAAO,MAAM,IAAI;AAC/D;AAKA,SAAS,EAAE,OAAuB;AAChC,SAAO,IAAI,MAAM,QAAQ,MAAM,OAAO,CAAC;AACzC;AAGA,SAAS,mBAAmB,MAAc,SAAyB;AACjE,QAAM,QAAQ,YAAY,KAAK,KAAK,QAAQ,QAAQ,OAAO,EAAE,EAAE,MAAM,IAAI;AACzE,QAAM,OAAO,MAAM,IAAI,CAAC,MAAM,IAAI,CAAC,EAAE,EAAE,KAAK,IAAI;AAChD,SAAO;AAAA,MAAsB,IAAI;AAAA,aAAgB,MAAM,MAAM;AAAA,EAAQ,IAAI,GAAG,OAAO,OAAO,EAAE;AAC9F;AAOO,SAAS,mBACd,QACA,MACA,SACA,OACsB;AACtB,QAAM,QAAQ,YAA6B;AACzC,QAAI,MAAM,SAAS,SAAU,QAAO;AACpC,QAAI;AACF,aAAO,MAAM,OAAO,GAAG,KAAK,MAAM,IAAI;AAAA,IACxC,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AACA,QAAM,SAAS,YAA6B;AAC1C,QAAI,YAAY,GAAI,QAAO;AAC3B,UAAM,MAAM,MAAM,MAAM,MAAM,IAAI;AAClC,QAAI;AACF,YAAM,MAAM,MAAM,OAAO,QAAQ;AAAA,QAC/B,YAAY,EAAE,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC;AAAA,QAChC,EAAE,KAAK,KAAA;AAAA,MAAK;AAEd,aAAO,IAAI,aAAa,IAAI,IAAI,SAAS;AAAA,IAC3C,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AACA,QAAM,OAAO,YAA6B;AACxC,QAAI,YAAY,IAAI;AAClB,UAAI,MAAM,SAAS,SAAU,QAAO;AACpC,aAAO,mBAAmB,MAAM,MAAM,MAAM,OAAO;AAAA,IACrD;AAMA,UAAM,MAAM,MAAM,MAAM,MAAM,IAAI;AAClC,QAAI;AACF,YAAM,MAAM,MAAM,OAAO,QAAQ;AAAA,QAC/B,YAAY,EAAE,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;AAAA,QACnC;AAAA,UACE,KAAK;AAAA,QAAA;AAAA,MACP;AAEF,aAAO,IAAI,aAAa,IAAI,IAAI,SAAS;AAAA,IAC3C,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AACA,SAAO,EAAE,GAAG,OAAO,QAAQ,OAAO,KAAA;AACpC;AAQO,SAAS,kBACd,KACoB;AACpB,MAAI,QAAQ,MAAO,QAAO,EAAE,SAAS,OAAO,MAAM,MAAA;AAClD,MAAI,QAAQ,UAAa,QAAQ,aAAa,EAAE,SAAS,MAAM,MAAM,MAAA;AACrE,SAAO,EAAE,SAAS,MAAM,MAAM,IAAI,SAAS,KAAA;AAC7C;"}

package/dist/esm/middleware.js

@@ -2,6 +2,7 @@ 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 { ProjectionCapability, provideWorkspaceProjection } from "./projection.js";
 import { resolveSecret } from "./secrets.js";
 import { watchWorkspace } from "./watch.js";
@@ -53,6 +54,15 @@ function withSandbox(definition) {
       const handle = await definition.ensure(ensureCtx);
       provideSandbox(ctx, handle);
       if (definition.policy) provideSandboxPolicy(ctx, definition.policy);
+      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();
+      } catch {
+      }
       const workspace = definition.workspace;
       if (workspace !== void 0) {
         const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT;
@@ -76,24 +86,45 @@ function withSandbox(definition) {
       }
       const hooks = definition.hooks;
       await hooks?.onReady?.(handle);
+      const fe = resolveFileEvents(definition.fileEvents);
+      const pendingDiffs = [];
       let watcher;
-      if (definition.fileEvents !== false) {
+      if (fe.enabled) {
         const runtime = getSandboxRuntime(ctx, { optional: true });
         watcher = await watchWorkspace(handle, {
           onEvent: (event) => {
-            void dispatchDefinitionHooks(hooks, event);
-            runtime?.emit(event);
+            const enriched = buildFileHookEvent(
+              handle,
+              watchRoot,
+              baseSha,
+              event
+            );
+            void dispatchDefinitionHooks(hooks, enriched);
+            runtime?.emit(enriched);
+            if (fe.diff) {
+              pendingDiffs.push(
+                enriched.diff().then((diff) => {
+                  runtime?.emitFileDiff({ path: event.path, diff });
+                }).catch(() => void 0)
+              );
+            }
           },
           ...ctx.signal !== void 0 ? { signal: ctx.signal } : {}
         });
       }
-      runState.set(ctx, { handle, ensureCtx, ...watcher ? { watcher } : {} });
+      runState.set(ctx, {
+        handle,
+        ensureCtx,
+        pendingDiffs,
+        ...watcher ? { watcher } : {}
+      });
     },
     async onFinish(ctx) {
       const state = runState.get(ctx);
       if (!state) return;
       const { handle, ensureCtx } = state;
       await state.watcher?.stop();
+      await Promise.allSettled(state.pendingDiffs);
       const lifecycle = definition.lifecycle;
       if (lifecycle?.snapshot === "after-run" && handle.capabilities.snapshots && handle.snapshot) {
         const snapshot = await handle.snapshot(`after-run-${ctx.runId}`);
@@ -119,6 +150,7 @@ function withSandbox(definition) {
       const state = runState.get(ctx);
       if (!state) return;
       await state.watcher?.stop();
+      await Promise.allSettled(state.pendingDiffs);
       await definition.destroy(state.ensureCtx);
       await definition.hooks?.onDestroy?.();
     },
@@ -126,6 +158,7 @@ function withSandbox(definition) {
       const state = runState.get(ctx);
       if (!state) return;
       await state.watcher?.stop();
+      await Promise.allSettled(state.pendingDiffs);
       await definition.hooks?.onError?.(info.error);
       if (definition.lifecycle?.destroyOnComplete) {
         await definition.destroy(state.ensureCtx);

package/dist/esm/middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"middleware.js","sources":["../../src/middleware.ts"],"sourcesContent":["/**\n * `withSandbox(definition)` — the middleware that PROVIDES the\n * {@link SandboxCapability} a harness adapter requires.\n *\n * - `setup`: resume-or-create the sandbox (via the definition's ensure\n *   algorithm), provide the handle, using the optional SandboxStore/Locks\n *   capabilities when a persistence middleware supplied them (in-memory\n *   fallback otherwise). If `fileEvents` is not false, starts a watcher\n *   that dispatches to sandbox-scoped hooks and forwards to the runtime sink.\n * - `onFinish`/`onAbort`/`onError`: stop the watcher, snapshot (`after-run`)\n *   and/or destroy per lifecycle.\n *\n * NOTE: streamed sandbox lifecycle events (sandbox.created, workspace.setup.*)\n * are emitted by the harness adapter's chatStream (which can yield CUSTOM\n * chunks), not from here — middleware setup runs before streaming begins.\n */\nimport { defineChatMiddleware } from '@tanstack/ai'\nimport { getSandboxRuntime } from '@tanstack/ai/adapter-internals'\nimport {\n  LocksCapability,\n  SandboxCapability,\n  SandboxStoreCapability,\n  provideSandbox,\n  provideSandboxPolicy,\n} from './capabilities'\nimport { computeWorkspaceHash } from './key'\nimport { ProjectionCapability, provideWorkspaceProjection } from './projection'\nimport { resolveSecret } from './secrets'\nimport { watchWorkspace } from './watch'\nimport { DEFAULT_WORKSPACE_ROOT } from './bootstrap'\nimport type {\n  AbortInfo,\n  ChatMiddlewareContext,\n  DefinedChatMiddleware,\n  SandboxFileEvent,\n} from '@tanstack/ai'\nimport type { SandboxHandle } from './contracts'\nimport type {\n  SandboxDefinition,\n  SandboxEnsureContext,\n  SandboxHooks,\n} from './sandbox'\nimport type { SandboxWatchHandle } from './watch'\n\n/** Per-request state we need to carry from `setup` to the terminal hooks. */\ninterface SandboxRunState {\n  handle: SandboxHandle\n  ensureCtx: SandboxEnsureContext\n  watcher?: SandboxWatchHandle\n}\n\nconst runState = new WeakMap<object, SandboxRunState>()\n\n/** Defensively pull tenant scoping out of the runtime context, if present. */\nfunction tenantFrom(\n  context: unknown,\n): { userId?: string; orgId?: string } | undefined {\n  if (context === null || typeof context !== 'object') return undefined\n  const c = context as Record<string, unknown>\n  const userId = typeof c.userId === 'string' ? c.userId : undefined\n  const orgId = typeof c.orgId === 'string' ? c.orgId : undefined\n  if (userId === undefined && orgId === undefined) return undefined\n  return { userId, orgId }\n}\n\nfunction buildEnsureCtx(ctx: ChatMiddlewareContext): SandboxEnsureContext {\n  return {\n    threadId: ctx.threadId,\n    runId: ctx.runId,\n    store: ctx.getOptional(SandboxStoreCapability),\n    locks: ctx.getOptional(LocksCapability),\n    tenant: tenantFrom(ctx.context),\n    signal: ctx.signal,\n  }\n}\n\n/**\n * Dispatch a sandbox file event to the per-type hooks declared on the\n * definition. Errors in individual hooks are swallowed so one bad hook\n * cannot break the run.\n */\nasync function dispatchDefinitionHooks(\n  hooks: SandboxHooks | undefined,\n  event: SandboxFileEvent,\n): Promise<void> {\n  if (!hooks) return\n  const typed = (\n    {\n      create: 'onFileCreate',\n      change: 'onFileChange',\n      delete: 'onFileDelete',\n    } as const\n  )[event.type]\n  for (const fn of [hooks.onFile, hooks[typed]]) {\n    if (!fn) continue\n    try {\n      await fn(event)\n    } catch {\n      // swallowed — one bad hook must not break the run\n    }\n  }\n}\n\nexport function withSandbox(\n  definition: SandboxDefinition,\n): DefinedChatMiddleware<\n  unknown,\n  readonly [],\n  readonly [typeof SandboxCapability, typeof ProjectionCapability]\n> {\n  return defineChatMiddleware({\n    name: 'sandbox',\n    provides: [SandboxCapability, ProjectionCapability],\n    // SandboxPolicyCapability is provided conditionally (only when the\n    // definition has a policy), so it is intentionally NOT declared here —\n    // consumers read it via `getOptional`.\n    optionalRequires: [SandboxStoreCapability, LocksCapability],\n\n    async setup(ctx) {\n      const ensureCtx = buildEnsureCtx(ctx)\n      const handle = await definition.ensure(ensureCtx)\n      provideSandbox(ctx, handle)\n      if (definition.policy) provideSandboxPolicy(ctx, definition.policy)\n\n      const workspace = definition.workspace\n      if (workspace !== undefined) {\n        const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT\n        const workspaceHash = computeWorkspaceHash(workspace)\n        const secrets = workspace.secrets\n        provideWorkspaceProjection(ctx, {\n          skills: workspace.skills ?? [],\n          plugins: workspace.plugins ?? [],\n          resolveSecret: (ref) => {\n            if (secrets === undefined) {\n              throw new Error(\n                `resolveSecret: no secrets defined on this workspace (ref: \"${ref.__secretName}\")`,\n              )\n            }\n            return resolveSecret(secrets, ref)\n          },\n          markerPath: `${root}/.tanstack-projected-${workspaceHash}`,\n          root,\n          ...(workspace.scripts !== undefined\n            ? { scripts: workspace.scripts }\n            : {}),\n        })\n      }\n\n      const hooks = definition.hooks\n      await hooks?.onReady?.(handle)\n\n      let watcher: SandboxWatchHandle | undefined\n      if (definition.fileEvents !== false) {\n        const runtime = getSandboxRuntime(ctx, { optional: true })\n        watcher = await watchWorkspace(handle, {\n          onEvent: (event: SandboxFileEvent) => {\n            void dispatchDefinitionHooks(hooks, event)\n            runtime?.emit(event)\n          },\n          ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),\n        })\n      }\n\n      runState.set(ctx, { handle, ensureCtx, ...(watcher ? { watcher } : {}) })\n    },\n\n    async onFinish(ctx) {\n      const state = runState.get(ctx)\n      if (!state) return\n      const { handle, ensureCtx } = state\n\n      await state.watcher?.stop()\n\n      const lifecycle = definition.lifecycle\n\n      if (\n        lifecycle?.snapshot === 'after-run' &&\n        handle.capabilities.snapshots &&\n        handle.snapshot\n      ) {\n        const snapshot = await handle.snapshot(`after-run-${ctx.runId}`)\n        const store = ensureCtx.store\n        if (store) {\n          const key = definition.key(ensureCtx)\n          const existing = await store.get(key)\n          if (existing) {\n            await store.upsert({\n              ...existing,\n              latestSnapshotId: snapshot.id,\n              updatedAt: Date.now(),\n            })\n          }\n        }\n      }\n\n      if (lifecycle?.destroyOnComplete) {\n        await definition.destroy(ensureCtx)\n        await definition.hooks?.onDestroy?.()\n      }\n    },\n\n    async onAbort(ctx, _info: AbortInfo) {\n      const state = runState.get(ctx)\n      if (!state) return\n\n      await state.watcher?.stop()\n\n      // ALWAYS tear down on an explicit abort, regardless of `destroyOnComplete`.\n      // The in-sandbox agent process is not killed by closing its IO stream\n      // (e.g. a Docker exec survives client disconnect), so the only reliable way\n      // to stop it — and the token/cost drain of its ongoing API calls — is to\n      // destroy the sandbox (stop the container/VM). `keepAlive` /\n      // `destroyOnComplete:false` governs *successful completion*, never cancel.\n      await definition.destroy(state.ensureCtx)\n      await definition.hooks?.onDestroy?.()\n    },\n\n    async onError(ctx, info) {\n      const state = runState.get(ctx)\n      if (!state) return\n\n      await state.watcher?.stop()\n      await definition.hooks?.onError?.(info.error)\n\n      // On failure, only tear down when the lifecycle says so; otherwise leave\n      // the sandbox for a resumed retry.\n      if (definition.lifecycle?.destroyOnComplete) {\n        await definition.destroy(state.ensureCtx)\n        await definition.hooks?.onDestroy?.()\n      }\n    },\n  })\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"middleware.js","sources":["../../src/middleware.ts"],"sourcesContent":["/**\n * `withSandbox(definition)` — the middleware that PROVIDES the\n * {@link SandboxCapability} a harness adapter requires.\n *\n * - `setup`: resume-or-create the sandbox (via the definition's ensure\n *   algorithm), provide the handle, using the optional SandboxStore/Locks\n *   capabilities when a persistence middleware supplied them (in-memory\n *   fallback otherwise). If `fileEvents` is not false, starts a watcher\n *   that dispatches to sandbox-scoped hooks and forwards to the runtime sink.\n * - `onFinish`/`onAbort`/`onError`: stop the watcher, snapshot (`after-run`)\n *   and/or destroy per lifecycle.\n *\n * NOTE: streamed sandbox lifecycle events (sandbox.created, workspace.setup.*)\n * are emitted by the harness adapter's chatStream (which can yield CUSTOM\n * chunks), not from here — middleware setup runs before streaming begins.\n */\nimport { defineChatMiddleware } from '@tanstack/ai'\nimport { getSandboxRuntime } from '@tanstack/ai/adapter-internals'\nimport {\n  LocksCapability,\n  SandboxCapability,\n  SandboxStoreCapability,\n  provideSandbox,\n  provideSandboxPolicy,\n} from './capabilities'\nimport { computeWorkspaceHash } from './key'\nimport { buildFileHookEvent, resolveFileEvents } from './file-diff'\nimport { ProjectionCapability, provideWorkspaceProjection } from './projection'\nimport { resolveSecret } from './secrets'\nimport { watchWorkspace } from './watch'\nimport { DEFAULT_WORKSPACE_ROOT } from './bootstrap'\nimport type {\n  AbortInfo,\n  ChatMiddlewareContext,\n  DefinedChatMiddleware,\n  SandboxFileEvent,\n  SandboxFileHookEvent,\n} from '@tanstack/ai'\nimport type { SandboxHandle } from './contracts'\nimport type {\n  SandboxDefinition,\n  SandboxEnsureContext,\n  SandboxHooks,\n} from './sandbox'\nimport type { SandboxWatchHandle } from './watch'\n\n/** Per-request state we need to carry from `setup` to the terminal hooks. */\ninterface SandboxRunState {\n  handle: SandboxHandle\n  ensureCtx: SandboxEnsureContext\n  watcher?: SandboxWatchHandle\n  /** In-flight `enriched.diff()` promises queued by the `fileEvents.diff`\n   * watcher callback, awaited before teardown so a pending diff isn't\n   * dropped when the run finishes/aborts/errors mid-computation. */\n  pendingDiffs: Array<Promise<void>>\n}\n\nconst runState = new WeakMap<object, SandboxRunState>()\n\n/** Defensively pull tenant scoping out of the runtime context, if present. */\nfunction tenantFrom(\n  context: unknown,\n): { userId?: string; orgId?: string } | undefined {\n  if (context === null || typeof context !== 'object') return undefined\n  const c = context as Record<string, unknown>\n  const userId = typeof c.userId === 'string' ? c.userId : undefined\n  const orgId = typeof c.orgId === 'string' ? c.orgId : undefined\n  if (userId === undefined && orgId === undefined) return undefined\n  return { userId, orgId }\n}\n\nfunction buildEnsureCtx(ctx: ChatMiddlewareContext): SandboxEnsureContext {\n  return {\n    threadId: ctx.threadId,\n    runId: ctx.runId,\n    store: ctx.getOptional(SandboxStoreCapability),\n    locks: ctx.getOptional(LocksCapability),\n    tenant: tenantFrom(ctx.context),\n    signal: ctx.signal,\n  }\n}\n\n/**\n * Dispatch a sandbox file event to the per-type hooks declared on the\n * definition. Errors in individual hooks are swallowed so one bad hook\n * cannot break the run.\n */\nasync function dispatchDefinitionHooks(\n  hooks: SandboxHooks | undefined,\n  event: SandboxFileHookEvent,\n): Promise<void> {\n  if (!hooks) return\n  const typed = (\n    {\n      create: 'onFileCreate',\n      change: 'onFileChange',\n      delete: 'onFileDelete',\n    } as const\n  )[event.type]\n  for (const fn of [hooks.onFile, hooks[typed]]) {\n    if (!fn) continue\n    try {\n      await fn(event)\n    } catch {\n      // swallowed — one bad hook must not break the run\n    }\n  }\n}\n\nexport function withSandbox(\n  definition: SandboxDefinition,\n): DefinedChatMiddleware<\n  unknown,\n  readonly [],\n  readonly [typeof SandboxCapability, typeof ProjectionCapability]\n> {\n  return defineChatMiddleware({\n    name: 'sandbox',\n    provides: [SandboxCapability, ProjectionCapability],\n    // SandboxPolicyCapability is provided conditionally (only when the\n    // definition has a policy), so it is intentionally NOT declared here —\n    // consumers read it via `getOptional`.\n    optionalRequires: [SandboxStoreCapability, LocksCapability],\n\n    async setup(ctx) {\n      const ensureCtx = buildEnsureCtx(ctx)\n      const handle = await definition.ensure(ensureCtx)\n      provideSandbox(ctx, handle)\n      if (definition.policy) provideSandboxPolicy(ctx, definition.policy)\n\n      const watchRoot = definition.workspace?.root ?? DEFAULT_WORKSPACE_ROOT\n      let baseSha = ''\n      try {\n        const shaRes = await handle.process.exec('git rev-parse HEAD', {\n          cwd: watchRoot,\n        })\n        if (shaRes.exitCode === 0) baseSha = shaRes.stdout.trim()\n      } catch {\n        // non-git workspace / exec rejects → baseSha stays '' (accessors fall back)\n      }\n\n      const workspace = definition.workspace\n      if (workspace !== undefined) {\n        const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT\n        const workspaceHash = computeWorkspaceHash(workspace)\n        const secrets = workspace.secrets\n        provideWorkspaceProjection(ctx, {\n          skills: workspace.skills ?? [],\n          plugins: workspace.plugins ?? [],\n          resolveSecret: (ref) => {\n            if (secrets === undefined) {\n              throw new Error(\n                `resolveSecret: no secrets defined on this workspace (ref: \"${ref.__secretName}\")`,\n              )\n            }\n            return resolveSecret(secrets, ref)\n          },\n          markerPath: `${root}/.tanstack-projected-${workspaceHash}`,\n          root,\n          ...(workspace.scripts !== undefined\n            ? { scripts: workspace.scripts }\n            : {}),\n        })\n      }\n\n      const hooks = definition.hooks\n      await hooks?.onReady?.(handle)\n\n      const fe = resolveFileEvents(definition.fileEvents)\n      const pendingDiffs: Array<Promise<void>> = []\n      let watcher: SandboxWatchHandle | undefined\n      if (fe.enabled) {\n        const runtime = getSandboxRuntime(ctx, { optional: true })\n        watcher = await watchWorkspace(handle, {\n          onEvent: (event: SandboxFileEvent) => {\n            const enriched = buildFileHookEvent(\n              handle,\n              watchRoot,\n              baseSha,\n              event,\n            )\n            void dispatchDefinitionHooks(hooks, enriched)\n            runtime?.emit(enriched)\n            if (fe.diff) {\n              pendingDiffs.push(\n                enriched\n                  .diff()\n                  .then((diff) => {\n                    runtime?.emitFileDiff({ path: event.path, diff })\n                  })\n                  .catch(() => undefined),\n              )\n            }\n          },\n          ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),\n        })\n      }\n\n      runState.set(ctx, {\n        handle,\n        ensureCtx,\n        pendingDiffs,\n        ...(watcher ? { watcher } : {}),\n      })\n    },\n\n    async onFinish(ctx) {\n      const state = runState.get(ctx)\n      if (!state) return\n      const { handle, ensureCtx } = state\n\n      await state.watcher?.stop()\n      await Promise.allSettled(state.pendingDiffs)\n\n      const lifecycle = definition.lifecycle\n\n      if (\n        lifecycle?.snapshot === 'after-run' &&\n        handle.capabilities.snapshots &&\n        handle.snapshot\n      ) {\n        const snapshot = await handle.snapshot(`after-run-${ctx.runId}`)\n        const store = ensureCtx.store\n        if (store) {\n          const key = definition.key(ensureCtx)\n          const existing = await store.get(key)\n          if (existing) {\n            await store.upsert({\n              ...existing,\n              latestSnapshotId: snapshot.id,\n              updatedAt: Date.now(),\n            })\n          }\n        }\n      }\n\n      if (lifecycle?.destroyOnComplete) {\n        await definition.destroy(ensureCtx)\n        await definition.hooks?.onDestroy?.()\n      }\n    },\n\n    async onAbort(ctx, _info: AbortInfo) {\n      const state = runState.get(ctx)\n      if (!state) return\n\n      await state.watcher?.stop()\n      await Promise.allSettled(state.pendingDiffs)\n\n      // ALWAYS tear down on an explicit abort, regardless of `destroyOnComplete`.\n      // The in-sandbox agent process is not killed by closing its IO stream\n      // (e.g. a Docker exec survives client disconnect), so the only reliable way\n      // to stop it — and the token/cost drain of its ongoing API calls — is to\n      // destroy the sandbox (stop the container/VM). `keepAlive` /\n      // `destroyOnComplete:false` governs *successful completion*, never cancel.\n      await definition.destroy(state.ensureCtx)\n      await definition.hooks?.onDestroy?.()\n    },\n\n    async onError(ctx, info) {\n      const state = runState.get(ctx)\n      if (!state) return\n\n      await state.watcher?.stop()\n      await Promise.allSettled(state.pendingDiffs)\n      await definition.hooks?.onError?.(info.error)\n\n      // On failure, only tear down when the lifecycle says so; otherwise leave\n      // the sandbox for a resumed retry.\n      if (definition.lifecycle?.destroyOnComplete) {\n        await definition.destroy(state.ensureCtx)\n        await definition.hooks?.onDestroy?.()\n      }\n    },\n  })\n}\n"],"names":[],"mappings":";;;;;;;;;AAyDA,MAAM,+BAAe,QAAA;AAGrB,SAAS,WACP,SACiD;AACjD,MAAI,YAAY,QAAQ,OAAO,YAAY,SAAU,QAAO;AAC5D,QAAM,IAAI;AACV,QAAM,SAAS,OAAO,EAAE,WAAW,WAAW,EAAE,SAAS;AACzD,QAAM,QAAQ,OAAO,EAAE,UAAU,WAAW,EAAE,QAAQ;AACtD,MAAI,WAAW,UAAa,UAAU,OAAW,QAAO;AACxD,SAAO,EAAE,QAAQ,MAAA;AACnB;AAEA,SAAS,eAAe,KAAkD;AACxE,SAAO;AAAA,IACL,UAAU,IAAI;AAAA,IACd,OAAO,IAAI;AAAA,IACX,OAAO,IAAI,YAAY,sBAAsB;AAAA,IAC7C,OAAO,IAAI,YAAY,eAAe;AAAA,IACtC,QAAQ,WAAW,IAAI,OAAO;AAAA,IAC9B,QAAQ,IAAI;AAAA,EAAA;AAEhB;AAOA,eAAe,wBACb,OACA,OACe;AACf,MAAI,CAAC,MAAO;AACZ,QAAM,QACJ;AAAA,IACE,QAAQ;AAAA,IACR,QAAQ;AAAA,IACR,QAAQ;AAAA,EAAA,EAEV,MAAM,IAAI;AACZ,aAAW,MAAM,CAAC,MAAM,QAAQ,MAAM,KAAK,CAAC,GAAG;AAC7C,QAAI,CAAC,GAAI;AACT,QAAI;AACF,YAAM,GAAG,KAAK;AAAA,IAChB,QAAQ;AAAA,IAER;AAAA,EACF;AACF;AAEO,SAAS,YACd,YAKA;AACA,SAAO,qBAAqB;AAAA,IAC1B,MAAM;AAAA,IACN,UAAU,CAAC,mBAAmB,oBAAoB;AAAA;AAAA;AAAA;AAAA,IAIlD,kBAAkB,CAAC,wBAAwB,eAAe;AAAA,IAE1D,MAAM,MAAM,KAAK;AACf,YAAM,YAAY,eAAe,GAAG;AACpC,YAAM,SAAS,MAAM,WAAW,OAAO,SAAS;AAChD,qBAAe,KAAK,MAAM;AAC1B,UAAI,WAAW,OAAQ,sBAAqB,KAAK,WAAW,MAAM;AAElE,YAAM,YAAY,WAAW,WAAW,QAAQ;AAChD,UAAI,UAAU;AACd,UAAI;AACF,cAAM,SAAS,MAAM,OAAO,QAAQ,KAAK,sBAAsB;AAAA,UAC7D,KAAK;AAAA,QAAA,CACN;AACD,YAAI,OAAO,aAAa,EAAG,WAAU,OAAO,OAAO,KAAA;AAAA,MACrD,QAAQ;AAAA,MAER;AAEA,YAAM,YAAY,WAAW;AAC7B,UAAI,cAAc,QAAW;AAC3B,cAAM,OAAO,UAAU,QAAQ;AAC/B,cAAM,gBAAgB,qBAAqB,SAAS;AACpD,cAAM,UAAU,UAAU;AAC1B,mCAA2B,KAAK;AAAA,UAC9B,QAAQ,UAAU,UAAU,CAAA;AAAA,UAC5B,SAAS,UAAU,WAAW,CAAA;AAAA,UAC9B,eAAe,CAAC,QAAQ;AACtB,gBAAI,YAAY,QAAW;AACzB,oBAAM,IAAI;AAAA,gBACR,8DAA8D,IAAI,YAAY;AAAA,cAAA;AAAA,YAElF;AACA,mBAAO,cAAc,SAAS,GAAG;AAAA,UACnC;AAAA,UACA,YAAY,GAAG,IAAI,wBAAwB,aAAa;AAAA,UACxD;AAAA,UACA,GAAI,UAAU,YAAY,SACtB,EAAE,SAAS,UAAU,YACrB,CAAA;AAAA,QAAC,CACN;AAAA,MACH;AAEA,YAAM,QAAQ,WAAW;AACzB,YAAM,OAAO,UAAU,MAAM;AAE7B,YAAM,KAAK,kBAAkB,WAAW,UAAU;AAClD,YAAM,eAAqC,CAAA;AAC3C,UAAI;AACJ,UAAI,GAAG,SAAS;AACd,cAAM,UAAU,kBAAkB,KAAK,EAAE,UAAU,MAAM;AACzD,kBAAU,MAAM,eAAe,QAAQ;AAAA,UACrC,SAAS,CAAC,UAA4B;AACpC,kBAAM,WAAW;AAAA,cACf;AAAA,cACA;AAAA,cACA;AAAA,cACA;AAAA,YAAA;AAEF,iBAAK,wBAAwB,OAAO,QAAQ;AAC5C,qBAAS,KAAK,QAAQ;AACtB,gBAAI,GAAG,MAAM;AACX,2BAAa;AAAA,gBACX,SACG,KAAA,EACA,KAAK,CAAC,SAAS;AACd,2BAAS,aAAa,EAAE,MAAM,MAAM,MAAM,MAAM;AAAA,gBAClD,CAAC,EACA,MAAM,MAAM,MAAS;AAAA,cAAA;AAAA,YAE5B;AAAA,UACF;AAAA,UACA,GAAI,IAAI,WAAW,SAAY,EAAE,QAAQ,IAAI,WAAW,CAAA;AAAA,QAAC,CAC1D;AAAA,MACH;AAEA,eAAS,IAAI,KAAK;AAAA,QAChB;AAAA,QACA;AAAA,QACA;AAAA,QACA,GAAI,UAAU,EAAE,YAAY,CAAA;AAAA,MAAC,CAC9B;AAAA,IACH;AAAA,IAEA,MAAM,SAAS,KAAK;AAClB,YAAM,QAAQ,SAAS,IAAI,GAAG;AAC9B,UAAI,CAAC,MAAO;AACZ,YAAM,EAAE,QAAQ,UAAA,IAAc;AAE9B,YAAM,MAAM,SAAS,KAAA;AACrB,YAAM,QAAQ,WAAW,MAAM,YAAY;AAE3C,YAAM,YAAY,WAAW;AAE7B,UACE,WAAW,aAAa,eACxB,OAAO,aAAa,aACpB,OAAO,UACP;AACA,cAAM,WAAW,MAAM,OAAO,SAAS,aAAa,IAAI,KAAK,EAAE;AAC/D,cAAM,QAAQ,UAAU;AACxB,YAAI,OAAO;AACT,gBAAM,MAAM,WAAW,IAAI,SAAS;AACpC,gBAAM,WAAW,MAAM,MAAM,IAAI,GAAG;AACpC,cAAI,UAAU;AACZ,kBAAM,MAAM,OAAO;AAAA,cACjB,GAAG;AAAA,cACH,kBAAkB,SAAS;AAAA,cAC3B,WAAW,KAAK,IAAA;AAAA,YAAI,CACrB;AAAA,UACH;AAAA,QACF;AAAA,MACF;AAEA,UAAI,WAAW,mBAAmB;AAChC,cAAM,WAAW,QAAQ,SAAS;AAClC,cAAM,WAAW,OAAO,YAAA;AAAA,MAC1B;AAAA,IACF;AAAA,IAEA,MAAM,QAAQ,KAAK,OAAkB;AACnC,YAAM,QAAQ,SAAS,IAAI,GAAG;AAC9B,UAAI,CAAC,MAAO;AAEZ,YAAM,MAAM,SAAS,KAAA;AACrB,YAAM,QAAQ,WAAW,MAAM,YAAY;AAQ3C,YAAM,WAAW,QAAQ,MAAM,SAAS;AACxC,YAAM,WAAW,OAAO,YAAA;AAAA,IAC1B;AAAA,IAEA,MAAM,QAAQ,KAAK,MAAM;AACvB,YAAM,QAAQ,SAAS,IAAI,GAAG;AAC9B,UAAI,CAAC,MAAO;AAEZ,YAAM,MAAM,SAAS,KAAA;AACrB,YAAM,QAAQ,WAAW,MAAM,YAAY;AAC3C,YAAM,WAAW,OAAO,UAAU,KAAK,KAAK;AAI5C,UAAI,WAAW,WAAW,mBAAmB;AAC3C,cAAM,WAAW,QAAQ,MAAM,SAAS;AACxC,cAAM,WAAW,OAAO,YAAA;AAAA,MAC1B;AAAA,IACF;AAAA,EAAA,CACD;AACH;"}

package/dist/esm/sandbox.d.ts

@@ -1,4 +1,4 @@
-import { SandboxFileEvent } from '@tanstack/ai';
+import { SandboxFileHookEvent } from '@tanstack/ai';
 import { SandboxHandle, SandboxProvider } from './contracts.js';
 import { LockStore, SandboxStore } from './store.js';
 import { SandboxPolicy } from './policy.js';
@@ -8,10 +8,10 @@ import { WorkspaceDefinition } from './workspace.js';
  * create/change/delete during a chat run; lifecycle hooks fire server-side.
  */
 export interface SandboxHooks {
-    onFile?: (e: SandboxFileEvent) => void | Promise<void>;
-    onFileCreate?: (e: SandboxFileEvent) => void | Promise<void>;
-    onFileChange?: (e: SandboxFileEvent) => void | Promise<void>;
-    onFileDelete?: (e: SandboxFileEvent) => void | Promise<void>;
+    onFile?: (e: SandboxFileHookEvent) => void | Promise<void>;
+    onFileCreate?: (e: SandboxFileHookEvent) => void | Promise<void>;
+    onFileChange?: (e: SandboxFileHookEvent) => void | Promise<void>;
+    onFileDelete?: (e: SandboxFileHookEvent) => void | Promise<void>;
     onReady?: (handle: SandboxHandle) => void | Promise<void>;
     onError?: (err: unknown) => void | Promise<void>;
     onDestroy?: () => void | Promise<void>;
@@ -42,8 +42,11 @@ export interface SandboxConfig {
     lifecycle?: SandboxLifecycle;
     /** Sandbox-scoped file/lifecycle hooks. */
     hooks?: SandboxHooks;
-    /** Watch the workspace for file events (default true). Set false to disable. */
-    fileEvents?: boolean;
+    /** Watch the workspace for file events (default true). `false` disables the
+     *  watcher; `{ diff: true }` also emits a per-file `sandbox.file.diff` event. */
+    fileEvents?: boolean | {
+        diff?: boolean;
+    };
 }
 /** Context passed to `ensure()` by `withSandbox` (or advanced callers). */
 export interface SandboxEnsureContext {
@@ -67,8 +70,11 @@ export interface SandboxDefinition {
     readonly lifecycle?: SandboxLifecycle;
     /** Sandbox-scoped file/lifecycle hooks. */
     readonly hooks?: SandboxHooks;
-    /** Watch the workspace for file events (default true). Set false to disable. */
-    readonly fileEvents?: boolean;
+    /** Watch the workspace for file events (default true). `false` disables the
+     *  watcher; `{ diff: true }` also emits a per-file `sandbox.file.diff` event. */
+    readonly fileEvents?: boolean | {
+        diff?: boolean;
+    };
     /** Compound instance key for a given run context. */
     key: (ctx: SandboxEnsureContext) => string;
     /** Resume-or-create the sandbox for this thread/run. */

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 { SandboxFileEvent } 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: SandboxFileEvent) => void | Promise<void>\n  onFileCreate?: (e: SandboxFileEvent) => void | Promise<void>\n  onFileChange?: (e: SandboxFileEvent) => void | Promise<void>\n  onFileDelete?: (e: SandboxFileEvent) => 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). Set false to disable. */\n  fileEvents?: 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). Set false to disable. */\n  readonly fileEvents?: 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","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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"}

package/dist/esm/watch.js

@@ -16,11 +16,12 @@ function diffSnapshots(prev, next, timestamp) {
   }
   return events;
 }
-function buildFindCommand(root, ignore) {
+function buildFindCommand(ignore) {
   const prunes = ignore.map((entry) => `-not -path ${q(`*/${entry}/*`)}`).join(" ");
-  return `find ${q(root)} -type f ${prunes} -printf '%T@\\t%s\\t%p\\n'`;
+  return `find . -type f ${prunes} -printf '%T@\\t%s\\t%p\\n'`;
 }
-function parseFindOutput(stdout) {
+function parseFindOutput(stdout, root) {
+  const base = root.replace(/\/+$/, "");
   const snapshot = /* @__PURE__ */ new Map();
   for (const line of stdout.split("\n")) {
     if (line === "") continue;
@@ -29,7 +30,8 @@ function parseFindOutput(stdout) {
     if (firstTab === -1 || secondTab === -1) continue;
     const mtime = line.slice(0, firstTab);
     const size = line.slice(firstTab + 1, secondTab);
-    const path = line.slice(secondTab + 1);
+    const rel = line.slice(secondTab + 1).replace(/^\.\/?/, "");
+    const path = rel === "" ? base : `${base}/${rel}`;
     snapshot.set(path, `${mtime}	${size}`);
   }
   return snapshot;
@@ -81,14 +83,14 @@ async function startNativeWatch(handle, options) {
 }
 async function startPollWatch(handle, options) {
   const { onEvent, root, ignore, intervalMs } = options;
-  const command = buildFindCommand(root, ignore);
+  const command = buildFindCommand(ignore);
   const controller = new AbortController();
   const snapshot = async () => {
     const result = await handle.process.exec(command, {
       cwd: root,
       signal: controller.signal
     });
-    return result.exitCode === 0 ? parseFindOutput(result.stdout) : /* @__PURE__ */ new Map();
+    return result.exitCode === 0 ? parseFindOutput(result.stdout, root) : /* @__PURE__ */ new Map();
   };
   let previous = await snapshot();
   const state = { running: true };

package/dist/esm/watch.js.map

@@ -1 +1 @@
-{"version":3,"file":"watch.js","sources":["../../src/watch.ts"],"sourcesContent":["/**\n * Sandbox file-event hooks — observe create / change / delete of files inside a\n * sandbox (e.g. as an in-sandbox agent edits the workspace).\n *\n * Provider-agnostic: coded against the {@link SandboxHandle} contract only.\n * Two mechanisms, auto-selected:\n *\n * - **Native** — when a provider implements the optional `fs.watch` seam\n *   (local-process does, via Node `fs.watch`), OS events drive the feed with low\n *   latency.\n * - **Exec-poll** — otherwise (Docker, Cloudflare, any exec-only provider), a\n *   single `find … -printf` snapshot of `mtime\\tsize\\tpath` is taken every\n *   `intervalMs` and diffed. Works on any Linux container with GNU findutils\n *   (true for `node:*` / debian images) with no extra deps or image changes.\n *\n * The feed intentionally rides only the portable surface, so the same\n * `watchWorkspace` call behaves identically across providers.\n */\nimport { DEFAULT_WORKSPACE_ROOT } from './bootstrap'\nimport type { SandboxHandle } from './contracts'\nimport type { SandboxFileEvent } from '@tanstack/ai'\n\nexport type { SandboxFileEvent } from '@tanstack/ai'\n/** @deprecated alias retained for the low-level watch API. */\nexport type FileEvent = SandboxFileEvent\nexport type FileEventType = SandboxFileEvent['type']\n\nexport interface WatchOptions {\n  /** Called for every observed file event. */\n  onEvent: (event: SandboxFileEvent) => void\n  /** Workspace root to watch. Defaults to `/workspace`. */\n  root?: string\n  /** Poll interval for the exec-poll fallback, in ms. Defaults to 700. */\n  intervalMs?: number\n  /**\n   * Directory-name fragments to ignore (a path containing `/<entry>/` is\n   * skipped). Defaults to `['.git', 'node_modules']`.\n   */\n  ignore?: Array<string>\n  /** Stop watching when this signal aborts. */\n  signal?: AbortSignal\n}\n\nexport interface SandboxWatchHandle {\n  /** Stop the watcher and release its resources. */\n  stop: () => Promise<void>\n}\n\nconst DEFAULT_INTERVAL_MS = 700\nconst DEFAULT_IGNORE = ['.git', 'node_modules']\n\n/** POSIX single-quote escape for embedding values in a shell command. */\nfunction q(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`\n}\n\n/**\n * Diff two file snapshots (`Map<path, signature>`, signature = `mtime\\tsize`).\n * Pure — the heart of the exec-poll path, unit-tested in isolation.\n */\nexport function diffSnapshots(\n  prev: Map<string, string>,\n  next: Map<string, string>,\n  timestamp: number,\n): Array<SandboxFileEvent> {\n  const events: Array<SandboxFileEvent> = []\n  for (const [path, sig] of next) {\n    const before = prev.get(path)\n    if (before === undefined) events.push({ type: 'create', path, timestamp })\n    else if (before !== sig) events.push({ type: 'change', path, timestamp })\n  }\n  for (const path of prev.keys()) {\n    if (!next.has(path)) events.push({ type: 'delete', path, timestamp })\n  }\n  return events\n}\n\n/** Build the `find` command that prints `mtime\\tsize\\tpath` for every file. */\nfunction buildFindCommand(root: string, ignore: Array<string>): string {\n  const prunes = ignore\n    .map((entry) => `-not -path ${q(`*/${entry}/*`)}`)\n    .join(' ')\n  return `find ${q(root)} -type f ${prunes} -printf '%T@\\\\t%s\\\\t%p\\\\n'`\n}\n\n/** Parse `find -printf` output into a `Map<path, signature>`. */\nfunction parseFindOutput(stdout: string): Map<string, string> {\n  const snapshot = new Map<string, string>()\n  for (const line of stdout.split('\\n')) {\n    if (line === '') continue\n    const firstTab = line.indexOf('\\t')\n    const secondTab = line.indexOf('\\t', firstTab + 1)\n    if (firstTab === -1 || secondTab === -1) continue\n    const mtime = line.slice(0, firstTab)\n    const size = line.slice(firstTab + 1, secondTab)\n    const path = line.slice(secondTab + 1)\n    snapshot.set(path, `${mtime}\\t${size}`)\n  }\n  return snapshot\n}\n\n/** Whether a path should be ignored (contains a `/<entry>/` fragment). */\nfunction isIgnored(path: string, ignore: Array<string>): boolean {\n  return ignore.some((entry) => path.includes(`/${entry}/`))\n}\n\n/**\n * Start watching a sandbox workspace for file events. Picks the native\n * `fs.watch` fast-path when the provider advertises it, otherwise polls via\n * `find`. Returns a handle whose `stop()` tears everything down.\n */\nexport async function watchWorkspace(\n  handle: SandboxHandle,\n  options: WatchOptions,\n): Promise<SandboxWatchHandle> {\n  const root = options.root ?? DEFAULT_WORKSPACE_ROOT\n  const ignore = options.ignore ?? DEFAULT_IGNORE\n  const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS\n\n  // Already aborted before we start — don't begin any async work.\n  if (options.signal?.aborted) return { stop: () => Promise.resolve() }\n\n  if (handle.fs.watch) {\n    return startNativeWatch(handle, { ...options, root, ignore })\n  }\n  return startPollWatch(handle, { ...options, root, ignore, intervalMs })\n}\n\n/** Native fs.watch path: OS events, disambiguated against a known-path set. */\nasync function startNativeWatch(\n  handle: SandboxHandle,\n  options: WatchOptions & { root: string; ignore: Array<string> },\n): Promise<SandboxWatchHandle> {\n  const { onEvent, root, ignore } = options\n  const watch = handle.fs.watch\n  if (!watch) throw new Error('native watch is unavailable on this provider')\n  // Seed the set of existing files so the first event per path is classified\n  // correctly (create vs change).\n  const known = await collectPaths(handle, root, ignore)\n\n  const subscription = await watch(root, (raw) => {\n    const path = raw.path\n    if (isIgnored(path, ignore)) return\n    void (async () => {\n      const exists = await handle.fs.exists(path)\n      const timestamp = Date.now()\n      if (!exists) {\n        if (known.delete(path)) onEvent({ type: 'delete', path, timestamp })\n        return\n      }\n      if (known.has(path)) onEvent({ type: 'change', path, timestamp })\n      else {\n        known.add(path)\n        onEvent({ type: 'create', path, timestamp })\n      }\n    })().catch(() => undefined)\n  })\n\n  const onAbort = (): void => void subscription.stop().catch(() => undefined)\n  options.signal?.addEventListener('abort', onAbort, { once: true })\n  // The signal may have aborted during the awaits above (the once-listener\n  // would have missed it) — tear down now if so.\n  if (options.signal?.aborted) void subscription.stop().catch(() => undefined)\n\n  return {\n    stop: async () => {\n      options.signal?.removeEventListener('abort', onAbort)\n      await subscription.stop()\n    },\n  }\n}\n\n/** Exec-poll path: snapshot `find -printf` on an interval and diff. */\nasync function startPollWatch(\n  handle: SandboxHandle,\n  options: WatchOptions & {\n    root: string\n    ignore: Array<string>\n    intervalMs: number\n  },\n): Promise<SandboxWatchHandle> {\n  const { onEvent, root, ignore, intervalMs } = options\n  const command = buildFindCommand(root, ignore)\n  const controller = new AbortController()\n\n  const snapshot = async (): Promise<Map<string, string>> => {\n    const result = await handle.process.exec(command, {\n      cwd: root,\n      signal: controller.signal,\n    })\n    return result.exitCode === 0\n      ? parseFindOutput(result.stdout)\n      : new Map<string, string>()\n  }\n\n  let previous = await snapshot()\n  const state = { running: true }\n\n  const tick = async (): Promise<void> => {\n    if (!state.running) return\n    try {\n      const next = await snapshot()\n      for (const event of diffSnapshots(previous, next, Date.now())) {\n        onEvent(event)\n      }\n      previous = next\n    } catch {\n      // transient exec failure (e.g. mid-teardown) — try again next tick\n    }\n  }\n\n  const timer = setInterval(() => void tick(), intervalMs)\n  // Don't keep the event loop alive on the watcher alone.\n  if (typeof timer.unref === 'function') timer.unref()\n\n  const stop = (): Promise<void> => {\n    if (state.running) {\n      state.running = false\n      clearInterval(timer)\n      controller.abort()\n      options.signal?.removeEventListener('abort', onAbort)\n    }\n    return Promise.resolve()\n  }\n  const onAbort = (): void => void stop()\n  options.signal?.addEventListener('abort', onAbort, { once: true })\n  // The signal may have aborted during the initial `await snapshot()` above\n  // (the once-listener would have missed it) — tear down now if so.\n  if (options.signal?.aborted) void stop()\n\n  return { stop }\n}\n\n/** Recursively collect file paths under `root`, honoring `ignore`. */\nasync function collectPaths(\n  handle: SandboxHandle,\n  root: string,\n  ignore: Array<string>,\n): Promise<Set<string>> {\n  const files = new Set<string>()\n  const walk = async (dir: string): Promise<void> => {\n    let entries: Awaited<ReturnType<SandboxHandle['fs']['list']>>\n    try {\n      entries = await handle.fs.list(dir)\n    } catch {\n      return\n    }\n    for (const entry of entries) {\n      if (ignore.includes(entry.name)) continue\n      if (entry.type === 'dir') await walk(entry.path)\n      else files.add(entry.path)\n    }\n  }\n  await walk(root)\n  return files\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"watch.js","sources":["../../src/watch.ts"],"sourcesContent":["/**\n * Sandbox file-event hooks — observe create / change / delete of files inside a\n * sandbox (e.g. as an in-sandbox agent edits the workspace).\n *\n * Provider-agnostic: coded against the {@link SandboxHandle} contract only.\n * Two mechanisms, auto-selected:\n *\n * - **Native** — when a provider implements the optional `fs.watch` seam\n *   (local-process does, via Node `fs.watch`), OS events drive the feed with low\n *   latency.\n * - **Exec-poll** — otherwise (Docker, Cloudflare, any exec-only provider), a\n *   single `find … -printf` snapshot of `mtime\\tsize\\tpath` is taken every\n *   `intervalMs` and diffed. Works on any Linux container with GNU findutils\n *   (true for `node:*` / debian images) with no extra deps or image changes.\n *\n * The feed intentionally rides only the portable surface, so the same\n * `watchWorkspace` call behaves identically across providers.\n */\nimport { DEFAULT_WORKSPACE_ROOT } from './bootstrap'\nimport type { SandboxHandle } from './contracts'\nimport type { SandboxFileEvent } from '@tanstack/ai'\n\nexport type { SandboxFileEvent } from '@tanstack/ai'\n/** @deprecated alias retained for the low-level watch API. */\nexport type FileEvent = SandboxFileEvent\nexport type FileEventType = SandboxFileEvent['type']\n\nexport interface WatchOptions {\n  /** Called for every observed file event. */\n  onEvent: (event: SandboxFileEvent) => void\n  /** Workspace root to watch. Defaults to `/workspace`. */\n  root?: string\n  /** Poll interval for the exec-poll fallback, in ms. Defaults to 700. */\n  intervalMs?: number\n  /**\n   * Directory-name fragments to ignore (a path containing `/<entry>/` is\n   * skipped). Defaults to `['.git', 'node_modules']`.\n   */\n  ignore?: Array<string>\n  /** Stop watching when this signal aborts. */\n  signal?: AbortSignal\n}\n\nexport interface SandboxWatchHandle {\n  /** Stop the watcher and release its resources. */\n  stop: () => Promise<void>\n}\n\nconst DEFAULT_INTERVAL_MS = 700\nconst DEFAULT_IGNORE = ['.git', 'node_modules']\n\n/** POSIX single-quote escape for embedding values in a shell command. */\nfunction q(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`\n}\n\n/**\n * Diff two file snapshots (`Map<path, signature>`, signature = `mtime\\tsize`).\n * Pure — the heart of the exec-poll path, unit-tested in isolation.\n */\nexport function diffSnapshots(\n  prev: Map<string, string>,\n  next: Map<string, string>,\n  timestamp: number,\n): Array<SandboxFileEvent> {\n  const events: Array<SandboxFileEvent> = []\n  for (const [path, sig] of next) {\n    const before = prev.get(path)\n    if (before === undefined) events.push({ type: 'create', path, timestamp })\n    else if (before !== sig) events.push({ type: 'change', path, timestamp })\n  }\n  for (const path of prev.keys()) {\n    if (!next.has(path)) events.push({ type: 'delete', path, timestamp })\n  }\n  return events\n}\n\n/**\n * Build the `find` command that prints `mtime\\tsize\\tpath` for every file.\n * Searches `.` (relative to the exec `cwd`) rather than an absolute root: a\n * provider's `exec` maps only `cwd` onto the real filesystem, not literal path\n * arguments, so `find <virtual-root>` would look at a non-existent host path on\n * mapped-root providers (e.g. local-process). Emitted `%p` values are\n * root-normalized in {@link parseFindOutput}.\n */\nfunction buildFindCommand(ignore: Array<string>): string {\n  const prunes = ignore\n    .map((entry) => `-not -path ${q(`*/${entry}/*`)}`)\n    .join(' ')\n  return `find . -type f ${prunes} -printf '%T@\\\\t%s\\\\t%p\\\\n'`\n}\n\n/**\n * Parse `find -printf` output into a `Map<path, signature>`. `find .` prints\n * paths like `./sub/file`; map them back under `root` so event paths match the\n * native-watch shape (`<root>/sub/file`).\n */\nfunction parseFindOutput(stdout: string, root: string): Map<string, string> {\n  const base = root.replace(/\\/+$/, '')\n  const snapshot = new Map<string, string>()\n  for (const line of stdout.split('\\n')) {\n    if (line === '') continue\n    const firstTab = line.indexOf('\\t')\n    const secondTab = line.indexOf('\\t', firstTab + 1)\n    if (firstTab === -1 || secondTab === -1) continue\n    const mtime = line.slice(0, firstTab)\n    const size = line.slice(firstTab + 1, secondTab)\n    const rel = line.slice(secondTab + 1).replace(/^\\.\\/?/, '')\n    const path = rel === '' ? base : `${base}/${rel}`\n    snapshot.set(path, `${mtime}\\t${size}`)\n  }\n  return snapshot\n}\n\n/** Whether a path should be ignored (contains a `/<entry>/` fragment). */\nfunction isIgnored(path: string, ignore: Array<string>): boolean {\n  return ignore.some((entry) => path.includes(`/${entry}/`))\n}\n\n/**\n * Start watching a sandbox workspace for file events. Picks the native\n * `fs.watch` fast-path when the provider advertises it, otherwise polls via\n * `find`. Returns a handle whose `stop()` tears everything down.\n */\nexport async function watchWorkspace(\n  handle: SandboxHandle,\n  options: WatchOptions,\n): Promise<SandboxWatchHandle> {\n  const root = options.root ?? DEFAULT_WORKSPACE_ROOT\n  const ignore = options.ignore ?? DEFAULT_IGNORE\n  const intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS\n\n  // Already aborted before we start — don't begin any async work.\n  if (options.signal?.aborted) return { stop: () => Promise.resolve() }\n\n  if (handle.fs.watch) {\n    return startNativeWatch(handle, { ...options, root, ignore })\n  }\n  return startPollWatch(handle, { ...options, root, ignore, intervalMs })\n}\n\n/** Native fs.watch path: OS events, disambiguated against a known-path set. */\nasync function startNativeWatch(\n  handle: SandboxHandle,\n  options: WatchOptions & { root: string; ignore: Array<string> },\n): Promise<SandboxWatchHandle> {\n  const { onEvent, root, ignore } = options\n  const watch = handle.fs.watch\n  if (!watch) throw new Error('native watch is unavailable on this provider')\n  // Seed the set of existing files so the first event per path is classified\n  // correctly (create vs change).\n  const known = await collectPaths(handle, root, ignore)\n\n  const subscription = await watch(root, (raw) => {\n    const path = raw.path\n    if (isIgnored(path, ignore)) return\n    void (async () => {\n      const exists = await handle.fs.exists(path)\n      const timestamp = Date.now()\n      if (!exists) {\n        if (known.delete(path)) onEvent({ type: 'delete', path, timestamp })\n        return\n      }\n      if (known.has(path)) onEvent({ type: 'change', path, timestamp })\n      else {\n        known.add(path)\n        onEvent({ type: 'create', path, timestamp })\n      }\n    })().catch(() => undefined)\n  })\n\n  const onAbort = (): void => void subscription.stop().catch(() => undefined)\n  options.signal?.addEventListener('abort', onAbort, { once: true })\n  // The signal may have aborted during the awaits above (the once-listener\n  // would have missed it) — tear down now if so.\n  if (options.signal?.aborted) void subscription.stop().catch(() => undefined)\n\n  return {\n    stop: async () => {\n      options.signal?.removeEventListener('abort', onAbort)\n      await subscription.stop()\n    },\n  }\n}\n\n/** Exec-poll path: snapshot `find -printf` on an interval and diff. */\nasync function startPollWatch(\n  handle: SandboxHandle,\n  options: WatchOptions & {\n    root: string\n    ignore: Array<string>\n    intervalMs: number\n  },\n): Promise<SandboxWatchHandle> {\n  const { onEvent, root, ignore, intervalMs } = options\n  const command = buildFindCommand(ignore)\n  const controller = new AbortController()\n\n  const snapshot = async (): Promise<Map<string, string>> => {\n    const result = await handle.process.exec(command, {\n      cwd: root,\n      signal: controller.signal,\n    })\n    return result.exitCode === 0\n      ? parseFindOutput(result.stdout, root)\n      : new Map<string, string>()\n  }\n\n  let previous = await snapshot()\n  const state = { running: true }\n\n  const tick = async (): Promise<void> => {\n    if (!state.running) return\n    try {\n      const next = await snapshot()\n      for (const event of diffSnapshots(previous, next, Date.now())) {\n        onEvent(event)\n      }\n      previous = next\n    } catch {\n      // transient exec failure (e.g. mid-teardown) — try again next tick\n    }\n  }\n\n  const timer = setInterval(() => void tick(), intervalMs)\n  // Don't keep the event loop alive on the watcher alone.\n  if (typeof timer.unref === 'function') timer.unref()\n\n  const stop = (): Promise<void> => {\n    if (state.running) {\n      state.running = false\n      clearInterval(timer)\n      controller.abort()\n      options.signal?.removeEventListener('abort', onAbort)\n    }\n    return Promise.resolve()\n  }\n  const onAbort = (): void => void stop()\n  options.signal?.addEventListener('abort', onAbort, { once: true })\n  // The signal may have aborted during the initial `await snapshot()` above\n  // (the once-listener would have missed it) — tear down now if so.\n  if (options.signal?.aborted) void stop()\n\n  return { stop }\n}\n\n/** Recursively collect file paths under `root`, honoring `ignore`. */\nasync function collectPaths(\n  handle: SandboxHandle,\n  root: string,\n  ignore: Array<string>,\n): Promise<Set<string>> {\n  const files = new Set<string>()\n  const walk = async (dir: string): Promise<void> => {\n    let entries: Awaited<ReturnType<SandboxHandle['fs']['list']>>\n    try {\n      entries = await handle.fs.list(dir)\n    } catch {\n      return\n    }\n    for (const entry of entries) {\n      if (ignore.includes(entry.name)) continue\n      if (entry.type === 'dir') await walk(entry.path)\n      else files.add(entry.path)\n    }\n  }\n  await walk(root)\n  return files\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-sandbox",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Provider-agnostic sandbox layer for TanStack AI — run harness adapters inside isolated sandboxes (defineSandbox, defineWorkspace, withSandbox) with a uniform SandboxHandle, workspace bootstrap, policy, and resumable lifecycle.",
   "author": "",
   "license": "MIT",
@@ -44,7 +44,7 @@
   },
   "peerDependencies": {
     "@ngrok/ngrok": "^1.0.0",
-    "@tanstack/ai": "^0.39.1"
+    "@tanstack/ai": "^0.40.0"
   },
   "peerDependenciesMeta": {
     "@ngrok/ngrok": {
@@ -54,7 +54,7 @@
   "devDependencies": {
     "@ngrok/ngrok": "^1.7.0",
     "@vitest/coverage-v8": "4.0.14",
-    "@tanstack/ai": "0.39.1"
+    "@tanstack/ai": "0.40.0"
   },
   "scripts": {
     "build": "vite build",

package/src/file-diff.ts

@@ -0,0 +1,94 @@
+import type { SandboxFileEvent, SandboxFileHookEvent } from '@tanstack/ai'
+import type { SandboxHandle } from './contracts'
+
+/** Path relative to the repo/workspace root, POSIX form. */
+function relTo(root: string, path: string): string {
+  const prefix = root.endsWith('/') ? root : `${root}/`
+  return path.startsWith(prefix) ? path.slice(prefix.length) : path
+}
+
+/**
+ * POSIX single-quote escape for embedding a value in a shell command.
+ */
+function q(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+/** Minimal unified add-patch for a brand-new file (non-git workspaces). */
+function synthesizeAddPatch(path: string, content: string): string {
+  const lines = content === '' ? [] : content.replace(/\n$/, '').split('\n')
+  const body = lines.map((l) => `+${l}`).join('\n')
+  return `--- /dev/null\n+++ ${path}\n@@ -0,0 +1,${lines.length} @@\n${body}${body ? '\n' : ''}`
+}
+
+/**
+ * Wrap a raw {@link SandboxFileEvent} with lazy git-backed accessors bound to
+ * the live handle. `baseSha` is the session baseline (`''` when the workspace
+ * isn't a git repo). Never throws.
+ */
+export function buildFileHookEvent(
+  handle: SandboxHandle,
+  root: string,
+  baseSha: string,
+  event: SandboxFileEvent,
+): SandboxFileHookEvent {
+  const after = async (): Promise<string> => {
+    if (event.type === 'delete') return ''
+    try {
+      return await handle.fs.read(event.path)
+    } catch {
+      return ''
+    }
+  }
+  const before = async (): Promise<string> => {
+    if (baseSha === '') return ''
+    const rel = relTo(root, event.path)
+    try {
+      const res = await handle.process.exec(
+        `git show ${q(baseSha)}:${q(rel)}`,
+        { cwd: root },
+      )
+      return res.exitCode === 0 ? res.stdout : ''
+    } catch {
+      return ''
+    }
+  }
+  const diff = async (): Promise<string> => {
+    if (baseSha === '') {
+      if (event.type === 'delete') return ''
+      return synthesizeAddPatch(event.path, await after())
+    }
+    // Pathspec must be relative to `root` (like `before()` above) — a bare
+    // leading `/` (e.g. the virtual `/workspace/x.ts`) is resolved by git
+    // against the filesystem root, not the repo root, and fails with
+    // "fatal: Invalid path" whenever the real repo root differs from
+    // `/workspace` (e.g. every local-process sandbox).
+    const rel = relTo(root, event.path)
+    try {
+      const res = await handle.process.exec(
+        `git diff ${q(baseSha)} -- ${q(rel)}`,
+        {
+          cwd: root,
+        },
+      )
+      return res.exitCode === 0 ? res.stdout : ''
+    } catch {
+      return ''
+    }
+  }
+  return { ...event, before, after, diff }
+}
+
+export interface ResolvedFileEvents {
+  enabled: boolean
+  diff: boolean
+}
+
+/** Normalize the `fileEvents` option (`boolean | { diff?: boolean }`). */
+export function resolveFileEvents(
+  opt: boolean | { diff?: boolean } | undefined,
+): ResolvedFileEvents {
+  if (opt === false) return { enabled: false, diff: false }
+  if (opt === undefined || opt === true) return { enabled: true, diff: false }
+  return { enabled: true, diff: opt.diff === true }
+}

package/src/middleware.ts

@@ -24,6 +24,7 @@ import {
   provideSandboxPolicy,
 } from './capabilities'
 import { computeWorkspaceHash } from './key'
+import { buildFileHookEvent, resolveFileEvents } from './file-diff'
 import { ProjectionCapability, provideWorkspaceProjection } from './projection'
 import { resolveSecret } from './secrets'
 import { watchWorkspace } from './watch'
@@ -33,6 +34,7 @@ import type {
   ChatMiddlewareContext,
   DefinedChatMiddleware,
   SandboxFileEvent,
+  SandboxFileHookEvent,
 } from '@tanstack/ai'
 import type { SandboxHandle } from './contracts'
 import type {
@@ -47,6 +49,10 @@ interface SandboxRunState {
   handle: SandboxHandle
   ensureCtx: SandboxEnsureContext
   watcher?: SandboxWatchHandle
+  /** In-flight `enriched.diff()` promises queued by the `fileEvents.diff`
+   * watcher callback, awaited before teardown so a pending diff isn't
+   * dropped when the run finishes/aborts/errors mid-computation. */
+  pendingDiffs: Array<Promise<void>>
 }
 
 const runState = new WeakMap<object, SandboxRunState>()
@@ -81,7 +87,7 @@ function buildEnsureCtx(ctx: ChatMiddlewareContext): SandboxEnsureContext {
  */
 async function dispatchDefinitionHooks(
   hooks: SandboxHooks | undefined,
-  event: SandboxFileEvent,
+  event: SandboxFileHookEvent,
 ): Promise<void> {
   if (!hooks) return
   const typed = (
@@ -122,6 +128,17 @@ export function withSandbox(
       provideSandbox(ctx, handle)
       if (definition.policy) provideSandboxPolicy(ctx, definition.policy)
 
+      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()
+      } catch {
+        // non-git workspace / exec rejects → baseSha stays '' (accessors fall back)
+      }
+
       const workspace = definition.workspace
       if (workspace !== undefined) {
         const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT
@@ -149,19 +166,42 @@ export function withSandbox(
       const hooks = definition.hooks
       await hooks?.onReady?.(handle)
 
+      const fe = resolveFileEvents(definition.fileEvents)
+      const pendingDiffs: Array<Promise<void>> = []
       let watcher: SandboxWatchHandle | undefined
-      if (definition.fileEvents !== false) {
+      if (fe.enabled) {
         const runtime = getSandboxRuntime(ctx, { optional: true })
         watcher = await watchWorkspace(handle, {
           onEvent: (event: SandboxFileEvent) => {
-            void dispatchDefinitionHooks(hooks, event)
-            runtime?.emit(event)
+            const enriched = buildFileHookEvent(
+              handle,
+              watchRoot,
+              baseSha,
+              event,
+            )
+            void dispatchDefinitionHooks(hooks, enriched)
+            runtime?.emit(enriched)
+            if (fe.diff) {
+              pendingDiffs.push(
+                enriched
+                  .diff()
+                  .then((diff) => {
+                    runtime?.emitFileDiff({ path: event.path, diff })
+                  })
+                  .catch(() => undefined),
+              )
+            }
           },
           ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
         })
       }
 
-      runState.set(ctx, { handle, ensureCtx, ...(watcher ? { watcher } : {}) })
+      runState.set(ctx, {
+        handle,
+        ensureCtx,
+        pendingDiffs,
+        ...(watcher ? { watcher } : {}),
+      })
     },
 
     async onFinish(ctx) {
@@ -170,6 +210,7 @@ export function withSandbox(
       const { handle, ensureCtx } = state
 
       await state.watcher?.stop()
+      await Promise.allSettled(state.pendingDiffs)
 
       const lifecycle = definition.lifecycle
 
@@ -204,6 +245,7 @@ export function withSandbox(
       if (!state) return
 
       await state.watcher?.stop()
+      await Promise.allSettled(state.pendingDiffs)
 
       // ALWAYS tear down on an explicit abort, regardless of `destroyOnComplete`.
       // The in-sandbox agent process is not killed by closing its IO stream
@@ -220,6 +262,7 @@ export function withSandbox(
       if (!state) return
 
       await state.watcher?.stop()
+      await Promise.allSettled(state.pendingDiffs)
       await definition.hooks?.onError?.(info.error)
 
       // On failure, only tear down when the lifecycle says so; otherwise leave

package/src/sandbox.ts

@@ -10,7 +10,7 @@ import { bootstrapWorkspace } from './bootstrap'
 import { resolveAllSecrets } from './secrets'
 import { computeSandboxKey } from './key'
 import { InMemoryLockStore, InMemorySandboxStore } from './store'
-import type { SandboxFileEvent } from '@tanstack/ai'
+import type { SandboxFileHookEvent } from '@tanstack/ai'
 import type { SandboxHandle, SandboxProvider } from './contracts'
 import type { SandboxKeyInput } from './key'
 import type { LockStore, SandboxStore } from './store'
@@ -22,10 +22,10 @@ import type { WorkspaceDefinition } from './workspace'
  * create/change/delete during a chat run; lifecycle hooks fire server-side.
  */
 export interface SandboxHooks {
-  onFile?: (e: SandboxFileEvent) => void | Promise<void>
-  onFileCreate?: (e: SandboxFileEvent) => void | Promise<void>
-  onFileChange?: (e: SandboxFileEvent) => void | Promise<void>
-  onFileDelete?: (e: SandboxFileEvent) => void | Promise<void>
+  onFile?: (e: SandboxFileHookEvent) => void | Promise<void>
+  onFileCreate?: (e: SandboxFileHookEvent) => void | Promise<void>
+  onFileChange?: (e: SandboxFileHookEvent) => void | Promise<void>
+  onFileDelete?: (e: SandboxFileHookEvent) => void | Promise<void>
   onReady?: (handle: SandboxHandle) => void | Promise<void>
   onError?: (err: unknown) => void | Promise<void>
   onDestroy?: () => void | Promise<void>
@@ -59,8 +59,9 @@ export interface SandboxConfig {
   lifecycle?: SandboxLifecycle
   /** Sandbox-scoped file/lifecycle hooks. */
   hooks?: SandboxHooks
-  /** Watch the workspace for file events (default true). Set false to disable. */
-  fileEvents?: boolean
+  /** Watch the workspace for file events (default true). `false` disables the
+   *  watcher; `{ diff: true }` also emits a per-file `sandbox.file.diff` event. */
+  fileEvents?: boolean | { diff?: boolean }
 }
 
 /** Context passed to `ensure()` by `withSandbox` (or advanced callers). */
@@ -83,8 +84,9 @@ export interface SandboxDefinition {
   readonly lifecycle?: SandboxLifecycle
   /** Sandbox-scoped file/lifecycle hooks. */
   readonly hooks?: SandboxHooks
-  /** Watch the workspace for file events (default true). Set false to disable. */
-  readonly fileEvents?: boolean
+  /** Watch the workspace for file events (default true). `false` disables the
+   *  watcher; `{ diff: true }` also emits a per-file `sandbox.file.diff` event. */
+  readonly fileEvents?: boolean | { diff?: boolean }
   /** Compound instance key for a given run context. */
   key: (ctx: SandboxEnsureContext) => string
   /** Resume-or-create the sandbox for this thread/run. */

package/src/watch.ts

@@ -75,16 +75,28 @@ export function diffSnapshots(
   return events
 }
 
-/** Build the `find` command that prints `mtime\tsize\tpath` for every file. */
-function buildFindCommand(root: string, ignore: Array<string>): string {
+/**
+ * Build the `find` command that prints `mtime\tsize\tpath` for every file.
+ * Searches `.` (relative to the exec `cwd`) rather than an absolute root: a
+ * provider's `exec` maps only `cwd` onto the real filesystem, not literal path
+ * arguments, so `find <virtual-root>` would look at a non-existent host path on
+ * mapped-root providers (e.g. local-process). Emitted `%p` values are
+ * root-normalized in {@link parseFindOutput}.
+ */
+function buildFindCommand(ignore: Array<string>): string {
   const prunes = ignore
     .map((entry) => `-not -path ${q(`*/${entry}/*`)}`)
     .join(' ')
-  return `find ${q(root)} -type f ${prunes} -printf '%T@\\t%s\\t%p\\n'`
+  return `find . -type f ${prunes} -printf '%T@\\t%s\\t%p\\n'`
 }
 
-/** Parse `find -printf` output into a `Map<path, signature>`. */
-function parseFindOutput(stdout: string): Map<string, string> {
+/**
+ * Parse `find -printf` output into a `Map<path, signature>`. `find .` prints
+ * paths like `./sub/file`; map them back under `root` so event paths match the
+ * native-watch shape (`<root>/sub/file`).
+ */
+function parseFindOutput(stdout: string, root: string): Map<string, string> {
+  const base = root.replace(/\/+$/, '')
   const snapshot = new Map<string, string>()
   for (const line of stdout.split('\n')) {
     if (line === '') continue
@@ -93,7 +105,8 @@ function parseFindOutput(stdout: string): Map<string, string> {
     if (firstTab === -1 || secondTab === -1) continue
     const mtime = line.slice(0, firstTab)
     const size = line.slice(firstTab + 1, secondTab)
-    const path = line.slice(secondTab + 1)
+    const rel = line.slice(secondTab + 1).replace(/^\.\/?/, '')
+    const path = rel === '' ? base : `${base}/${rel}`
     snapshot.set(path, `${mtime}\t${size}`)
   }
   return snapshot
@@ -180,7 +193,7 @@ async function startPollWatch(
   },
 ): Promise<SandboxWatchHandle> {
   const { onEvent, root, ignore, intervalMs } = options
-  const command = buildFindCommand(root, ignore)
+  const command = buildFindCommand(ignore)
   const controller = new AbortController()
 
   const snapshot = async (): Promise<Map<string, string>> => {
@@ -189,7 +202,7 @@ async function startPollWatch(
       signal: controller.signal,
     })
     return result.exitCode === 0
-      ? parseFindOutput(result.stdout)
+      ? parseFindOutput(result.stdout, root)
       : new Map<string, string>()
   }