@tanstack/ai-sandbox 0.1.0

package/dist/esm/capabilities.d.ts

@@ -0,0 +1,26 @@
+import { SandboxHandle } from './contracts.js';
+import { LockStore, SandboxStore } from './store.js';
+import { SandboxPolicy } from './policy.js';
+import { ToolBridgeProvisioner } from './tool-bridge.js';
+export declare const SandboxCapability: import('@tanstack/ai').Capability<SandboxHandle, "sandbox">;
+export declare const SandboxStoreCapability: import('@tanstack/ai').Capability<SandboxStore, "sandbox-store">;
+export declare const LocksCapability: import('@tanstack/ai').Capability<LockStore, "locks">;
+/**
+ * The active sandbox policy, provided by `withSandbox` from the definition.
+ * Harness adapters read it to map allow/ask/deny rules onto their native
+ * permission system.
+ */
+export declare const SandboxPolicyCapability: import('@tanstack/ai').Capability<SandboxPolicy, "sandbox-policy">;
+/**
+ * Provisions the MCP tool-bridge endpoint for a run. OPTIONALLY provided by a
+ * serverless/edge orchestrator (e.g. a Durable Object) to override the default
+ * `node:http` host transport. Harness adapters read it via `getOptional` and
+ * fall back to `nodeHttpBridgeProvisioner` when absent.
+ */
+export declare const ToolBridgeProvisionerCapability: import('@tanstack/ai').Capability<ToolBridgeProvisioner, "tool-bridge-provisioner">;
+/** Destructured accessors for adapters: `getSandbox(ctx)` reads the handle. */
+export declare const getSandbox: import('@tanstack/ai').CapabilityGetter<SandboxHandle>, provideSandbox: import('@tanstack/ai').CapabilityProvider<SandboxHandle>;
+export declare const getSandboxStore: import('@tanstack/ai').CapabilityGetter<SandboxStore>, provideSandboxStore: import('@tanstack/ai').CapabilityProvider<SandboxStore>;
+export declare const getLocks: import('@tanstack/ai').CapabilityGetter<LockStore>, provideLocks: import('@tanstack/ai').CapabilityProvider<LockStore>;
+export declare const getSandboxPolicy: import('@tanstack/ai').CapabilityGetter<SandboxPolicy>, provideSandboxPolicy: import('@tanstack/ai').CapabilityProvider<SandboxPolicy>;
+export declare const getToolBridgeProvisioner: import('@tanstack/ai').CapabilityGetter<ToolBridgeProvisioner>, provideToolBridgeProvisioner: import('@tanstack/ai').CapabilityProvider<ToolBridgeProvisioner>;

package/dist/esm/capabilities.js

@@ -0,0 +1,29 @@
+import { createCapability } from "@tanstack/ai";
+const SandboxCapability = createCapability()("sandbox");
+const SandboxStoreCapability = createCapability()("sandbox-store");
+const LocksCapability = createCapability()("locks");
+const SandboxPolicyCapability = createCapability()("sandbox-policy");
+const ToolBridgeProvisionerCapability = createCapability()("tool-bridge-provisioner");
+const [getSandbox, provideSandbox] = SandboxCapability;
+const [getSandboxStore, provideSandboxStore] = SandboxStoreCapability;
+const [getLocks, provideLocks] = LocksCapability;
+const [getSandboxPolicy, provideSandboxPolicy] = SandboxPolicyCapability;
+const [getToolBridgeProvisioner, provideToolBridgeProvisioner] = ToolBridgeProvisionerCapability;
+export {
+  LocksCapability,
+  SandboxCapability,
+  SandboxPolicyCapability,
+  SandboxStoreCapability,
+  ToolBridgeProvisionerCapability,
+  getLocks,
+  getSandbox,
+  getSandboxPolicy,
+  getSandboxStore,
+  getToolBridgeProvisioner,
+  provideLocks,
+  provideSandbox,
+  provideSandboxPolicy,
+  provideSandboxStore,
+  provideToolBridgeProvisioner
+};
+//# sourceMappingURL=capabilities.js.map

package/dist/esm/capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.js","sources":["../../src/capabilities.ts"],"sourcesContent":["/**\n * Capability tokens the sandbox layer provides/consumes through the\n * `@tanstack/ai` middleware capability system.\n *\n * - `SandboxCapability` is PROVIDED by `withSandbox` and REQUIRED by harness\n *   adapters (`requires: [SandboxCapability]`).\n * - `SandboxStoreCapability` / `LocksCapability` are OPTIONALLY required by\n *   `withSandbox`. v1 falls back to in-memory defaults; the future persistence\n *   package PROVIDES durable implementations.\n */\nimport { createCapability } from '@tanstack/ai'\nimport type { SandboxHandle } from './contracts'\nimport type { LockStore, SandboxStore } from './store'\nimport type { SandboxPolicy } from './policy'\nimport type { ToolBridgeProvisioner } from './tool-bridge'\n\nexport const SandboxCapability = createCapability<SandboxHandle>()('sandbox')\n\nexport const SandboxStoreCapability =\n  createCapability<SandboxStore>()('sandbox-store')\n\nexport const LocksCapability = createCapability<LockStore>()('locks')\n\n/**\n * The active sandbox policy, provided by `withSandbox` from the definition.\n * Harness adapters read it to map allow/ask/deny rules onto their native\n * permission system.\n */\nexport const SandboxPolicyCapability =\n  createCapability<SandboxPolicy>()('sandbox-policy')\n\n/**\n * Provisions the MCP tool-bridge endpoint for a run. OPTIONALLY provided by a\n * serverless/edge orchestrator (e.g. a Durable Object) to override the default\n * `node:http` host transport. Harness adapters read it via `getOptional` and\n * fall back to `nodeHttpBridgeProvisioner` when absent.\n */\nexport const ToolBridgeProvisionerCapability =\n  createCapability<ToolBridgeProvisioner>()('tool-bridge-provisioner')\n\n/** Destructured accessors for adapters: `getSandbox(ctx)` reads the handle. */\nexport const [getSandbox, provideSandbox] = SandboxCapability\nexport const [getSandboxStore, provideSandboxStore] = SandboxStoreCapability\nexport const [getLocks, provideLocks] = LocksCapability\nexport const [getSandboxPolicy, provideSandboxPolicy] = SandboxPolicyCapability\nexport const [getToolBridgeProvisioner, provideToolBridgeProvisioner] =\n  ToolBridgeProvisionerCapability\n"],"names":[],"mappings":";AAgBO,MAAM,oBAAoB,iBAAA,EAAkC,SAAS;AAErE,MAAM,yBACX,iBAAA,EAAiC,eAAe;AAE3C,MAAM,kBAAkB,iBAAA,EAA8B,OAAO;AAO7D,MAAM,0BACX,iBAAA,EAAkC,gBAAgB;AAQ7C,MAAM,kCACX,iBAAA,EAA0C,yBAAyB;AAG9D,MAAM,CAAC,YAAY,cAAc,IAAI;AACrC,MAAM,CAAC,iBAAiB,mBAAmB,IAAI;AAC/C,MAAM,CAAC,UAAU,YAAY,IAAI;AACjC,MAAM,CAAC,kBAAkB,oBAAoB,IAAI;AACjD,MAAM,CAAC,0BAA0B,4BAA4B,IAClE;"}

package/dist/esm/contracts.d.ts

@@ -0,0 +1,211 @@
+import { WorkspaceDefinition } from './workspace.js';
+import { SandboxPolicy } from './policy.js';
+/** Static description of what a provider supports. */
+export interface SandboxCapabilities {
+    /** Read/write/list/… via {@link SandboxFs}. Always true (mandatory). */
+    fs: boolean;
+    /** Blocking command execution via {@link SandboxProcess.exec}. Always true (mandatory). */
+    exec: boolean;
+    /** Per-create / per-command environment variables. */
+    env: boolean;
+    /** Expose a port and resolve a reachable channel via {@link SandboxPorts}. */
+    ports: boolean;
+    /** Long-running/background processes via {@link SandboxProcess.spawn}. */
+    backgroundProcesses: boolean;
+    /**
+     * A spawned process exposes a writable host→process stdin
+     * ({@link SpawnHandle.stdin}). `true` for host/Docker; some edge providers
+     * (e.g. Cloudflare) run background processes WITHOUT a writable stdin, so
+     * harness adapters that feed a prompt over stdin must instead deliver it via a
+     * file + shell redirection.
+     */
+    writableStdin: boolean;
+    /** Capture/restore filesystem snapshots via {@link SandboxHandle.snapshot}. */
+    snapshots: boolean;
+    /** Declarative network egress allow/deny policy. */
+    networkPolicy: boolean;
+    /** Filesystem persists across sandbox stop/restart without a snapshot. */
+    durableFilesystem: boolean;
+    /** Branch a new sandbox from current state via {@link SandboxHandle.fork}. */
+    fork: boolean;
+}
+/** Result of a blocking command. */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Options for {@link SandboxProcess.exec} / {@link SandboxProcess.spawn}. */
+export interface ProcessOptions {
+    /** Working directory inside the sandbox. Defaults to the workspace root. */
+    cwd?: string;
+    /** Per-command environment variables, merged over the sandbox env. */
+    env?: Record<string, string>;
+    /** Abort the command/process when this signal fires. */
+    signal?: AbortSignal;
+}
+/**
+ * A live background process. `stdout`/`stderr` are async-iterables of decoded
+ * chunks; `stdin.write` feeds the process (duplex — required for ACP harness
+ * protocols such as Codex / Gemini CLI). There is intentionally NO
+ * reconnect-to-a-running-process in v1 — that belongs to the durable-stream /
+ * persistence layer.
+ */
+export interface SpawnHandle {
+    readonly pid: number;
+    readonly stdout: AsyncIterable<string>;
+    readonly stderr: AsyncIterable<string>;
+    readonly stdin: {
+        write: (data: string) => Promise<void>;
+        end: () => Promise<void>;
+    };
+    /** Resolves with the exit code when the process exits. */
+    wait: () => Promise<number>;
+    kill: (signal?: NodeJS.Signals | number) => Promise<void>;
+}
+export interface SandboxProcess {
+    /** Run a command to completion and capture stdout/stderr/exit code. */
+    exec: (command: string, options?: ProcessOptions) => Promise<ExecResult>;
+    /** Start a long-running/background process with streamable, duplex IO. */
+    spawn: (command: string, options?: ProcessOptions) => Promise<SpawnHandle>;
+}
+/** Common, portable filesystem operations every provider implements. */
+export interface SandboxFs {
+    read: (path: string) => Promise<string>;
+    readBytes: (path: string) => Promise<Uint8Array>;
+    write: (path: string, data: string | Uint8Array) => Promise<void>;
+    list: (path: string) => Promise<Array<{
+        name: string;
+        path: string;
+        type: 'file' | 'dir';
+    }>>;
+    mkdir: (path: string) => Promise<void>;
+    remove: (path: string) => Promise<void>;
+    rename: (from: string, to: string) => Promise<void>;
+    exists: (path: string) => Promise<boolean>;
+    /** Optional — present only when `capabilities.fs` providers advertise watch. */
+    watch?: (path: string, onEvent: (event: {
+        type: string;
+        path: string;
+    }) => void) => Promise<{
+        stop: () => Promise<void>;
+    }>;
+}
+/**
+ * Uniform git surface. Implementations either delegate to the provider's
+ * native git (when advertised) or desugar to `process.exec("git …")`, so the
+ * contract is identical across providers.
+ */
+export interface SandboxGit {
+    clone: (input: {
+        url: string;
+        dir?: string;
+        ref?: string;
+        auth?: {
+            username?: string;
+            token: string;
+        };
+        depth?: number | 'full';
+    }) => Promise<void>;
+    status: (dir?: string) => Promise<string>;
+    add: (paths: Array<string>, dir?: string) => Promise<void>;
+    commit: (message: string, dir?: string) => Promise<void>;
+    push: (dir?: string) => Promise<void>;
+    pull: (dir?: string) => Promise<void>;
+    /** Returns the current branch name. */
+    branch: (dir?: string) => Promise<string>;
+}
+/** A reachable channel to a port inside the sandbox. */
+export interface SandboxChannel {
+    /** URL the host can reach (localhost / host-bound port / authenticated preview URL). */
+    url: string;
+    /** Bearer token gating the channel, when the provider issues one. */
+    token?: string;
+    /**
+     * Ready-to-send HTTP headers that authenticate requests to {@link url}, when
+     * the provider's auth doesn't fit a plain `Authorization: Bearer <token>`
+     * (e.g. Daytona's `x-daytona-preview-token`). Consumers that speak HTTP to the
+     * channel should attach these verbatim; the provider owns the header names so
+     * consumers stay provider-agnostic.
+     */
+    headers?: Record<string, string>;
+}
+export interface SandboxPorts {
+    /** Expose `port` and resolve the best reachable channel for the host. */
+    connect: (port: number) => Promise<SandboxChannel>;
+}
+export interface SandboxEnv {
+    set: (vars: Record<string, string>) => Promise<void>;
+}
+/** Opaque reference to a stored snapshot, used to restore later. */
+export interface SnapshotRef {
+    id: string;
+    label?: string;
+}
+/** The uniform runtime surface a sandbox exposes. */
+export interface SandboxHandle {
+    /** Provider-assigned id used to reconnect to this sandbox. */
+    readonly id: string;
+    /** Provider name (e.g. "docker", "cloudflare", "local-process"). */
+    readonly provider: string;
+    /**
+     * Real filesystem path backing the virtual workspace root (`/workspace`).
+     * Harness CLIs and ACP `newSession` interpret cwd literally — use
+     * {@link resolveHarnessCwd} rather than the virtual path when the provider
+     * maps `/workspace` elsewhere (Daytona, Vercel, local-process).
+     */
+    readonly workspaceRoot?: string;
+    /** What this sandbox can do. */
+    readonly capabilities: SandboxCapabilities;
+    readonly fs: SandboxFs;
+    readonly git: SandboxGit;
+    readonly process: SandboxProcess;
+    readonly ports: SandboxPorts;
+    readonly env: SandboxEnv;
+    /** Capability-gated: throws UnsupportedCapabilityError if `capabilities.snapshots` is false. */
+    snapshot?: (label?: string) => Promise<SnapshotRef>;
+    /** Capability-gated: throws UnsupportedCapabilityError if `capabilities.fork` is false. */
+    fork?: () => Promise<SandboxHandle>;
+    destroy: () => Promise<void>;
+}
+/** Input passed to {@link SandboxProvider.create}. */
+export interface SandboxCreateInput {
+    workspace?: WorkspaceDefinition;
+    policy?: SandboxPolicy;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/** Input passed to {@link SandboxProvider.resume}. */
+export interface SandboxResumeInput {
+    /** Provider-assigned sandbox id recorded by a prior run. */
+    id: string;
+    signal?: AbortSignal;
+}
+/** Input passed to {@link SandboxProvider.restoreSnapshot}. */
+export interface SandboxRestoreInput {
+    snapshotId: string;
+    workspace?: WorkspaceDefinition;
+    policy?: SandboxPolicy;
+    env?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/** Input passed to {@link SandboxProvider.destroy}. */
+export interface SandboxDestroyInput {
+    id: string;
+    signal?: AbortSignal;
+}
+/**
+ * Owns an isolation primitive. Implemented by `@tanstack/ai-sandbox-*`
+ * provider packages.
+ */
+export interface SandboxProvider {
+    readonly name: string;
+    /** Static capability descriptor. */
+    capabilities: () => SandboxCapabilities;
+    create: (input: SandboxCreateInput) => Promise<SandboxHandle>;
+    /** Reconnect to an existing sandbox by id; resolves null if it's gone. */
+    resume: (input: SandboxResumeInput) => Promise<SandboxHandle | null>;
+    /** Capability-gated: present only when `capabilities().snapshots` is true. */
+    restoreSnapshot?: (input: SandboxRestoreInput) => Promise<SandboxHandle>;
+    destroy: (input: SandboxDestroyInput) => Promise<void>;
+}

package/dist/esm/errors.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Thrown when code invokes an optional sandbox capability that the active
+ * provider does not support. Core/middleware should check
+ * `handle.capabilities` BEFORE using an optional capability and degrade
+ * gracefully; this error exists so that a direct call to an unsupported
+ * optional method fails loud instead of silently no-opping.
+ */
+export declare class UnsupportedCapabilityError extends Error {
+    readonly provider: string;
+    readonly capability: string;
+    constructor(provider: string, capability: string, hint?: string);
+}
+/** Thrown when a harness adapter requires a sandbox but none was provided. */
+export declare class MissingSandboxError extends Error {
+    constructor(adapterName: string);
+}

package/dist/esm/errors.js

@@ -0,0 +1,25 @@
+class UnsupportedCapabilityError extends Error {
+  provider;
+  capability;
+  constructor(provider, capability, hint) {
+    super(
+      `Sandbox provider "${provider}" does not support the "${capability}" capability.` + (hint ? ` ${hint}` : "")
+    );
+    this.name = "UnsupportedCapabilityError";
+    this.provider = provider;
+    this.capability = capability;
+  }
+}
+class MissingSandboxError extends Error {
+  constructor(adapterName) {
+    super(
+      `Adapter "${adapterName}" requires a sandbox. Add withSandbox(defineSandbox({ ... })) to chat() middleware.`
+    );
+    this.name = "MissingSandboxError";
+  }
+}
+export {
+  MissingSandboxError,
+  UnsupportedCapabilityError
+};
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sources":["../../src/errors.ts"],"sourcesContent":["/**\n * Thrown when code invokes an optional sandbox capability that the active\n * provider does not support. Core/middleware should check\n * `handle.capabilities` BEFORE using an optional capability and degrade\n * gracefully; this error exists so that a direct call to an unsupported\n * optional method fails loud instead of silently no-opping.\n */\nexport class UnsupportedCapabilityError extends Error {\n  readonly provider: string\n  readonly capability: string\n\n  constructor(provider: string, capability: string, hint?: string) {\n    super(\n      `Sandbox provider \"${provider}\" does not support the \"${capability}\" capability.` +\n        (hint ? ` ${hint}` : ''),\n    )\n    this.name = 'UnsupportedCapabilityError'\n    this.provider = provider\n    this.capability = capability\n  }\n}\n\n/** Thrown when a harness adapter requires a sandbox but none was provided. */\nexport class MissingSandboxError extends Error {\n  constructor(adapterName: string) {\n    super(\n      `Adapter \"${adapterName}\" requires a sandbox. Add withSandbox(defineSandbox({ ... })) to chat() middleware.`,\n    )\n    this.name = 'MissingSandboxError'\n  }\n}\n"],"names":[],"mappings":"AAOO,MAAM,mCAAmC,MAAM;AAAA,EAC3C;AAAA,EACA;AAAA,EAET,YAAY,UAAkB,YAAoB,MAAe;AAC/D;AAAA,MACE,qBAAqB,QAAQ,2BAA2B,UAAU,mBAC/D,OAAO,IAAI,IAAI,KAAK;AAAA,IAAA;AAEzB,SAAK,OAAO;AACZ,SAAK,WAAW;AAChB,SAAK,aAAa;AAAA,EACpB;AACF;AAGO,MAAM,4BAA4B,MAAM;AAAA,EAC7C,YAAY,aAAqB;AAC/B;AAAA,MACE,YAAY,WAAW;AAAA,IAAA;AAEzB,SAAK,OAAO;AAAA,EACd;AACF;"}

package/dist/esm/git-exec.d.ts

@@ -0,0 +1,2 @@
+import { SandboxGit, SandboxProcess } from './contracts.js';
+export declare function createExecBackedGit(process: SandboxProcess, defaultRoot: string): SandboxGit;

package/dist/esm/git-exec.js

@@ -0,0 +1,68 @@
+function q(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function assertNoLeadingDash(value, name) {
+  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';
+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()
+  };
+}
+export {
+  createExecBackedGit
+};
+//# sourceMappingURL=git-exec.js.map

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

@@ -0,0 +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;"}

package/dist/esm/harness-cwd.d.ts

@@ -0,0 +1,2 @@
+import { SandboxHandle } from './contracts.js';
+export declare function resolveHarnessCwd(handle: SandboxHandle, virtualCwd?: string): string;

package/dist/esm/harness-cwd.js

@@ -0,0 +1,24 @@
+import * as path from "node:path";
+import { DEFAULT_WORKSPACE_ROOT } from "./bootstrap.js";
+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;
+}
+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;
+}
+export {
+  resolveHarnessCwd
+};
+//# sourceMappingURL=harness-cwd.js.map

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

@@ -0,0 +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;"}

package/dist/esm/index.d.ts

@@ -0,0 +1,39 @@
+export { SandboxCapability, SandboxStoreCapability, LocksCapability, SandboxPolicyCapability, ToolBridgeProvisionerCapability, getSandbox, provideSandbox, getSandboxStore, provideSandboxStore, getLocks, provideLocks, getSandboxPolicy, provideSandboxPolicy, getToolBridgeProvisioner, provideToolBridgeProvisioner, } from './capabilities.js';
+export { ProjectionCapability, getWorkspaceProjection, provideWorkspaceProjection, } from './projection.js';
+export type { WorkspaceProjection } from './projection.js';
+export { withSandbox } from './middleware.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';
+export type { WorkspaceDefinition, WorkspaceSource, WorkspaceSkill, PackageManager, McpConfig, } from './workspace.js';
+export { createSecrets, bearer, isSecretRef, resolveSecret, resolveBearer, resolveAllSecrets, } from './secrets.js';
+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 { 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 { resolveApproval, approvalId, buildApprovalRequestedEvent, APPROVAL_REQUESTED_EVENT, } from './approvals.js';
+export type { ResolveApprovalInput, ApprovalOutcome } from './approvals.js';
+export { watchWorkspace, diffSnapshots } from './watch.js';
+export type { SandboxFileEvent, FileEvent, FileEventType, WatchOptions, SandboxWatchHandle, } from './watch.js';
+export { computeSandboxKey, computeWorkspaceHash } from './key.js';
+export type { SandboxKeyInput } from './key.js';
+export { UnsupportedCapabilityError, MissingSandboxError } from './errors.js';

package/dist/esm/index.js

@@ -0,0 +1,103 @@
+import { LocksCapability, SandboxCapability, SandboxPolicyCapability, SandboxStoreCapability, ToolBridgeProvisionerCapability, getLocks, getSandbox, getSandboxPolicy, getSandboxStore, getToolBridgeProvisioner, provideLocks, provideSandbox, provideSandboxPolicy, provideSandboxStore, provideToolBridgeProvisioner } from "./capabilities.js";
+import { ProjectionCapability, getWorkspaceProjection, provideWorkspaceProjection } from "./projection.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 { 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

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;"}

package/dist/esm/key.d.ts

@@ -0,0 +1,20 @@
+import { WorkspaceDefinition } from './workspace.js';
+/** Inputs that, together, identify one resumable sandbox instance. */
+export interface SandboxKeyInput {
+    threadId: string;
+    sandboxId: string;
+    providerName: string;
+    workspace?: WorkspaceDefinition;
+    /** Optional tenant scoping pulled from runtimeContext. */
+    tenant?: {
+        userId?: string;
+        orgId?: string;
+    };
+}
+/**
+ * Hash of the parts of a workspace that change what the agent sees. Secrets are
+ * intentionally excluded (rotating a token must not orphan the sandbox).
+ */
+export declare function computeWorkspaceHash(workspace: WorkspaceDefinition | undefined): string;
+/** Compute the compound sandbox instance key. */
+export declare function computeSandboxKey(input: SandboxKeyInput): string;