@tanstack/ai-sandbox 0.1.0

package/src/contracts.ts

@@ -0,0 +1,236 @@
+/**
+ * Provider-agnostic sandbox contracts.
+ *
+ * A {@link SandboxProvider} owns an isolation primitive (Docker container,
+ * Cloudflare DO-backed container, a local OS process tree, …) and knows how to
+ * create / resume / restore / destroy a {@link SandboxHandle}. A
+ * `SandboxHandle` is the uniform runtime surface every consumer (harness
+ * adapters, the workspace bootstrap engine, advanced users) codes against.
+ *
+ * Providers differ in what they can do — see {@link SandboxCapabilities}. The
+ * mandatory `fs` and `exec` capabilities are guaranteed by the contract;
+ * everything else is optional and capability-gated. Calling an unsupported
+ * optional method throws {@link UnsupportedCapabilityError} rather than
+ * silently no-opping.
+ */
+import type { WorkspaceDefinition } from './workspace'
+import type { SandboxPolicy } from './policy'
+
+/** 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/src/errors.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 class UnsupportedCapabilityError extends Error {
+  readonly provider: string
+  readonly capability: string
+
+  constructor(provider: string, capability: string, hint?: string) {
+    super(
+      `Sandbox provider "${provider}" does not support the "${capability}" capability.` +
+        (hint ? ` ${hint}` : ''),
+    )
+    this.name = 'UnsupportedCapabilityError'
+    this.provider = provider
+    this.capability = capability
+  }
+}
+
+/** Thrown when a harness adapter requires a sandbox but none was provided. */
+export class MissingSandboxError extends Error {
+  constructor(adapterName: string) {
+    super(
+      `Adapter "${adapterName}" requires a sandbox. Add withSandbox(defineSandbox({ ... })) to chat() middleware.`,
+    )
+    this.name = 'MissingSandboxError'
+  }
+}

package/src/git-exec.ts

@@ -0,0 +1,114 @@
+/**
+ * An exec-backed {@link SandboxGit} implementation. Providers without a native
+ * git API (local-process, Docker) get a uniform `sandbox.git` by desugaring to
+ * `process.exec("git …")`. Providers WITH native git (Daytona, Cloudflare) may
+ * supply their own implementation instead.
+ *
+ * Security:
+ * - Every interpolated value is single-quote escaped (no shell injection).
+ * - A `--` end-of-options separator precedes untrusted positionals and values
+ *   are rejected if they begin with `-`, so a repo URL / ref / path can't
+ *   smuggle a git flag (e.g. `--upload-pack=…`).
+ * - Auth tokens NEVER appear in argv (they'd leak via `ps` / process logs).
+ *   Instead a one-shot `credential.helper` reads the token from the child
+ *   process ENV. The helper string is single-quoted so the OUTER shell never
+ *   expands the env var — only git's own helper subshell does, at use time.
+ *
+ * NOTE: `SandboxProcess.exec` takes a command STRING by design (the sandbox
+ * runs shell commands), so we mitigate flag smuggling with `--` + validation
+ * rather than an argv array.
+ */
+import type { SandboxGit, SandboxProcess } from './contracts'
+
+/** POSIX single-quote escape: wrap in '…' and escape embedded quotes. */
+function q(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}
+
+/** Reject values that could be parsed as a git flag when used as a positional. */
+function assertNoLeadingDash(value: string, name: string): void {
+  if (value.startsWith('-')) {
+    throw new Error(
+      `git-exec: ${name} "${value}" must not begin with "-" (argument-injection guard).`,
+    )
+  }
+}
+
+// Credential helper that prints creds read from the child ENV. Single-quoted at
+// the call site so the outer shell passes it literally; git expands the vars in
+// its own helper subshell, keeping the token out of argv.
+const CREDENTIAL_HELPER =
+  '!f() { echo "username=${GIT_ASKPASS_USER}"; echo "password=${GIT_ASKPASS_TOKEN}"; }; f'
+
+export function createExecBackedGit(
+  process: SandboxProcess,
+  defaultRoot: string,
+): SandboxGit {
+  const at = (dir?: string): string => {
+    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 !== undefined) assertNoLeadingDash(ref, 'ref')
+      const refArg = ref ? `--branch ${q(ref)} ` : ''
+      const resolvedDepth = depth ?? 1
+      // `depth` is interpolated unquoted into the command, so validate it the
+      // same way other positionals are guarded — a non-positive-integer (e.g. an
+      // untyped caller passing a string) must never reach the shell.
+      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(),
+  }
+}

package/src/harness-cwd.ts

@@ -0,0 +1,38 @@
+/**
+ * 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`, …).
+ */
+import * as path from 'node:path'
+import { DEFAULT_WORKSPACE_ROOT } from './bootstrap'
+import type { SandboxHandle } from './contracts'
+
+function mapVirtualWorkspacePath(virtualCwd: string, realRoot: string): string {
+  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
+}
+
+export function resolveHarnessCwd(
+  handle: SandboxHandle,
+  virtualCwd: string = DEFAULT_WORKSPACE_ROOT,
+): string {
+  if (handle.provider === 'local-process') {
+    return mapVirtualWorkspacePath(virtualCwd, handle.id)
+  }
+
+  const root = handle.workspaceRoot
+  if (root !== undefined && root !== DEFAULT_WORKSPACE_ROOT) {
+    return mapVirtualWorkspacePath(virtualCwd, root)
+  }
+
+  return virtualCwd
+}

package/src/index.ts

@@ -0,0 +1,222 @@
+// Capability tokens + accessors
+export {
+  SandboxCapability,
+  SandboxStoreCapability,
+  LocksCapability,
+  SandboxPolicyCapability,
+  ToolBridgeProvisionerCapability,
+  getSandbox,
+  provideSandbox,
+  getSandboxStore,
+  provideSandboxStore,
+  getLocks,
+  provideLocks,
+  getSandboxPolicy,
+  provideSandboxPolicy,
+  getToolBridgeProvisioner,
+  provideToolBridgeProvisioner,
+} from './capabilities'
+
+// Workspace projection capability (provided by withSandbox, consumed by harness adapters)
+export {
+  ProjectionCapability,
+  getWorkspaceProjection,
+  provideWorkspaceProjection,
+} from './projection'
+export type { WorkspaceProjection } from './projection'
+
+// Middleware
+export { withSandbox } from './middleware'
+
+// Sandbox definition + lifecycle
+export { defineSandbox } from './sandbox'
+export type {
+  SandboxConfig,
+  SandboxDefinition,
+  SandboxEnsureContext,
+  SandboxLifecycle,
+  SandboxHooks,
+  ReuseStrategy,
+  SnapshotStrategy,
+} from './sandbox'
+
+// Workspace
+export {
+  defineWorkspace,
+  gitSource,
+  githubRepo,
+  localSource,
+  fileSkill,
+  agentSkill,
+  mcpSkill,
+  gitSkill,
+} from './workspace'
+export type {
+  WorkspaceDefinition,
+  WorkspaceSource,
+  WorkspaceSkill,
+  PackageManager,
+  McpConfig,
+} from './workspace'
+
+// Secrets
+export {
+  createSecrets,
+  bearer,
+  isSecretRef,
+  resolveSecret,
+  resolveBearer,
+  resolveAllSecrets,
+} from './secrets'
+export type { SecretRef, Secrets, BearerRef } from './secrets'
+
+// Policy
+export { defineSandboxPolicy, evaluateCommand, commandAliases } from './policy'
+export type {
+  SandboxPolicy,
+  PolicyDecision,
+  CommandRules,
+  CapabilityRules,
+} from './policy'
+
+// Provider + handle contracts
+export type {
+  SandboxProvider,
+  SandboxHandle,
+  SandboxCapabilities,
+  SandboxFs,
+  SandboxGit,
+  SandboxProcess,
+  SandboxPorts,
+  SandboxEnv,
+  SandboxChannel,
+  SpawnHandle,
+  ExecResult,
+  ProcessOptions,
+  SnapshotRef,
+  SandboxCreateInput,
+  SandboxResumeInput,
+  SandboxRestoreInput,
+  SandboxDestroyInput,
+} from './contracts'
+
+// Stores (interfaces + in-memory defaults)
+export { InMemorySandboxStore, InMemoryLockStore } from './store'
+export type { SandboxStore, LockStore, SandboxRecord } from './store'
+
+// Bootstrap engine (exported for provider/adapter authors + tests)
+export {
+  bootstrapWorkspace,
+  detectPackageManager,
+  DEFAULT_WORKSPACE_ROOT,
+} from './bootstrap'
+export { resolveHarnessCwd } from './harness-cwd'
+export type { BootstrapResult } from './bootstrap'
+
+// AGENTS.md writer + gitSkill path helper (used by bootstrap + harness adapters)
+export {
+  writeAgentsFile,
+  resolveGitSkillDir,
+  formatWorkspaceScriptsSection,
+  mergeAgentsContent,
+} from './agents-file'
+
+// Exec-backed git helper (for providers without native git)
+export { createExecBackedGit } from './git-exec'
+
+// Harness runner: spawn an agent CLI in a sandbox + stream NDJSON stdout
+export { spawnNdjson, toLines } from './runner'
+export type { SpawnNdjsonOptions } from './runner'
+
+// MCP tool-proxy bridge (shared by harness adapters): transport-agnostic core
+// + the node:http host transport + a fetch-friendly JSON-RPC dispatcher.
+export {
+  startHostToolBridge,
+  hostForSandbox,
+  createToolBridgeCore,
+  handleBridgeJsonRpc,
+  timingSafeBearerEqual,
+  nodeHttpBridgeProvisioner,
+  BRIDGED_MCP_SERVER_NAME,
+} from './tool-bridge'
+export type {
+  HostToolBridge,
+  StartBridgeOptions,
+  ToolBridgeCore,
+  ToolBridgeCoreOptions,
+  ToolDescriptor,
+  ToolCallResult,
+  BridgePermission,
+  PermissionToolResult,
+  ToolBridgeProvisioner,
+  ToolBridgeProvisionOptions,
+  ProvisionedBridge,
+} from './tool-bridge'
+
+// Surface bridged-tool custom events (e.g. code mode console logs) on a harness
+// adapter's live output stream.
+export { createBridgeEventChannel, mergeChunkStreams } from './bridge-events'
+export type { BridgeEventChannel } from './bridge-events'
+
+// Host-tool delegation for the co-located ("combined") model: harness + bridge
+// run in-container; only chat()-tool EXECUTION crosses back to the orchestrator.
+export {
+  remoteToolStubs,
+  toolDescriptors,
+  httpRemoteToolExecutor,
+  executeHostTool,
+  isToolExecRequest,
+} from './remote-tools'
+export type {
+  RemoteToolExecutor,
+  RemoteToolExecuteOptions,
+  ToolExecRequest,
+} from './remote-tools'
+
+// Resumable run event-log — the primitive that lets a trigger start a run and
+// return while a durable orchestrator drives it and clients tail from a cursor.
+export { InMemoryRunEventLog, isTerminalRunStatus } from './run-log'
+export type {
+  RunEventLog,
+  RunRecord,
+  RunEvent,
+  RunStatus,
+  TerminalRunStatus,
+  RunError,
+  RunEventLogReadOptions,
+} from './run-log'
+
+// Run driver — pump a chat() stream into the event-log so a trigger returns
+// immediately while a durable orchestrator drives the run and clients tail it.
+export { pipeToRunLog, RunController } from './run'
+export type {
+  PipeToRunLogOptions,
+  RunControllerStartInput,
+  RunHandle,
+} from './run'
+
+// Interactive approvals (shared by harness adapters)
+export {
+  resolveApproval,
+  approvalId,
+  buildApprovalRequestedEvent,
+  APPROVAL_REQUESTED_EVENT,
+} from './approvals'
+export type { ResolveApprovalInput, ApprovalOutcome } from './approvals'
+
+// File-event watch (low-level workspace observer)
+export { watchWorkspace, diffSnapshots } from './watch'
+export type {
+  SandboxFileEvent,
+  FileEvent,
+  FileEventType,
+  WatchOptions,
+  SandboxWatchHandle,
+} from './watch'
+
+// Keying
+export { computeSandboxKey, computeWorkspaceHash } from './key'
+export type { SandboxKeyInput } from './key'
+
+// Errors
+export { UnsupportedCapabilityError, MissingSandboxError } from './errors'