@tanstack/ai-sandbox 0.2.4 → 0.3.0

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

@@ -1 +1 @@
-{"version":3,"file":"file-diff.js","sources":["../../src/file-diff.ts"],"sourcesContent":["import type { SandboxFileEvent, SandboxFileHookEvent } from '@tanstack/ai'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\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/**\n * Unified add-patch for a brand-new file, closely following the shape `git\n * diff` produces for an added file (`diff --git` header + `new file mode` +\n * `--- /dev/null` + `+++ b/<rel>`), so synthesized `create` diffs align with\n * the real `git diff` output emitted for `change` events. `rel` must be the\n * repo-root-relative POSIX path (like git's). Reproduces git's `\\ No newline\n * at end of file` marker and the header-only form for a zero-byte file, so a\n * consumer applying the patch reconstructs the file byte-for-byte. It is not\n * byte-identical to git — it omits the `index <hash>..<hash>` line and always\n * writes the `+1,N` hunk count (git omits `,1`) — but both are valid\n * unified-diff and accepted by `git apply`/`patch`.\n */\nfunction synthesizeAddPatch(rel: string, content: string): string {\n  const header = `diff --git a/${rel} b/${rel}\\nnew file mode 100644\\n`\n  // A zero-byte new file has no hunk in git's output — just the header.\n  if (content === '') return header\n  const hasFinalNewline = content.endsWith('\\n')\n  const lines = content.replace(/\\n$/, '').split('\\n')\n  const body = lines.map((l) => `+${l}`).join('\\n')\n  return (\n    header +\n    `--- /dev/null\\n` +\n    `+++ b/${rel}\\n` +\n    `@@ -0,0 +1,${lines.length} @@\\n` +\n    body +\n    (hasFinalNewline ? '\\n' : '\\n\\\\\n')\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 — every git/fs failure falls back to `''`\n * (or a synthesized add-patch), but is logged first via `logger` so a failure\n * is observable instead of silently becoming empty data.\n */\nexport function buildFileHookEvent(\n  handle: SandboxHandle,\n  root: string,\n  baseSha: string,\n  event: SandboxFileEvent,\n  logger?: InternalLogger,\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 (error) {\n      logger?.warn('sandbox after() failed to read file', {\n        path: event.path,\n        error,\n      })\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      if (res.exitCode === 0) return res.stdout\n      // Non-zero exit is EXPECTED when the file didn't exist at the baseline\n      // (a newly created file) — git exits 128 with \"exists on disk, but not\n      // in <sha>\". Log under `sandbox` (off by default) rather than warn so a\n      // create event's before() doesn't spam a warning on every new file.\n      logger?.sandbox('before() git show non-zero exit', {\n        path: event.path,\n        exitCode: res.exitCode,\n        stderr: res.stderr,\n      })\n      return ''\n    } catch (error) {\n      logger?.warn('sandbox before() git show failed', {\n        path: event.path,\n        error,\n      })\n      return ''\n    }\n  }\n  // Empty `git diff` fallback: `git diff <sha> -- <path>` shows nothing for a\n  // file git isn't tracking, so an untracked file (the common agent action —\n  // and every subsequent edit to it, which arrives as a `change`, not just the\n  // first `create`) yields empty stdout even though it has content. Synthesize\n  // an add-patch, but ONLY when the file is genuinely untracked at the\n  // baseline — an empty diff for a *tracked* file means \"identical to\n  // baseline\", a real no-op that must stay empty. Presence at `baseSha`\n  // distinguishes them, probed below via the `git show` EXIT CODE (NOT\n  // `before()`'s `''`, which also means \"git show threw\" — see the inline note).\n  // ponytail: reached only when `git diff` came back empty — the common case\n  // for an untracked file (and every edit to it), rare for a tracked one. It\n  // spends up to two extra subprocesses (`git check-ignore`, then `git show`)\n  // plus one `after()` read per such event; both verdicts are invariant per\n  // path across a run, but memoizing them would need cross-event state the\n  // per-event accessor doesn't hold. Add a per-path cache in the watcher if\n  // edit-burst latency matters.\n  const synthesizeIfUntracked = async (rel: string): Promise<string> => {\n    const content = await after()\n    if (content === '') return '' // deleted / empty / unreadable — nothing to add\n    // Don't expose the CONTENTS of a git-ignored file (`.env`, credentials,\n    // build artifacts, …) in the diff feed. The file event still fires so\n    // consumers are notified it changed — only its diff is withheld. A\n    // force-added, ignored-yet-TRACKED file produces a non-empty `git diff`\n    // above and never reaches here, so its real diff is unaffected.\n    try {\n      const ignored = await handle.process.exec(\n        `git check-ignore -q -- ${q(rel)}`,\n        { cwd: root },\n      )\n      // check-ignore: exit 0 ⇒ path is ignored; 1 ⇒ not ignored; 128 ⇒ error.\n      if (ignored.exitCode === 0) {\n        logger?.sandbox('sandbox diff() withheld for git-ignored file', {\n          path: event.path,\n        })\n        return ''\n      }\n      if (ignored.exitCode !== 1) {\n        // Not the expected \"not ignored\" (1) — a real check-ignore error (128:\n        // corrupt repo, bad invocation). Same anomaly class as the throw below,\n        // so `warn`. We still fall through and diff, so a broken probe never\n        // silently withholds; but log it, or an error here would look exactly\n        // like \"not ignored\" and could expose a would-be-withheld file's diff.\n        logger?.warn('sandbox diff() git check-ignore non-zero exit', {\n          path: event.path,\n          exitCode: ignored.exitCode,\n          stderr: ignored.stderr,\n        })\n      }\n    } catch (error) {\n      // check-ignore threw (git/exec broken) — same anomaly class as the other\n      // git execs here, so `warn`. We fall through and diff as usual rather\n      // than withhold, so a broken probe can't hide a legitimate diff.\n      logger?.warn('sandbox diff() git check-ignore failed', {\n        path: event.path,\n        error,\n      })\n    }\n    // Distinguish \"absent at the baseline (untracked)\" from \"present at the\n    // baseline\" by the git-show EXIT CODE, not by before()'s `''` — which also\n    // means \"git show threw\". Conflating a transient git-show failure with\n    // untracked would fabricate a full-file add-patch for an unchanged tracked\n    // file the agent never touched.\n    try {\n      const res = await handle.process.exec(\n        `git show ${q(baseSha)}:${q(rel)}`,\n        { cwd: root },\n      )\n      // exit 0 ⇒ tracked; `git diff` was already empty ⇒ identical to baseline\n      // ⇒ genuine no-op.\n      if (res.exitCode === 0) return ''\n      // Non-zero is the EXPECTED \"absent at baseline ⇒ untracked\" case (exit\n      // 128), but a genuine git-show error (bad object, corrupt repo, invalid\n      // sha) also exits non-zero and would silently fabricate a full-file\n      // add-patch. Log it under `sandbox` (like `before()` does) so a\n      // persistent probe error is greppable, then fall back to synthesize.\n      logger?.sandbox(\n        'sandbox diff() tracked-ness probe non-zero exit (treating as untracked)',\n        { path: event.path, exitCode: res.exitCode, stderr: res.stderr },\n      )\n      return synthesizeAddPatch(rel, content)\n    } catch (error) {\n      // Uncertain — don't fabricate a full-file add-patch on a probe failure.\n      logger?.warn('sandbox diff() tracked-ness probe failed', {\n        path: event.path,\n        error,\n      })\n      return ''\n    }\n  }\n  const diff = async (): Promise<string> => {\n    if (baseSha === '') {\n      if (event.type === 'delete') return ''\n      return synthesizeAddPatch(relTo(root, 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      if (res.exitCode !== 0) {\n        logger?.warn('sandbox diff() git diff non-zero exit', {\n          path: event.path,\n          exitCode: res.exitCode,\n          stderr: res.stderr,\n        })\n        return ''\n      }\n      if (res.stdout !== '') return res.stdout\n      return synthesizeIfUntracked(rel)\n    } catch (error) {\n      logger?.warn('sandbox diff() git diff failed', {\n        path: event.path,\n        error,\n      })\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":"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"}
+{"version":3,"file":"file-diff.js","names":[],"sources":["../../src/file-diff.ts"],"sourcesContent":["import type { SandboxFileEvent, SandboxFileHookEvent } from '@tanstack/ai'\nimport type { InternalLogger } from '@tanstack/ai/adapter-internals'\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/**\n * Unified add-patch for a brand-new file, closely following the shape `git\n * diff` produces for an added file (`diff --git` header + `new file mode` +\n * `--- /dev/null` + `+++ b/<rel>`), so synthesized `create` diffs align with\n * the real `git diff` output emitted for `change` events. `rel` must be the\n * repo-root-relative POSIX path (like git's). Reproduces git's `\\ No newline\n * at end of file` marker and the header-only form for a zero-byte file, so a\n * consumer applying the patch reconstructs the file byte-for-byte. It is not\n * byte-identical to git — it omits the `index <hash>..<hash>` line and always\n * writes the `+1,N` hunk count (git omits `,1`) — but both are valid\n * unified-diff and accepted by `git apply`/`patch`.\n */\nfunction synthesizeAddPatch(rel: string, content: string): string {\n  const header = `diff --git a/${rel} b/${rel}\\nnew file mode 100644\\n`\n  // A zero-byte new file has no hunk in git's output — just the header.\n  if (content === '') return header\n  const hasFinalNewline = content.endsWith('\\n')\n  const lines = content.replace(/\\n$/, '').split('\\n')\n  const body = lines.map((l) => `+${l}`).join('\\n')\n  return (\n    header +\n    `--- /dev/null\\n` +\n    `+++ b/${rel}\\n` +\n    `@@ -0,0 +1,${lines.length} @@\\n` +\n    body +\n    (hasFinalNewline ? '\\n' : '\\n\\\\\n')\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 — every git/fs failure falls back to `''`\n * (or a synthesized add-patch), but is logged first via `logger` so a failure\n * is observable instead of silently becoming empty data.\n */\nexport function buildFileHookEvent(\n  handle: SandboxHandle,\n  root: string,\n  baseSha: string,\n  event: SandboxFileEvent,\n  logger?: InternalLogger,\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 (error) {\n      logger?.warn('sandbox after() failed to read file', {\n        path: event.path,\n        error,\n      })\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      if (res.exitCode === 0) return res.stdout\n      // Non-zero exit is EXPECTED when the file didn't exist at the baseline\n      // (a newly created file) — git exits 128 with \"exists on disk, but not\n      // in <sha>\". Log under `sandbox` (off by default) rather than warn so a\n      // create event's before() doesn't spam a warning on every new file.\n      logger?.sandbox('before() git show non-zero exit', {\n        path: event.path,\n        exitCode: res.exitCode,\n        stderr: res.stderr,\n      })\n      return ''\n    } catch (error) {\n      logger?.warn('sandbox before() git show failed', {\n        path: event.path,\n        error,\n      })\n      return ''\n    }\n  }\n  // Empty `git diff` fallback: `git diff <sha> -- <path>` shows nothing for a\n  // file git isn't tracking, so an untracked file (the common agent action —\n  // and every subsequent edit to it, which arrives as a `change`, not just the\n  // first `create`) yields empty stdout even though it has content. Synthesize\n  // an add-patch, but ONLY when the file is genuinely untracked at the\n  // baseline — an empty diff for a *tracked* file means \"identical to\n  // baseline\", a real no-op that must stay empty. Presence at `baseSha`\n  // distinguishes them, probed below via the `git show` EXIT CODE (NOT\n  // `before()`'s `''`, which also means \"git show threw\" — see the inline note).\n  // ponytail: reached only when `git diff` came back empty — the common case\n  // for an untracked file (and every edit to it), rare for a tracked one. It\n  // spends up to two extra subprocesses (`git check-ignore`, then `git show`)\n  // plus one `after()` read per such event; both verdicts are invariant per\n  // path across a run, but memoizing them would need cross-event state the\n  // per-event accessor doesn't hold. Add a per-path cache in the watcher if\n  // edit-burst latency matters.\n  const synthesizeIfUntracked = async (rel: string): Promise<string> => {\n    const content = await after()\n    if (content === '') return '' // deleted / empty / unreadable — nothing to add\n    // Don't expose the CONTENTS of a git-ignored file (`.env`, credentials,\n    // build artifacts, …) in the diff feed. The file event still fires so\n    // consumers are notified it changed — only its diff is withheld. A\n    // force-added, ignored-yet-TRACKED file produces a non-empty `git diff`\n    // above and never reaches here, so its real diff is unaffected.\n    try {\n      const ignored = await handle.process.exec(\n        `git check-ignore -q -- ${q(rel)}`,\n        { cwd: root },\n      )\n      // check-ignore: exit 0 ⇒ path is ignored; 1 ⇒ not ignored; 128 ⇒ error.\n      if (ignored.exitCode === 0) {\n        logger?.sandbox('sandbox diff() withheld for git-ignored file', {\n          path: event.path,\n        })\n        return ''\n      }\n      if (ignored.exitCode !== 1) {\n        // Not the expected \"not ignored\" (1) — a real check-ignore error (128:\n        // corrupt repo, bad invocation). Same anomaly class as the throw below,\n        // so `warn`. We still fall through and diff, so a broken probe never\n        // silently withholds; but log it, or an error here would look exactly\n        // like \"not ignored\" and could expose a would-be-withheld file's diff.\n        logger?.warn('sandbox diff() git check-ignore non-zero exit', {\n          path: event.path,\n          exitCode: ignored.exitCode,\n          stderr: ignored.stderr,\n        })\n      }\n    } catch (error) {\n      // check-ignore threw (git/exec broken) — same anomaly class as the other\n      // git execs here, so `warn`. We fall through and diff as usual rather\n      // than withhold, so a broken probe can't hide a legitimate diff.\n      logger?.warn('sandbox diff() git check-ignore failed', {\n        path: event.path,\n        error,\n      })\n    }\n    // Distinguish \"absent at the baseline (untracked)\" from \"present at the\n    // baseline\" by the git-show EXIT CODE, not by before()'s `''` — which also\n    // means \"git show threw\". Conflating a transient git-show failure with\n    // untracked would fabricate a full-file add-patch for an unchanged tracked\n    // file the agent never touched.\n    try {\n      const res = await handle.process.exec(\n        `git show ${q(baseSha)}:${q(rel)}`,\n        { cwd: root },\n      )\n      // exit 0 ⇒ tracked; `git diff` was already empty ⇒ identical to baseline\n      // ⇒ genuine no-op.\n      if (res.exitCode === 0) return ''\n      // Non-zero is the EXPECTED \"absent at baseline ⇒ untracked\" case (exit\n      // 128), but a genuine git-show error (bad object, corrupt repo, invalid\n      // sha) also exits non-zero and would silently fabricate a full-file\n      // add-patch. Log it under `sandbox` (like `before()` does) so a\n      // persistent probe error is greppable, then fall back to synthesize.\n      logger?.sandbox(\n        'sandbox diff() tracked-ness probe non-zero exit (treating as untracked)',\n        { path: event.path, exitCode: res.exitCode, stderr: res.stderr },\n      )\n      return synthesizeAddPatch(rel, content)\n    } catch (error) {\n      // Uncertain — don't fabricate a full-file add-patch on a probe failure.\n      logger?.warn('sandbox diff() tracked-ness probe failed', {\n        path: event.path,\n        error,\n      })\n      return ''\n    }\n  }\n  const diff = async (): Promise<string> => {\n    if (baseSha === '') {\n      if (event.type === 'delete') return ''\n      return synthesizeAddPatch(relTo(root, 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      if (res.exitCode !== 0) {\n        logger?.warn('sandbox diff() git diff non-zero exit', {\n          path: event.path,\n          exitCode: res.exitCode,\n          stderr: res.stderr,\n        })\n        return ''\n      }\n      if (res.stdout !== '') return res.stdout\n      return synthesizeIfUntracked(rel)\n    } catch (error) {\n      logger?.warn('sandbox diff() git diff failed', {\n        path: event.path,\n        error,\n      })\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"],"mappings":";;AAKA,SAAS,MAAM,MAAc,MAAsB;CACjD,MAAM,SAAS,KAAK,SAAS,GAAG,IAAI,OAAO,GAAG,KAAK;CACnD,OAAO,KAAK,WAAW,MAAM,IAAI,KAAK,MAAM,OAAO,MAAM,IAAI;AAC/D;;;;AAKA,SAAS,EAAE,OAAuB;CAChC,OAAO,IAAI,MAAM,QAAQ,MAAM,OAAO,EAAE;AAC1C;;;;;;;;;;;;;AAcA,SAAS,mBAAmB,KAAa,SAAyB;CAChE,MAAM,SAAS,gBAAgB,IAAI,KAAK,IAAI;CAE5C,IAAI,YAAY,IAAI,OAAO;CAC3B,MAAM,kBAAkB,QAAQ,SAAS,IAAI;CAC7C,MAAM,QAAQ,QAAQ,QAAQ,OAAO,EAAE,CAAC,CAAC,MAAM,IAAI;CACnD,MAAM,OAAO,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,IAAI;CAChD,OACE,SACA,wBACS,IAAI,eACC,MAAM,OAAO,SAC3B,QACC,kBAAkB,OAAO;AAE9B;;;;;;;;AASA,SAAgB,mBACd,QACA,MACA,SACA,OACA,QACsB;CACtB,MAAM,QAAQ,YAA6B;EACzC,IAAI,MAAM,SAAS,UAAU,OAAO;EACpC,IAAI;GACF,OAAO,MAAM,OAAO,GAAG,KAAK,MAAM,IAAI;EACxC,SAAS,OAAO;GACd,QAAQ,KAAK,uCAAuC;IAClD,MAAM,MAAM;IACZ;GACF,CAAC;GACD,OAAO;EACT;CACF;CACA,MAAM,SAAS,YAA6B;EAC1C,IAAI,YAAY,IAAI,OAAO;EAC3B,MAAM,MAAM,MAAM,MAAM,MAAM,IAAI;EAClC,IAAI;GACF,MAAM,MAAM,MAAM,OAAO,QAAQ,KAC/B,YAAY,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAC/B,EAAE,KAAK,KAAK,CACd;GACA,IAAI,IAAI,aAAa,GAAG,OAAO,IAAI;GAKnC,QAAQ,QAAQ,mCAAmC;IACjD,MAAM,MAAM;IACZ,UAAU,IAAI;IACd,QAAQ,IAAI;GACd,CAAC;GACD,OAAO;EACT,SAAS,OAAO;GACd,QAAQ,KAAK,oCAAoC;IAC/C,MAAM,MAAM;IACZ;GACF,CAAC;GACD,OAAO;EACT;CACF;CAiBA,MAAM,wBAAwB,OAAO,QAAiC;EACpE,MAAM,UAAU,MAAM,MAAM;EAC5B,IAAI,YAAY,IAAI,OAAO;EAM3B,IAAI;GACF,MAAM,UAAU,MAAM,OAAO,QAAQ,KACnC,0BAA0B,EAAE,GAAG,KAC/B,EAAE,KAAK,KAAK,CACd;GAEA,IAAI,QAAQ,aAAa,GAAG;IAC1B,QAAQ,QAAQ,gDAAgD,EAC9D,MAAM,MAAM,KACd,CAAC;IACD,OAAO;GACT;GACA,IAAI,QAAQ,aAAa,GAMvB,QAAQ,KAAK,iDAAiD;IAC5D,MAAM,MAAM;IACZ,UAAU,QAAQ;IAClB,QAAQ,QAAQ;GAClB,CAAC;EAEL,SAAS,OAAO;GAId,QAAQ,KAAK,0CAA0C;IACrD,MAAM,MAAM;IACZ;GACF,CAAC;EACH;EAMA,IAAI;GACF,MAAM,MAAM,MAAM,OAAO,QAAQ,KAC/B,YAAY,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,KAC/B,EAAE,KAAK,KAAK,CACd;GAGA,IAAI,IAAI,aAAa,GAAG,OAAO;GAM/B,QAAQ,QACN,2EACA;IAAE,MAAM,MAAM;IAAM,UAAU,IAAI;IAAU,QAAQ,IAAI;GAAO,CACjE;GACA,OAAO,mBAAmB,KAAK,OAAO;EACxC,SAAS,OAAO;GAEd,QAAQ,KAAK,4CAA4C;IACvD,MAAM,MAAM;IACZ;GACF,CAAC;GACD,OAAO;EACT;CACF;CACA,MAAM,OAAO,YAA6B;EACxC,IAAI,YAAY,IAAI;GAClB,IAAI,MAAM,SAAS,UAAU,OAAO;GACpC,OAAO,mBAAmB,MAAM,MAAM,MAAM,IAAI,GAAG,MAAM,MAAM,CAAC;EAClE;EAMA,MAAM,MAAM,MAAM,MAAM,MAAM,IAAI;EAClC,IAAI;GACF,MAAM,MAAM,MAAM,OAAO,QAAQ,KAC/B,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,KAClC,EACE,KAAK,KACP,CACF;GACA,IAAI,IAAI,aAAa,GAAG;IACtB,QAAQ,KAAK,yCAAyC;KACpD,MAAM,MAAM;KACZ,UAAU,IAAI;KACd,QAAQ,IAAI;IACd,CAAC;IACD,OAAO;GACT;GACA,IAAI,IAAI,WAAW,IAAI,OAAO,IAAI;GAClC,OAAO,sBAAsB,GAAG;EAClC,SAAS,OAAO;GACd,QAAQ,KAAK,kCAAkC;IAC7C,MAAM,MAAM;IACZ;GACF,CAAC;GACD,OAAO;EACT;CACF;CACA,OAAO;EAAE,GAAG;EAAO;EAAQ;EAAO;CAAK;AACzC;;AAQA,SAAgB,kBACd,KACoB;CACpB,IAAI,QAAQ,OAAO,OAAO;EAAE,SAAS;EAAO,MAAM;CAAM;CACxD,IAAI,QAAQ,KAAA,KAAa,QAAQ,MAAM,OAAO;EAAE,SAAS;EAAM,MAAM;CAAM;CAC3E,OAAO;EAAE,SAAS;EAAM,MAAM,IAAI,SAAS;CAAK;AAClD"}

package/dist/esm/git-exec.js

@@ -1,68 +1,57 @@
+//#region src/git-exec.ts
+/** POSIX single-quote escape: wrap in '…' and escape embedded quotes. */
 function q(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
+/** Reject values that could be parsed as a git flag when used as a positional. */
 function assertNoLeadingDash(value, name) {
-  if (value.startsWith("-")) {
-    throw new Error(
-      `git-exec: ${name} "${value}" must not begin with "-" (argument-injection guard).`
-    );
-  }
+	if (value.startsWith("-")) throw new Error(`git-exec: ${name} "${value}" must not begin with "-" (argument-injection guard).`);
 }
-const CREDENTIAL_HELPER = '!f() { echo "username=${GIT_ASKPASS_USER}"; echo "password=${GIT_ASKPASS_TOKEN}"; }; f';
+var CREDENTIAL_HELPER = "!f() { echo \"username=${GIT_ASKPASS_USER}\"; echo \"password=${GIT_ASKPASS_TOKEN}\"; }; f";
 function createExecBackedGit(process, defaultRoot) {
-  const at = (dir) => {
-    const d = dir ?? defaultRoot;
-    assertNoLeadingDash(d, "dir");
-    return q(d);
-  };
-  return {
-    clone: async ({ url, dir, ref, auth, depth }) => {
-      assertNoLeadingDash(url, "url");
-      const target = dir ?? defaultRoot;
-      assertNoLeadingDash(target, "dir");
-      if (ref !== void 0) assertNoLeadingDash(ref, "ref");
-      const refArg = ref ? `--branch ${q(ref)} ` : "";
-      const resolvedDepth = depth ?? 1;
-      if (resolvedDepth !== "full" && (!Number.isInteger(resolvedDepth) || resolvedDepth <= 0)) {
-        throw new Error('git-exec: depth must be a positive integer or "full".');
-      }
-      const depthArg = resolvedDepth === "full" ? "" : `--depth ${resolvedDepth} --single-branch `;
-      if (auth?.token) {
-        await process.exec(
-          `git -c credential.helper=${q(CREDENTIAL_HELPER)} clone ${refArg}${depthArg}-- ${q(url)} ${q(target)}`,
-          {
-            // Token lives only in the child env, never in argv.
-            env: {
-              GIT_ASKPASS_USER: auth.username ?? "x-access-token",
-              GIT_ASKPASS_TOKEN: auth.token,
-              GIT_TERMINAL_PROMPT: "0"
-            }
-          }
-        );
-        return;
-      }
-      await process.exec(
-        `git clone ${refArg}${depthArg}-- ${q(url)} ${q(target)}`
-      );
-    },
-    status: async (dir) => (await process.exec(`git -C ${at(dir)} status --porcelain`)).stdout,
-    add: async (paths, dir) => {
-      paths.forEach((p, i) => assertNoLeadingDash(p, `path[${i}]`));
-      await process.exec(`git -C ${at(dir)} add -- ${paths.map(q).join(" ")}`);
-    },
-    commit: async (message, dir) => {
-      await process.exec(`git -C ${at(dir)} commit -m ${q(message)}`);
-    },
-    push: async (dir) => {
-      await process.exec(`git -C ${at(dir)} push`);
-    },
-    pull: async (dir) => {
-      await process.exec(`git -C ${at(dir)} pull`);
-    },
-    branch: async (dir) => (await process.exec(`git -C ${at(dir)} rev-parse --abbrev-ref HEAD`)).stdout.trim()
-  };
+	const at = (dir) => {
+		const d = dir ?? defaultRoot;
+		assertNoLeadingDash(d, "dir");
+		return q(d);
+	};
+	return {
+		clone: async ({ url, dir, ref, auth, depth }) => {
+			assertNoLeadingDash(url, "url");
+			const target = dir ?? defaultRoot;
+			assertNoLeadingDash(target, "dir");
+			if (ref !== void 0) assertNoLeadingDash(ref, "ref");
+			const refArg = ref ? `--branch ${q(ref)} ` : "";
+			const resolvedDepth = depth ?? 1;
+			if (resolvedDepth !== "full" && (!Number.isInteger(resolvedDepth) || resolvedDepth <= 0)) throw new Error("git-exec: depth must be a positive integer or \"full\".");
+			const depthArg = resolvedDepth === "full" ? "" : `--depth ${resolvedDepth} --single-branch `;
+			if (auth?.token) {
+				await process.exec(`git -c credential.helper=${q(CREDENTIAL_HELPER)} clone ${refArg}${depthArg}-- ${q(url)} ${q(target)}`, { env: {
+					GIT_ASKPASS_USER: auth.username ?? "x-access-token",
+					GIT_ASKPASS_TOKEN: auth.token,
+					GIT_TERMINAL_PROMPT: "0"
+				} });
+				return;
+			}
+			await process.exec(`git clone ${refArg}${depthArg}-- ${q(url)} ${q(target)}`);
+		},
+		status: async (dir) => (await process.exec(`git -C ${at(dir)} status --porcelain`)).stdout,
+		add: async (paths, dir) => {
+			paths.forEach((p, i) => assertNoLeadingDash(p, `path[${i}]`));
+			await process.exec(`git -C ${at(dir)} add -- ${paths.map(q).join(" ")}`);
+		},
+		commit: async (message, dir) => {
+			await process.exec(`git -C ${at(dir)} commit -m ${q(message)}`);
+		},
+		push: async (dir) => {
+			await process.exec(`git -C ${at(dir)} push`);
+		},
+		pull: async (dir) => {
+			await process.exec(`git -C ${at(dir)} pull`);
+		},
+		branch: async (dir) => (await process.exec(`git -C ${at(dir)} rev-parse --abbrev-ref HEAD`)).stdout.trim()
+	};
 }
-export {
-  createExecBackedGit
-};
-//# sourceMappingURL=git-exec.js.map
+//#endregion
+export { createExecBackedGit };
+
+//# sourceMappingURL=git-exec.js.map

package/dist/esm/git-exec.js.map

@@ -1 +1 @@
-{"version":3,"file":"git-exec.js","sources":["../../src/git-exec.ts"],"sourcesContent":["/**\n * An exec-backed {@link SandboxGit} implementation. Providers without a native\n * git API (local-process, Docker) get a uniform `sandbox.git` by desugaring to\n * `process.exec(\"git …\")`. Providers WITH native git (Daytona, Cloudflare) may\n * supply their own implementation instead.\n *\n * Security:\n * - Every interpolated value is single-quote escaped (no shell injection).\n * - A `--` end-of-options separator precedes untrusted positionals and values\n *   are rejected if they begin with `-`, so a repo URL / ref / path can't\n *   smuggle a git flag (e.g. `--upload-pack=…`).\n * - Auth tokens NEVER appear in argv (they'd leak via `ps` / process logs).\n *   Instead a one-shot `credential.helper` reads the token from the child\n *   process ENV. The helper string is single-quoted so the OUTER shell never\n *   expands the env var — only git's own helper subshell does, at use time.\n *\n * NOTE: `SandboxProcess.exec` takes a command STRING by design (the sandbox\n * runs shell commands), so we mitigate flag smuggling with `--` + validation\n * rather than an argv array.\n */\nimport type { SandboxGit, SandboxProcess } from './contracts'\n\n/** POSIX single-quote escape: wrap in '…' and escape embedded quotes. */\nfunction q(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`\n}\n\n/** Reject values that could be parsed as a git flag when used as a positional. */\nfunction assertNoLeadingDash(value: string, name: string): void {\n  if (value.startsWith('-')) {\n    throw new Error(\n      `git-exec: ${name} \"${value}\" must not begin with \"-\" (argument-injection guard).`,\n    )\n  }\n}\n\n// Credential helper that prints creds read from the child ENV. Single-quoted at\n// the call site so the outer shell passes it literally; git expands the vars in\n// its own helper subshell, keeping the token out of argv.\nconst CREDENTIAL_HELPER =\n  '!f() { echo \"username=${GIT_ASKPASS_USER}\"; echo \"password=${GIT_ASKPASS_TOKEN}\"; }; f'\n\nexport function createExecBackedGit(\n  process: SandboxProcess,\n  defaultRoot: string,\n): SandboxGit {\n  const at = (dir?: string): string => {\n    const d = dir ?? defaultRoot\n    assertNoLeadingDash(d, 'dir')\n    return q(d)\n  }\n\n  return {\n    clone: async ({ url, dir, ref, auth, depth }) => {\n      assertNoLeadingDash(url, 'url')\n      const target = dir ?? defaultRoot\n      assertNoLeadingDash(target, 'dir')\n      if (ref !== undefined) assertNoLeadingDash(ref, 'ref')\n      const refArg = ref ? `--branch ${q(ref)} ` : ''\n      const resolvedDepth = depth ?? 1\n      // `depth` is interpolated unquoted into the command, so validate it the\n      // same way other positionals are guarded — a non-positive-integer (e.g. an\n      // untyped caller passing a string) must never reach the shell.\n      if (\n        resolvedDepth !== 'full' &&\n        (!Number.isInteger(resolvedDepth) || resolvedDepth <= 0)\n      ) {\n        throw new Error('git-exec: depth must be a positive integer or \"full\".')\n      }\n      const depthArg =\n        resolvedDepth === 'full'\n          ? ''\n          : `--depth ${resolvedDepth} --single-branch `\n\n      if (auth?.token) {\n        await process.exec(\n          `git -c credential.helper=${q(CREDENTIAL_HELPER)} clone ${refArg}${depthArg}-- ${q(url)} ${q(target)}`,\n          {\n            // Token lives only in the child env, never in argv.\n            env: {\n              GIT_ASKPASS_USER: auth.username ?? 'x-access-token',\n              GIT_ASKPASS_TOKEN: auth.token,\n              GIT_TERMINAL_PROMPT: '0',\n            },\n          },\n        )\n        return\n      }\n\n      await process.exec(\n        `git clone ${refArg}${depthArg}-- ${q(url)} ${q(target)}`,\n      )\n    },\n    status: async (dir) =>\n      (await process.exec(`git -C ${at(dir)} status --porcelain`)).stdout,\n    add: async (paths, dir) => {\n      paths.forEach((p, i) => assertNoLeadingDash(p, `path[${i}]`))\n      await process.exec(`git -C ${at(dir)} add -- ${paths.map(q).join(' ')}`)\n    },\n    commit: async (message, dir) => {\n      await process.exec(`git -C ${at(dir)} commit -m ${q(message)}`)\n    },\n    push: async (dir) => {\n      await process.exec(`git -C ${at(dir)} push`)\n    },\n    pull: async (dir) => {\n      await process.exec(`git -C ${at(dir)} pull`)\n    },\n    branch: async (dir) =>\n      (\n        await process.exec(`git -C ${at(dir)} rev-parse --abbrev-ref HEAD`)\n      ).stdout.trim(),\n  }\n}\n"],"names":[],"mappings":"AAuBA,SAAS,EAAE,OAAuB;AAChC,SAAO,IAAI,MAAM,QAAQ,MAAM,OAAO,CAAC;AACzC;AAGA,SAAS,oBAAoB,OAAe,MAAoB;AAC9D,MAAI,MAAM,WAAW,GAAG,GAAG;AACzB,UAAM,IAAI;AAAA,MACR,aAAa,IAAI,KAAK,KAAK;AAAA,IAAA;AAAA,EAE/B;AACF;AAKA,MAAM,oBACJ;AAEK,SAAS,oBACd,SACA,aACY;AACZ,QAAM,KAAK,CAAC,QAAyB;AACnC,UAAM,IAAI,OAAO;AACjB,wBAAoB,GAAG,KAAK;AAC5B,WAAO,EAAE,CAAC;AAAA,EACZ;AAEA,SAAO;AAAA,IACL,OAAO,OAAO,EAAE,KAAK,KAAK,KAAK,MAAM,YAAY;AAC/C,0BAAoB,KAAK,KAAK;AAC9B,YAAM,SAAS,OAAO;AACtB,0BAAoB,QAAQ,KAAK;AACjC,UAAI,QAAQ,OAAW,qBAAoB,KAAK,KAAK;AACrD,YAAM,SAAS,MAAM,YAAY,EAAE,GAAG,CAAC,MAAM;AAC7C,YAAM,gBAAgB,SAAS;AAI/B,UACE,kBAAkB,WACjB,CAAC,OAAO,UAAU,aAAa,KAAK,iBAAiB,IACtD;AACA,cAAM,IAAI,MAAM,uDAAuD;AAAA,MACzE;AACA,YAAM,WACJ,kBAAkB,SACd,KACA,WAAW,aAAa;AAE9B,UAAI,MAAM,OAAO;AACf,cAAM,QAAQ;AAAA,UACZ,4BAA4B,EAAE,iBAAiB,CAAC,UAAU,MAAM,GAAG,QAAQ,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC;AAAA,UACpG;AAAA;AAAA,YAEE,KAAK;AAAA,cACH,kBAAkB,KAAK,YAAY;AAAA,cACnC,mBAAmB,KAAK;AAAA,cACxB,qBAAqB;AAAA,YAAA;AAAA,UACvB;AAAA,QACF;AAEF;AAAA,MACF;AAEA,YAAM,QAAQ;AAAA,QACZ,aAAa,MAAM,GAAG,QAAQ,MAAM,EAAE,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC;AAAA,MAAA;AAAA,IAE3D;AAAA,IACA,QAAQ,OAAO,SACZ,MAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,CAAC,qBAAqB,GAAG;AAAA,IAC/D,KAAK,OAAO,OAAO,QAAQ;AACzB,YAAM,QAAQ,CAAC,GAAG,MAAM,oBAAoB,GAAG,QAAQ,CAAC,GAAG,CAAC;AAC5D,YAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,CAAC,WAAW,MAAM,IAAI,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE;AAAA,IACzE;AAAA,IACA,QAAQ,OAAO,SAAS,QAAQ;AAC9B,YAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,EAAE;AAAA,IAChE;AAAA,IACA,MAAM,OAAO,QAAQ;AACnB,YAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,CAAC,OAAO;AAAA,IAC7C;AAAA,IACA,MAAM,OAAO,QAAQ;AACnB,YAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,CAAC,OAAO;AAAA,IAC7C;AAAA,IACA,QAAQ,OAAO,SAEX,MAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,CAAC,8BAA8B,GAClE,OAAO,KAAA;AAAA,EAAK;AAEpB;"}
+{"version":3,"file":"git-exec.js","names":[],"sources":["../../src/git-exec.ts"],"sourcesContent":["/**\n * An exec-backed {@link SandboxGit} implementation. Providers without a native\n * git API (local-process, Docker) get a uniform `sandbox.git` by desugaring to\n * `process.exec(\"git …\")`. Providers WITH native git (Daytona, Cloudflare) may\n * supply their own implementation instead.\n *\n * Security:\n * - Every interpolated value is single-quote escaped (no shell injection).\n * - A `--` end-of-options separator precedes untrusted positionals and values\n *   are rejected if they begin with `-`, so a repo URL / ref / path can't\n *   smuggle a git flag (e.g. `--upload-pack=…`).\n * - Auth tokens NEVER appear in argv (they'd leak via `ps` / process logs).\n *   Instead a one-shot `credential.helper` reads the token from the child\n *   process ENV. The helper string is single-quoted so the OUTER shell never\n *   expands the env var — only git's own helper subshell does, at use time.\n *\n * NOTE: `SandboxProcess.exec` takes a command STRING by design (the sandbox\n * runs shell commands), so we mitigate flag smuggling with `--` + validation\n * rather than an argv array.\n */\nimport type { SandboxGit, SandboxProcess } from './contracts'\n\n/** POSIX single-quote escape: wrap in '…' and escape embedded quotes. */\nfunction q(value: string): string {\n  return `'${value.replace(/'/g, `'\\\\''`)}'`\n}\n\n/** Reject values that could be parsed as a git flag when used as a positional. */\nfunction assertNoLeadingDash(value: string, name: string): void {\n  if (value.startsWith('-')) {\n    throw new Error(\n      `git-exec: ${name} \"${value}\" must not begin with \"-\" (argument-injection guard).`,\n    )\n  }\n}\n\n// Credential helper that prints creds read from the child ENV. Single-quoted at\n// the call site so the outer shell passes it literally; git expands the vars in\n// its own helper subshell, keeping the token out of argv.\nconst CREDENTIAL_HELPER =\n  '!f() { echo \"username=${GIT_ASKPASS_USER}\"; echo \"password=${GIT_ASKPASS_TOKEN}\"; }; f'\n\nexport function createExecBackedGit(\n  process: SandboxProcess,\n  defaultRoot: string,\n): SandboxGit {\n  const at = (dir?: string): string => {\n    const d = dir ?? defaultRoot\n    assertNoLeadingDash(d, 'dir')\n    return q(d)\n  }\n\n  return {\n    clone: async ({ url, dir, ref, auth, depth }) => {\n      assertNoLeadingDash(url, 'url')\n      const target = dir ?? defaultRoot\n      assertNoLeadingDash(target, 'dir')\n      if (ref !== undefined) assertNoLeadingDash(ref, 'ref')\n      const refArg = ref ? `--branch ${q(ref)} ` : ''\n      const resolvedDepth = depth ?? 1\n      // `depth` is interpolated unquoted into the command, so validate it the\n      // same way other positionals are guarded — a non-positive-integer (e.g. an\n      // untyped caller passing a string) must never reach the shell.\n      if (\n        resolvedDepth !== 'full' &&\n        (!Number.isInteger(resolvedDepth) || resolvedDepth <= 0)\n      ) {\n        throw new Error('git-exec: depth must be a positive integer or \"full\".')\n      }\n      const depthArg =\n        resolvedDepth === 'full'\n          ? ''\n          : `--depth ${resolvedDepth} --single-branch `\n\n      if (auth?.token) {\n        await process.exec(\n          `git -c credential.helper=${q(CREDENTIAL_HELPER)} clone ${refArg}${depthArg}-- ${q(url)} ${q(target)}`,\n          {\n            // Token lives only in the child env, never in argv.\n            env: {\n              GIT_ASKPASS_USER: auth.username ?? 'x-access-token',\n              GIT_ASKPASS_TOKEN: auth.token,\n              GIT_TERMINAL_PROMPT: '0',\n            },\n          },\n        )\n        return\n      }\n\n      await process.exec(\n        `git clone ${refArg}${depthArg}-- ${q(url)} ${q(target)}`,\n      )\n    },\n    status: async (dir) =>\n      (await process.exec(`git -C ${at(dir)} status --porcelain`)).stdout,\n    add: async (paths, dir) => {\n      paths.forEach((p, i) => assertNoLeadingDash(p, `path[${i}]`))\n      await process.exec(`git -C ${at(dir)} add -- ${paths.map(q).join(' ')}`)\n    },\n    commit: async (message, dir) => {\n      await process.exec(`git -C ${at(dir)} commit -m ${q(message)}`)\n    },\n    push: async (dir) => {\n      await process.exec(`git -C ${at(dir)} push`)\n    },\n    pull: async (dir) => {\n      await process.exec(`git -C ${at(dir)} pull`)\n    },\n    branch: async (dir) =>\n      (\n        await process.exec(`git -C ${at(dir)} rev-parse --abbrev-ref HEAD`)\n      ).stdout.trim(),\n  }\n}\n"],"mappings":";;AAuBA,SAAS,EAAE,OAAuB;CAChC,OAAO,IAAI,MAAM,QAAQ,MAAM,OAAO,EAAE;AAC1C;;AAGA,SAAS,oBAAoB,OAAe,MAAoB;CAC9D,IAAI,MAAM,WAAW,GAAG,GACtB,MAAM,IAAI,MACR,aAAa,KAAK,IAAI,MAAM,sDAC9B;AAEJ;AAKA,IAAM,oBACJ;AAEF,SAAgB,oBACd,SACA,aACY;CACZ,MAAM,MAAM,QAAyB;EACnC,MAAM,IAAI,OAAO;EACjB,oBAAoB,GAAG,KAAK;EAC5B,OAAO,EAAE,CAAC;CACZ;CAEA,OAAO;EACL,OAAO,OAAO,EAAE,KAAK,KAAK,KAAK,MAAM,YAAY;GAC/C,oBAAoB,KAAK,KAAK;GAC9B,MAAM,SAAS,OAAO;GACtB,oBAAoB,QAAQ,KAAK;GACjC,IAAI,QAAQ,KAAA,GAAW,oBAAoB,KAAK,KAAK;GACrD,MAAM,SAAS,MAAM,YAAY,EAAE,GAAG,EAAE,KAAK;GAC7C,MAAM,gBAAgB,SAAS;GAI/B,IACE,kBAAkB,WACjB,CAAC,OAAO,UAAU,aAAa,KAAK,iBAAiB,IAEtD,MAAM,IAAI,MAAM,yDAAuD;GAEzE,MAAM,WACJ,kBAAkB,SACd,KACA,WAAW,cAAc;GAE/B,IAAI,MAAM,OAAO;IACf,MAAM,QAAQ,KACZ,4BAA4B,EAAE,iBAAiB,EAAE,SAAS,SAAS,SAAS,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,KACnG,EAEE,KAAK;KACH,kBAAkB,KAAK,YAAY;KACnC,mBAAmB,KAAK;KACxB,qBAAqB;IACvB,EACF,CACF;IACA;GACF;GAEA,MAAM,QAAQ,KACZ,aAAa,SAAS,SAAS,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,GACxD;EACF;EACA,QAAQ,OAAO,SACZ,MAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,EAAE,oBAAoB,EAAA,CAAG;EAC/D,KAAK,OAAO,OAAO,QAAQ;GACzB,MAAM,SAAS,GAAG,MAAM,oBAAoB,GAAG,QAAQ,EAAE,EAAE,CAAC;GAC5D,MAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,EAAE,UAAU,MAAM,IAAI,CAAC,CAAC,CAAC,KAAK,GAAG,GAAG;EACzE;EACA,QAAQ,OAAO,SAAS,QAAQ;GAC9B,MAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,EAAE,aAAa,EAAE,OAAO,GAAG;EAChE;EACA,MAAM,OAAO,QAAQ;GACnB,MAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,EAAE,MAAM;EAC7C;EACA,MAAM,OAAO,QAAQ;GACnB,MAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,EAAE,MAAM;EAC7C;EACA,QAAQ,OAAO,SAEX,MAAM,QAAQ,KAAK,UAAU,GAAG,GAAG,EAAE,6BAA6B,EAAA,CAClE,OAAO,KAAK;CAClB;AACF"}

package/dist/esm/harness-cwd.js

@@ -1,24 +1,29 @@
-import * as path from "node:path";
 import { DEFAULT_WORKSPACE_ROOT } from "./bootstrap.js";
+import * as path from "node:path";
+//#region src/harness-cwd.ts
+/**
+* Resolve a VIRTUAL sandbox cwd (e.g. `/workspace`) to the path a harness CLI
+* or ACP session must use on the real filesystem.
+*
+* Provider handles map virtual paths for spawn/exec/fs; harness-facing APIs
+* interpret cwd literally (`grok --cwd`, ACP `newSession`, opencode HTTP
+* `directory`, …).
+*/
 function mapVirtualWorkspacePath(virtualCwd, realRoot) {
-  if (virtualCwd === DEFAULT_WORKSPACE_ROOT) return realRoot;
-  if (virtualCwd.startsWith(`${DEFAULT_WORKSPACE_ROOT}/`)) {
-    const rel = virtualCwd.slice(DEFAULT_WORKSPACE_ROOT.length + 1);
-    return realRoot === DEFAULT_WORKSPACE_ROOT ? `${DEFAULT_WORKSPACE_ROOT}/${rel}` : path.posix.join(realRoot, rel);
-  }
-  return virtualCwd;
+	if (virtualCwd === "/workspace") return realRoot;
+	if (virtualCwd.startsWith(`/workspace/`)) {
+		const rel = virtualCwd.slice(DEFAULT_WORKSPACE_ROOT.length + 1);
+		return realRoot === "/workspace" ? `${DEFAULT_WORKSPACE_ROOT}/${rel}` : path.posix.join(realRoot, rel);
+	}
+	return virtualCwd;
 }
 function resolveHarnessCwd(handle, virtualCwd = DEFAULT_WORKSPACE_ROOT) {
-  if (handle.provider === "local-process") {
-    return mapVirtualWorkspacePath(virtualCwd, handle.id);
-  }
-  const root = handle.workspaceRoot;
-  if (root !== void 0 && root !== DEFAULT_WORKSPACE_ROOT) {
-    return mapVirtualWorkspacePath(virtualCwd, root);
-  }
-  return virtualCwd;
+	if (handle.provider === "local-process") return mapVirtualWorkspacePath(virtualCwd, handle.id);
+	const root = handle.workspaceRoot;
+	if (root !== void 0 && root !== "/workspace") return mapVirtualWorkspacePath(virtualCwd, root);
+	return virtualCwd;
 }
-export {
-  resolveHarnessCwd
-};
-//# sourceMappingURL=harness-cwd.js.map
+//#endregion
+export { resolveHarnessCwd };
+
+//# sourceMappingURL=harness-cwd.js.map

package/dist/esm/harness-cwd.js.map

@@ -1 +1 @@
-{"version":3,"file":"harness-cwd.js","sources":["../../src/harness-cwd.ts"],"sourcesContent":["/**\n * Resolve a VIRTUAL sandbox cwd (e.g. `/workspace`) to the path a harness CLI\n * or ACP session must use on the real filesystem.\n *\n * Provider handles map virtual paths for spawn/exec/fs; harness-facing APIs\n * interpret cwd literally (`grok --cwd`, ACP `newSession`, opencode HTTP\n * `directory`, …).\n */\nimport * as path from 'node:path'\nimport { DEFAULT_WORKSPACE_ROOT } from './bootstrap'\nimport type { SandboxHandle } from './contracts'\n\nfunction mapVirtualWorkspacePath(virtualCwd: string, realRoot: string): string {\n  if (virtualCwd === DEFAULT_WORKSPACE_ROOT) return realRoot\n  if (virtualCwd.startsWith(`${DEFAULT_WORKSPACE_ROOT}/`)) {\n    const rel = virtualCwd.slice(DEFAULT_WORKSPACE_ROOT.length + 1)\n    return realRoot === DEFAULT_WORKSPACE_ROOT\n      ? `${DEFAULT_WORKSPACE_ROOT}/${rel}`\n      : path.posix.join(realRoot, rel)\n  }\n  return virtualCwd\n}\n\nexport function resolveHarnessCwd(\n  handle: SandboxHandle,\n  virtualCwd: string = DEFAULT_WORKSPACE_ROOT,\n): string {\n  if (handle.provider === 'local-process') {\n    return mapVirtualWorkspacePath(virtualCwd, handle.id)\n  }\n\n  const root = handle.workspaceRoot\n  if (root !== undefined && root !== DEFAULT_WORKSPACE_ROOT) {\n    return mapVirtualWorkspacePath(virtualCwd, root)\n  }\n\n  return virtualCwd\n}\n"],"names":[],"mappings":";;AAYA,SAAS,wBAAwB,YAAoB,UAA0B;AAC7E,MAAI,eAAe,uBAAwB,QAAO;AAClD,MAAI,WAAW,WAAW,GAAG,sBAAsB,GAAG,GAAG;AACvD,UAAM,MAAM,WAAW,MAAM,uBAAuB,SAAS,CAAC;AAC9D,WAAO,aAAa,yBAChB,GAAG,sBAAsB,IAAI,GAAG,KAChC,KAAK,MAAM,KAAK,UAAU,GAAG;AAAA,EACnC;AACA,SAAO;AACT;AAEO,SAAS,kBACd,QACA,aAAqB,wBACb;AACR,MAAI,OAAO,aAAa,iBAAiB;AACvC,WAAO,wBAAwB,YAAY,OAAO,EAAE;AAAA,EACtD;AAEA,QAAM,OAAO,OAAO;AACpB,MAAI,SAAS,UAAa,SAAS,wBAAwB;AACzD,WAAO,wBAAwB,YAAY,IAAI;AAAA,EACjD;AAEA,SAAO;AACT;"}
+{"version":3,"file":"harness-cwd.js","names":[],"sources":["../../src/harness-cwd.ts"],"sourcesContent":["/**\n * Resolve a VIRTUAL sandbox cwd (e.g. `/workspace`) to the path a harness CLI\n * or ACP session must use on the real filesystem.\n *\n * Provider handles map virtual paths for spawn/exec/fs; harness-facing APIs\n * interpret cwd literally (`grok --cwd`, ACP `newSession`, opencode HTTP\n * `directory`, …).\n */\nimport * as path from 'node:path'\nimport { DEFAULT_WORKSPACE_ROOT } from './bootstrap'\nimport type { SandboxHandle } from './contracts'\n\nfunction mapVirtualWorkspacePath(virtualCwd: string, realRoot: string): string {\n  if (virtualCwd === DEFAULT_WORKSPACE_ROOT) return realRoot\n  if (virtualCwd.startsWith(`${DEFAULT_WORKSPACE_ROOT}/`)) {\n    const rel = virtualCwd.slice(DEFAULT_WORKSPACE_ROOT.length + 1)\n    return realRoot === DEFAULT_WORKSPACE_ROOT\n      ? `${DEFAULT_WORKSPACE_ROOT}/${rel}`\n      : path.posix.join(realRoot, rel)\n  }\n  return virtualCwd\n}\n\nexport function resolveHarnessCwd(\n  handle: SandboxHandle,\n  virtualCwd: string = DEFAULT_WORKSPACE_ROOT,\n): string {\n  if (handle.provider === 'local-process') {\n    return mapVirtualWorkspacePath(virtualCwd, handle.id)\n  }\n\n  const root = handle.workspaceRoot\n  if (root !== undefined && root !== DEFAULT_WORKSPACE_ROOT) {\n    return mapVirtualWorkspacePath(virtualCwd, root)\n  }\n\n  return virtualCwd\n}\n"],"mappings":";;;;;;;;;;;AAYA,SAAS,wBAAwB,YAAoB,UAA0B;CAC7E,IAAI,eAAA,cAAuC,OAAO;CAClD,IAAI,WAAW,WAAW,aAA4B,GAAG;EACvD,MAAM,MAAM,WAAW,MAAM,uBAAuB,SAAS,CAAC;EAC9D,OAAO,aAAA,eACH,GAAG,uBAAuB,GAAG,QAC7B,KAAK,MAAM,KAAK,UAAU,GAAG;CACnC;CACA,OAAO;AACT;AAEA,SAAgB,kBACd,QACA,aAAqB,wBACb;CACR,IAAI,OAAO,aAAa,iBACtB,OAAO,wBAAwB,YAAY,OAAO,EAAE;CAGtD,MAAM,OAAO,OAAO;CACpB,IAAI,SAAS,KAAA,KAAa,SAAA,cACxB,OAAO,wBAAwB,YAAY,IAAI;CAGjD,OAAO;AACT"}

package/dist/esm/index.d.ts

@@ -1,7 +1,11 @@
-export { SandboxCapability, SandboxStoreCapability, LocksCapability, SandboxPolicyCapability, ToolBridgeProvisionerCapability, getSandbox, provideSandbox, getSandboxStore, provideSandboxStore, getLocks, provideLocks, getSandboxPolicy, provideSandboxPolicy, getToolBridgeProvisioner, provideToolBridgeProvisioner, } from './capabilities.js';
+export { SandboxCapability, SandboxPolicyCapability, ToolBridgeProvisionerCapability, getSandbox, provideSandbox, getSandboxPolicy, provideSandboxPolicy, getToolBridgeProvisioner, provideToolBridgeProvisioner, } from './capabilities.js';
+export { SandboxInstanceStoreCapability, getSandboxInstanceStore, provideSandboxInstanceStore, InMemorySandboxInstanceStore, defineSandboxInstanceStore, } from './instance-store.js';
+export type { SandboxInstanceStore, SandboxInstanceRecord, } from './instance-store.js';
 export { ProjectionCapability, getWorkspaceProjection, provideWorkspaceProjection, } from './projection.js';
 export type { WorkspaceProjection } from './projection.js';
 export { withSandbox } from './middleware.js';
+export type { SandboxMiddlewareOptions } from './middleware.js';
+export { isSandboxToolCall } from './tool-history.js';
 export { defineSandbox } from './sandbox.js';
 export type { SandboxConfig, SandboxDefinition, SandboxEnsureContext, SandboxLifecycle, SandboxHooks, ReuseStrategy, SnapshotStrategy, } from './sandbox.js';
 export { defineWorkspace, gitSource, githubRepo, localSource, fileSkill, agentSkill, mcpSkill, gitSkill, } from './workspace.js';
@@ -11,25 +15,43 @@ export type { SecretRef, Secrets, BearerRef } from './secrets.js';
 export { defineSandboxPolicy, evaluateCommand, commandAliases } from './policy.js';
 export type { SandboxPolicy, PolicyDecision, CommandRules, CapabilityRules, } from './policy.js';
 export type { SandboxProvider, SandboxHandle, SandboxCapabilities, SandboxFs, SandboxGit, SandboxProcess, SandboxPorts, SandboxEnv, SandboxChannel, SpawnHandle, ExecResult, ProcessOptions, SnapshotRef, SandboxCreateInput, SandboxResumeInput, SandboxRestoreInput, SandboxDestroyInput, } from './contracts.js';
-export { InMemorySandboxStore, InMemoryLockStore } from './store.js';
-export type { SandboxStore, LockStore, SandboxRecord } from './store.js';
 export { bootstrapWorkspace, detectPackageManager, DEFAULT_WORKSPACE_ROOT, } from './bootstrap.js';
 export { resolveHarnessCwd } from './harness-cwd.js';
 export type { BootstrapResult } from './bootstrap.js';
 export { writeAgentsFile, resolveGitSkillDir, formatWorkspaceScriptsSection, mergeAgentsContent, } from './agents-file.js';
 export { createExecBackedGit } from './git-exec.js';
-export { spawnNdjson, toLines } from './runner.js';
-export type { SpawnNdjsonOptions } from './runner.js';
+export { spawnNdjson, toLines, startJournaledAgent, readJournalNdjson, } from './runner.js';
+export type { SpawnNdjsonOptions, JournalOptions } from './runner.js';
+export { DEFAULT_JOURNAL_DIR, encodeRunId, EXIT_SENTINEL_KEY, EXIT_SENTINEL_NONCE_KEY, exitSentinelLine, parseExitSentinel, journalPaths, journaledCommand, journalFollowCommand, journalReadCommand, journalExistsCommand, journalListCommand, journalMtimeListCommand, parseJournalMtimeListing, journalExitProbeCommand, parseJournalExit, decodeJournalRunId, } from './journal.js';
+export type { JournalPaths, JournalMtimeListing, JournalDirEntry, DecodedJournalRunId, } from './journal.js';
+export { pruneJournals, DEFAULT_ORPHAN_TTL_MS, DEFAULT_MAX_DELETES, } from './journal-sweep.js';
+export type { PruneJournalsOptions, PruneJournalsResult, KeptJournal, KeptJournalReason, PruneJournalsFailure, } from './journal-sweep.js';
+export { reapDetachedRuns, probeRunExit, DEFAULT_RUN_BUDGET_MS, DEFAULT_MAX_RUNS, DEFAULT_EXIT_PROBE_BYTES, } from './reap.js';
+export type { RunExitProbe, ReapRunOutcome, ReapRunEntry, ReapResult, ReapOptions, } from './reap.js';
+export { reclaimSandbox, sandboxReclaimer, SandboxReclaimFailedError, } from './reclaim.js';
+export type { ReclaimOutcome, ReclaimSandboxOptions } from './reclaim.js';
+export { DEFAULT_JOURNAL_POLL_MS, journalReadStrategy, readJournal, } from './journal-reader.js';
+export type { ReadJournalOptions } from './journal-reader.js';
+export { decodeBase64Stream, toJournalLines } from './journal-bytes.js';
+export type { JournalLine } from './journal-bytes.js';
+export { createRunScopedIdGen, chunkFingerprint, chunkFingerprintIgnoringThreadId, chunkThreadId, } from './chunk-identity.js';
+export { alignToStoredLog, isBridgeCustomChunk, JournalReplayDivergedError, JournalReplayThreadIdMismatchError, DEFAULT_MAX_OUT_OF_BAND_SKIP, } from './align.js';
+export type { AlignToStoredLogOptions } from './align.js';
+export { awaitAttachableJournal, JournalAttachUnavailableError, DEFAULT_ATTACH_JOURNAL_WAIT_MS, DEFAULT_ATTACH_PROBE_INTERVAL_MS, } from './attach-preflight.js';
+export type { AttachUnavailableReason, AwaitAttachableJournalOptions, } from './attach-preflight.js';
+export { SandboxDurabilityCapability, getSandboxDurability, provideSandboxDurability, DurableAttachNotSupportedError, DurableRunIdRequiredError, DurableThreadIdRequiredError, resolveDurableRunId, resolveDurableThreadId, journalOptionsFor, alignedIfAttaching, } from './durability.js';
+export type { SandboxDurabilityOptions, SandboxDurabilityLog, SandboxRunDurability, } from './durability.js';
+export { sandboxRunDriver, RunDriverPipeOutsideClaimError } from './driver.js';
+export type { SandboxRunDriverOptions } from './driver.js';
+export { RunClaimNotAcquiredError, RunClaimLostError, DEFAULT_FENCE_QUIET_MS, } from './claim.js';
 export { startHostToolBridge, hostForSandbox, createToolBridgeCore, handleBridgeJsonRpc, timingSafeBearerEqual, nodeHttpBridgeProvisioner, BRIDGED_MCP_SERVER_NAME, } from './tool-bridge.js';
 export type { HostToolBridge, StartBridgeOptions, ToolBridgeCore, ToolBridgeCoreOptions, ToolDescriptor, ToolCallResult, BridgePermission, PermissionToolResult, ToolBridgeProvisioner, ToolBridgeProvisionOptions, ProvisionedBridge, } from './tool-bridge.js';
 export { createBridgeEventChannel, mergeChunkStreams } from './bridge-events.js';
 export type { BridgeEventChannel } from './bridge-events.js';
 export { remoteToolStubs, toolDescriptors, httpRemoteToolExecutor, executeHostTool, isToolExecRequest, } from './remote-tools.js';
 export type { RemoteToolExecutor, RemoteToolExecuteOptions, ToolExecRequest, } from './remote-tools.js';
-export { InMemoryRunEventLog, isTerminalRunStatus } from './run-log.js';
-export type { RunEventLog, RunRecord, RunEvent, RunStatus, TerminalRunStatus, RunError, RunEventLogReadOptions, } from './run-log.js';
 export { pipeToRunLog, RunController } from './run.js';
-export type { PipeToRunLogOptions, RunControllerStartInput, RunHandle, } from './run.js';
+export type { RunDeps, PipeToRunLogOptions, RunControllerStartInput, RunHandle, } from './run.js';
 export { resolveApproval, approvalId, buildApprovalRequestedEvent, APPROVAL_REQUESTED_EVENT, } from './approvals.js';
 export type { ResolveApprovalInput, ApprovalOutcome } from './approvals.js';
 export { watchWorkspace, diffSnapshots } from './watch.js';

package/dist/esm/index.js

@@ -1,103 +1,35 @@
-import { LocksCapability, SandboxCapability, SandboxPolicyCapability, SandboxStoreCapability, ToolBridgeProvisionerCapability, getLocks, getSandbox, getSandboxPolicy, getSandboxStore, getToolBridgeProvisioner, provideLocks, provideSandbox, provideSandboxPolicy, provideSandboxStore, provideToolBridgeProvisioner } from "./capabilities.js";
+import { SandboxCapability, SandboxPolicyCapability, ToolBridgeProvisionerCapability, getSandbox, getSandboxPolicy, getToolBridgeProvisioner, provideSandbox, provideSandboxPolicy, provideToolBridgeProvisioner } from "./capabilities.js";
+import { InMemorySandboxInstanceStore, SandboxInstanceStoreCapability, defineSandboxInstanceStore, getSandboxInstanceStore, provideSandboxInstanceStore } from "./instance-store.js";
 import { ProjectionCapability, getWorkspaceProjection, provideWorkspaceProjection } from "./projection.js";
+import { DEFAULT_JOURNAL_DIR, EXIT_SENTINEL_KEY, EXIT_SENTINEL_NONCE_KEY, decodeJournalRunId, encodeRunId, exitSentinelLine, journalExistsCommand, journalExitProbeCommand, journalFollowCommand, journalListCommand, journalMtimeListCommand, journalPaths, journalReadCommand, journaledCommand, parseExitSentinel, parseJournalExit, parseJournalMtimeListing } from "./journal.js";
+import { chunkFingerprint, chunkFingerprintIgnoringThreadId, chunkThreadId, createRunScopedIdGen } from "./chunk-identity.js";
+import { DEFAULT_MAX_OUT_OF_BAND_SKIP, JournalReplayDivergedError, JournalReplayThreadIdMismatchError, alignToStoredLog, isBridgeCustomChunk } from "./align.js";
+import { DurableAttachNotSupportedError, DurableRunIdRequiredError, DurableThreadIdRequiredError, SandboxDurabilityCapability, alignedIfAttaching, getSandboxDurability, journalOptionsFor, provideSandboxDurability, resolveDurableRunId, resolveDurableThreadId } from "./durability.js";
+import { computeSandboxKey, computeWorkspaceHash } from "./key.js";
+import { bearer, createSecrets, isSecretRef, resolveAllSecrets, resolveBearer, resolveSecret } from "./secrets.js";
+import { isSandboxToolCall } from "./tool-history.js";
+import { formatWorkspaceScriptsSection, mergeAgentsContent, resolveGitSkillDir, writeAgentsFile } from "./agents-file.js";
+import { DEFAULT_WORKSPACE_ROOT, bootstrapWorkspace, detectPackageManager } from "./bootstrap.js";
+import { diffSnapshots, watchWorkspace } from "./watch.js";
 import { withSandbox } from "./middleware.js";
 import { defineSandbox } from "./sandbox.js";
 import { agentSkill, defineWorkspace, fileSkill, gitSkill, gitSource, githubRepo, localSource, mcpSkill } from "./workspace.js";
-import { bearer, createSecrets, isSecretRef, resolveAllSecrets, resolveBearer, resolveSecret } from "./secrets.js";
 import { commandAliases, defineSandboxPolicy, evaluateCommand } from "./policy.js";
-import { InMemoryLockStore, InMemorySandboxStore } from "./store.js";
-import { DEFAULT_WORKSPACE_ROOT, bootstrapWorkspace, detectPackageManager } from "./bootstrap.js";
 import { resolveHarnessCwd } from "./harness-cwd.js";
-import { formatWorkspaceScriptsSection, mergeAgentsContent, resolveGitSkillDir, writeAgentsFile } from "./agents-file.js";
 import { createExecBackedGit } from "./git-exec.js";
-import { spawnNdjson, toLines } from "./runner.js";
+import { DEFAULT_ATTACH_JOURNAL_WAIT_MS, DEFAULT_ATTACH_PROBE_INTERVAL_MS, JournalAttachUnavailableError, awaitAttachableJournal } from "./attach-preflight.js";
+import { decodeBase64Stream, toJournalLines } from "./journal-bytes.js";
+import { DEFAULT_JOURNAL_POLL_MS, journalReadStrategy, readJournal } from "./journal-reader.js";
+import { readJournalNdjson, spawnNdjson, startJournaledAgent, toLines } from "./runner.js";
+import { DEFAULT_MAX_DELETES, DEFAULT_ORPHAN_TTL_MS, pruneJournals } from "./journal-sweep.js";
+import { DEFAULT_FENCE_QUIET_MS, RunClaimLostError, RunClaimNotAcquiredError } from "./claim.js";
+import { RunController, pipeToRunLog } from "./run.js";
+import { DEFAULT_EXIT_PROBE_BYTES, DEFAULT_MAX_RUNS, DEFAULT_RUN_BUDGET_MS, probeRunExit, reapDetachedRuns } from "./reap.js";
+import { SandboxReclaimFailedError, reclaimSandbox, sandboxReclaimer } from "./reclaim.js";
+import { RunDriverPipeOutsideClaimError, sandboxRunDriver } from "./driver.js";
 import { BRIDGED_MCP_SERVER_NAME, createToolBridgeCore, handleBridgeJsonRpc, hostForSandbox, nodeHttpBridgeProvisioner, startHostToolBridge, timingSafeBearerEqual } from "./tool-bridge.js";
 import { createBridgeEventChannel, mergeChunkStreams } from "./bridge-events.js";
 import { executeHostTool, httpRemoteToolExecutor, isToolExecRequest, remoteToolStubs, toolDescriptors } from "./remote-tools.js";
-import { InMemoryRunEventLog, isTerminalRunStatus } from "./run-log.js";
-import { RunController, pipeToRunLog } from "./run.js";
 import { APPROVAL_REQUESTED_EVENT, approvalId, buildApprovalRequestedEvent, resolveApproval } from "./approvals.js";
-import { diffSnapshots, watchWorkspace } from "./watch.js";
-import { computeSandboxKey, computeWorkspaceHash } from "./key.js";
 import { MissingSandboxError, UnsupportedCapabilityError } from "./errors.js";
-export {
-  APPROVAL_REQUESTED_EVENT,
-  BRIDGED_MCP_SERVER_NAME,
-  DEFAULT_WORKSPACE_ROOT,
-  InMemoryLockStore,
-  InMemoryRunEventLog,
-  InMemorySandboxStore,
-  LocksCapability,
-  MissingSandboxError,
-  ProjectionCapability,
-  RunController,
-  SandboxCapability,
-  SandboxPolicyCapability,
-  SandboxStoreCapability,
-  ToolBridgeProvisionerCapability,
-  UnsupportedCapabilityError,
-  agentSkill,
-  approvalId,
-  bearer,
-  bootstrapWorkspace,
-  buildApprovalRequestedEvent,
-  commandAliases,
-  computeSandboxKey,
-  computeWorkspaceHash,
-  createBridgeEventChannel,
-  createExecBackedGit,
-  createSecrets,
-  createToolBridgeCore,
-  defineSandbox,
-  defineSandboxPolicy,
-  defineWorkspace,
-  detectPackageManager,
-  diffSnapshots,
-  evaluateCommand,
-  executeHostTool,
-  fileSkill,
-  formatWorkspaceScriptsSection,
-  getLocks,
-  getSandbox,
-  getSandboxPolicy,
-  getSandboxStore,
-  getToolBridgeProvisioner,
-  getWorkspaceProjection,
-  gitSkill,
-  gitSource,
-  githubRepo,
-  handleBridgeJsonRpc,
-  hostForSandbox,
-  httpRemoteToolExecutor,
-  isSecretRef,
-  isTerminalRunStatus,
-  isToolExecRequest,
-  localSource,
-  mcpSkill,
-  mergeAgentsContent,
-  mergeChunkStreams,
-  nodeHttpBridgeProvisioner,
-  pipeToRunLog,
-  provideLocks,
-  provideSandbox,
-  provideSandboxPolicy,
-  provideSandboxStore,
-  provideToolBridgeProvisioner,
-  provideWorkspaceProjection,
-  remoteToolStubs,
-  resolveAllSecrets,
-  resolveApproval,
-  resolveBearer,
-  resolveGitSkillDir,
-  resolveHarnessCwd,
-  resolveSecret,
-  spawnNdjson,
-  startHostToolBridge,
-  timingSafeBearerEqual,
-  toLines,
-  toolDescriptors,
-  watchWorkspace,
-  withSandbox,
-  writeAgentsFile
-};
-//# sourceMappingURL=index.js.map
+export { APPROVAL_REQUESTED_EVENT, BRIDGED_MCP_SERVER_NAME, DEFAULT_ATTACH_JOURNAL_WAIT_MS, DEFAULT_ATTACH_PROBE_INTERVAL_MS, DEFAULT_EXIT_PROBE_BYTES, DEFAULT_FENCE_QUIET_MS, DEFAULT_JOURNAL_DIR, DEFAULT_JOURNAL_POLL_MS, DEFAULT_MAX_DELETES, DEFAULT_MAX_OUT_OF_BAND_SKIP, DEFAULT_MAX_RUNS, DEFAULT_ORPHAN_TTL_MS, DEFAULT_RUN_BUDGET_MS, DEFAULT_WORKSPACE_ROOT, DurableAttachNotSupportedError, DurableRunIdRequiredError, DurableThreadIdRequiredError, EXIT_SENTINEL_KEY, EXIT_SENTINEL_NONCE_KEY, InMemorySandboxInstanceStore, JournalAttachUnavailableError, JournalReplayDivergedError, JournalReplayThreadIdMismatchError, MissingSandboxError, ProjectionCapability, RunClaimLostError, RunClaimNotAcquiredError, RunController, RunDriverPipeOutsideClaimError, SandboxCapability, SandboxDurabilityCapability, SandboxInstanceStoreCapability, SandboxPolicyCapability, SandboxReclaimFailedError, ToolBridgeProvisionerCapability, UnsupportedCapabilityError, agentSkill, alignToStoredLog, alignedIfAttaching, approvalId, awaitAttachableJournal, bearer, bootstrapWorkspace, buildApprovalRequestedEvent, chunkFingerprint, chunkFingerprintIgnoringThreadId, chunkThreadId, commandAliases, computeSandboxKey, computeWorkspaceHash, createBridgeEventChannel, createExecBackedGit, createRunScopedIdGen, createSecrets, createToolBridgeCore, decodeBase64Stream, decodeJournalRunId, defineSandbox, defineSandboxInstanceStore, defineSandboxPolicy, defineWorkspace, detectPackageManager, diffSnapshots, encodeRunId, evaluateCommand, executeHostTool, exitSentinelLine, fileSkill, formatWorkspaceScriptsSection, getSandbox, getSandboxDurability, getSandboxInstanceStore, getSandboxPolicy, getToolBridgeProvisioner, getWorkspaceProjection, gitSkill, gitSource, githubRepo, handleBridgeJsonRpc, hostForSandbox, httpRemoteToolExecutor, isBridgeCustomChunk, isSandboxToolCall, isSecretRef, isToolExecRequest, journalExistsCommand, journalExitProbeCommand, journalFollowCommand, journalListCommand, journalMtimeListCommand, journalOptionsFor, journalPaths, journalReadCommand, journalReadStrategy, journaledCommand, localSource, mcpSkill, mergeAgentsContent, mergeChunkStreams, nodeHttpBridgeProvisioner, parseExitSentinel, parseJournalExit, parseJournalMtimeListing, pipeToRunLog, probeRunExit, provideSandbox, provideSandboxDurability, provideSandboxInstanceStore, provideSandboxPolicy, provideToolBridgeProvisioner, provideWorkspaceProjection, pruneJournals, readJournal, readJournalNdjson, reapDetachedRuns, reclaimSandbox, remoteToolStubs, resolveAllSecrets, resolveApproval, resolveBearer, resolveDurableRunId, resolveDurableThreadId, resolveGitSkillDir, resolveHarnessCwd, resolveSecret, sandboxReclaimer, sandboxRunDriver, spawnNdjson, startHostToolBridge, startJournaledAgent, timingSafeBearerEqual, toJournalLines, toLines, toolDescriptors, watchWorkspace, withSandbox, writeAgentsFile };

package/dist/esm/instance-store.d.ts

@@ -0,0 +1,88 @@
+/** One persisted sandbox instance, keyed by the compound sandbox instance key. */
+export interface SandboxInstanceRecord {
+    /** Compound key (see `computeSandboxKey`). */
+    key: string;
+    /** Provider name that owns `providerSandboxId`. */
+    provider: string;
+    /** Provider-assigned sandbox id used to resume. */
+    providerSandboxId: string;
+    /** Most recent snapshot id, when the provider supports snapshots. */
+    latestSnapshotId?: string;
+    threadId: string;
+    latestRunId?: string;
+    /**
+     * Epoch ms of last write (for keepAlive / GC by the host app).
+     */
+    updatedAt: number;
+}
+/**
+ * Maps a compound key to the provider sandbox that should be resumed.
+ *
+ * Implement against your own database (BYO). Prove the contract with
+ * `runSandboxInstanceStoreConformance` from `@tanstack/ai-sandbox/testkit`.
+ */
+export interface SandboxInstanceStore {
+    /**
+     * Return the record for `key`, or `null` if none exists.
+     *
+     * INVARIANT: missing keys return `null` (never throw).
+     */
+    get: (key: string) => Promise<SandboxInstanceRecord | null>;
+    /**
+     * Insert or fully replace the record for `record.key`.
+     *
+     * INVARIANT (full replace): omitted optional fields (`latestSnapshotId`,
+     * `latestRunId`) MUST clear any previously stored values. Do not merge with
+     * the prior row — a create-without-snapshot path must not leave a stale
+     * snapshot id.
+     */
+    upsert: (record: SandboxInstanceRecord) => Promise<void>;
+    /**
+     * Remove the record for `key`.
+     *
+     * INVARIANT: deleting a missing key is a **no-op** (must not throw).
+     */
+    delete: (key: string) => Promise<void>;
+}
+/**
+ * Type a {@link SandboxInstanceStore} implementation inline: pass the object and
+ * get autocomplete + contract checking, with no separate
+ * `: SandboxInstanceStore` annotation. Hand the result to
+ * `withSandbox(sandbox, { instances })`. Matches `defineLock` /
+ * `defineMessageStore` style helpers elsewhere in the monorepo.
+ */
+export declare function defineSandboxInstanceStore(store: SandboxInstanceStore): SandboxInstanceStore;
+/**
+ * Capability for the instance map — the ambient alternative to
+ * `withSandbox(sandbox, { instances })`. Provide it from any middleware with
+ * {@link provideSandboxInstanceStore}; `withSandbox` reads it when no explicit
+ * option was passed.
+ */
+export declare const SandboxInstanceStoreCapability: import('@tanstack/ai').Capability<SandboxInstanceStore, "sandbox-instance-store">;
+/** Destructured accessors: `getSandboxInstanceStore` / `provideSandboxInstanceStore`. */
+export declare const getSandboxInstanceStore: import('@tanstack/ai').CapabilityGetter<SandboxInstanceStore>, provideSandboxInstanceStore: import('@tanstack/ai').CapabilityProvider<SandboxInstanceStore>;
+/** In-memory {@link SandboxInstanceStore}. Resume works only within one process. */
+export declare class InMemorySandboxInstanceStore implements SandboxInstanceStore {
+    private readonly map;
+    get(key: string): Promise<SandboxInstanceRecord | null>;
+    upsert(record: SandboxInstanceRecord): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Wiring note: hand the store straight to the consumer —
+ * `withSandbox(sandbox, { instances: store })`. That cannot be mis-ordered,
+ * unlike a separate provider middleware composed after `withSandbox` (which
+ * silently degrades to the in-memory fallback).
+ *
+ * ```ts
+ * middleware: [
+ *   withLocks(locks), // from @tanstack/ai/locks — multi-replica
+ *   withSandbox(sandbox, { instances: instanceStore }),
+ * ]
+ * ```
+ *
+ * For ambient/platform wiring (a hosting layer injecting infra without touching
+ * the call site), any middleware may still
+ * `provideSandboxInstanceStore(ctx, store)` on the capability bus; an explicit
+ * option takes precedence over it.
+ */