@tanstack/ai-sandbox 0.1.0

package/src/agents-file.ts

@@ -0,0 +1,101 @@
+/**
+ * Universal AGENTS.md writer with per-CLI symlink projection, plus the
+ * canonical helper for locating cloned gitSkill repositories inside a sandbox.
+ *
+ * The known-names set below lists the canonical instruction-file names for
+ * each AI coding assistant CLI. Keep the list in one place so it is easy to
+ * extend. The copy fallback ensures correctness on platforms without symlink
+ * support (e.g. Windows).
+ *
+ * External per-CLI convention: each assistant looks for its own instruction
+ * file by name (CLAUDE.md for Claude Code, GEMINI.md for Gemini CLI, …).
+ * We write a single authoritative AGENTS.md and point each name at it.
+ */
+import type { SandboxHandle } from './contracts'
+import type { WorkspaceSkill } from './workspace'
+
+/** CLI instruction-file names that should resolve to AGENTS.md. */
+const SYMLINK_NAMES: ReadonlyArray<string> = ['CLAUDE.md', 'GEMINI.md']
+
+/**
+ * Resolve the directory a `gitSkill` repo is cloned into when no explicit
+ * `into` override is provided. The convention is:
+ *
+ *   `<root>/.tanstack-skills/<basename>`
+ *
+ * where `basename` is derived from the `repo` field by taking the last
+ * path segment and stripping a trailing `.git` suffix.
+ *
+ * Per-harness projectors (e.g. the Claude Code adapter) import this helper
+ * so they can locate cloned skill repos consistently.
+ *
+ * @param root  - Workspace root inside the sandbox (e.g. `/workspace`).
+ * @param skill - A `WorkspaceSkill` of `kind === 'git'`.
+ */
+export function resolveGitSkillDir(
+  root: string,
+  skill: Extract<WorkspaceSkill, { kind: 'git' }>,
+): string {
+  const rawBasename = skill.repo.split('/').pop() ?? skill.repo
+  const basename = rawBasename.endsWith('.git')
+    ? rawBasename.slice(0, -4)
+    : rawBasename
+  return `${root}/.tanstack-skills/${basename}`
+}
+
+/** Format workspace scripts as a `## Workspace scripts` markdown section. */
+export function formatWorkspaceScriptsSection(
+  scripts: Record<string, string>,
+): string {
+  const names = Object.keys(scripts).sort()
+  if (names.length === 0) return ''
+  const lines = names.map((name) => `- ${name} → ${scripts[name]}`)
+  return `## Workspace scripts\n\n${lines.join('\n')}`
+}
+
+/**
+ * Merge base AGENTS.md content with an optional workspace scripts section.
+ * Returns `undefined` when there is nothing to write.
+ */
+export function mergeAgentsContent(
+  base: string | undefined,
+  scripts: Record<string, string> | undefined,
+): string | undefined {
+  const scriptsSection =
+    scripts !== undefined ? formatWorkspaceScriptsSection(scripts) : ''
+  if (base === undefined && scriptsSection.length === 0) return undefined
+  if (base === undefined) return scriptsSection
+  if (scriptsSection.length === 0) return base
+  return `${base.trimEnd()}\n\n${scriptsSection}`
+}
+
+/** Escape a string for safe use as a single-quoted shell argument. */
+function sqEscape(value: string): string {
+  return value.replace(/'/g, `'\\''`)
+}
+
+/**
+ * Write `AGENTS.md` under `root` and create per-CLI symlinks (or copies as a
+ * fallback when `ln -s` is unavailable).
+ *
+ * @param handle - The sandbox handle providing `fs` and `process`.
+ * @param root   - Absolute path inside the sandbox under which to write.
+ * @param content - Markdown content for the instruction file.
+ */
+export async function writeAgentsFile(
+  handle: SandboxHandle,
+  root: string,
+  content: string,
+): Promise<void> {
+  const agentsPath = `${root}/AGENTS.md`
+  await handle.fs.write(agentsPath, content)
+
+  for (const name of SYMLINK_NAMES) {
+    const lnCmd = `ln -s '${sqEscape('AGENTS.md')}' '${sqEscape(name)}'`
+    const result = await handle.process.exec(lnCmd, { cwd: root })
+    if (result.exitCode !== 0) {
+      // Symlinks are not supported on this platform — fall back to a copy.
+      await handle.fs.write(`${root}/${name}`, content)
+    }
+  }
+}

package/src/approvals.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared interactive-approval logic for harness adapters.
+ *
+ * Flow (rides chat()'s existing resume-based approval mechanism):
+ *  1. The agent (inside the sandbox) asks to run a risky action; the harness's
+ *     host-side permission callback fires.
+ *  2. `resolveApproval` evaluates the sandbox policy: `allow`/`deny` are final;
+ *     `ask` consults the client's approval decisions (threaded via
+ *     `TextOptions.approvals`, keyed by a stable `approvalId`).
+ *  3. On `ask` with no decision yet, the adapter emits an `approval-requested`
+ *     CUSTOM event (carrying the `approvalId`) and denies the action this turn.
+ *     The client shows UI, then re-runs chat() with the decision in the message;
+ *     the engine surfaces it as `approvals`, and the next run allows it.
+ *
+ * `approvalId` is stable for a given (provider, kind, target) so a client grant
+ * matches the same action on the resumed run.
+ */
+import { EventType } from '@tanstack/ai'
+import { evaluateCommand } from './policy'
+import type { SandboxPolicy } from './policy'
+import type { StreamChunk } from '@tanstack/ai'
+
+/** CUSTOM event name emitted when a harness action needs client approval. */
+export const APPROVAL_REQUESTED_EVENT = 'approval-requested'
+
+/** A stable, opaque approval id for a harness action. */
+export function approvalId(input: {
+  provider: string
+  kind: 'command' | 'fileWrite' | 'network' | 'tool'
+  target: string
+}): string {
+  return `${input.provider}:${input.kind}:${input.target}`
+}
+
+export interface ResolveApprovalInput {
+  policy: SandboxPolicy | undefined
+  /** Client approval decisions, keyed by `approvalId`. */
+  approvals: ReadonlyMap<string, boolean> | undefined
+  /** Precomputed approval id for this action. */
+  id: string
+  /** A shell command to match against `policy.commands`. */
+  command?: string
+  /** Named workspace scripts for policy alias resolution. */
+  scripts?: Record<string, string>
+  /** A coarse capability to match against `policy.capabilities`. */
+  capability?: 'fileWrite' | 'network'
+}
+
+export interface ApprovalOutcome {
+  decision: 'allow' | 'deny'
+  /** True when policy said `ask` and the client hasn't decided yet. */
+  needsApproval: boolean
+}
+
+/** Resolve a harness permission request against policy + client approvals. */
+export function resolveApproval(input: ResolveApprovalInput): ApprovalOutcome {
+  const base =
+    input.command !== undefined
+      ? evaluateCommand(input.command, input.policy, input.scripts)
+      : input.capability !== undefined
+        ? (input.policy?.capabilities?.[input.capability] ??
+          input.policy?.default ??
+          'ask')
+        : (input.policy?.default ?? 'ask')
+
+  if (base === 'allow') return { decision: 'allow', needsApproval: false }
+  if (base === 'deny') return { decision: 'deny', needsApproval: false }
+
+  // base === 'ask' — consult the client's decision.
+  const granted = input.approvals?.get(input.id)
+  if (granted === true) return { decision: 'allow', needsApproval: false }
+  if (granted === false) return { decision: 'deny', needsApproval: false }
+  return { decision: 'deny', needsApproval: true }
+}
+
+/** Build the AG-UI `approval-requested` CUSTOM event for a harness action. */
+export function buildApprovalRequestedEvent(input: {
+  approvalId: string
+  title: string
+  threadId: string
+  runId: string
+  detail?: Record<string, unknown>
+}): StreamChunk {
+  return {
+    type: EventType.CUSTOM,
+    name: APPROVAL_REQUESTED_EVENT,
+    value: {
+      approvalId: input.approvalId,
+      title: input.title,
+      ...(input.detail ?? {}),
+    },
+    timestamp: Date.now(),
+    threadId: input.threadId,
+    runId: input.runId,
+  }
+}

package/src/bootstrap.ts

@@ -0,0 +1,196 @@
+/**
+ * Workspace bootstrap engine — provider-agnostic because it only uses the
+ * {@link SandboxHandle} contract. Runs once when a sandbox is freshly created
+ * (or restored without its working tree): land the source, inject secrets,
+ * detect the package manager, and run setup commands.
+ *
+ * Harness-specific projection (CLAUDE.md, agent skills, MCP config) is NOT done
+ * here — that's each adapter's `projectWorkspace()` hook, since the format
+ * differs per harness.
+ */
+import { buildSetupPlan } from './setup-plan'
+import { createBootstrapShell } from './shell'
+import {
+  mergeAgentsContent,
+  resolveGitSkillDir,
+  writeAgentsFile,
+} from './agents-file'
+import { resolveAllSecrets, resolveSecret } from './secrets'
+import type { SandboxHandle } from './contracts'
+import type { PackageManager, WorkspaceDefinition } from './workspace'
+
+const LOCKFILES: Record<Exclude<PackageManager, 'auto'>, string> = {
+  pnpm: 'pnpm-lock.yaml',
+  yarn: 'yarn.lock',
+  bun: 'bun.lockb',
+  npm: 'package-lock.json',
+}
+
+export const DEFAULT_WORKSPACE_ROOT = '/workspace'
+
+/** Resolve the package manager, detecting from a lockfile when `'auto'`. */
+export async function detectPackageManager(
+  handle: SandboxHandle,
+  workspace: WorkspaceDefinition,
+  root: string,
+): Promise<Exclude<PackageManager, 'auto'> | undefined> {
+  const pm = workspace.packageManager ?? 'auto'
+  if (pm !== 'auto') return pm
+  for (const [manager, lockfile] of Object.entries(LOCKFILES) as Array<
+    [Exclude<PackageManager, 'auto'>, string]
+  >) {
+    if (await handle.fs.exists(`${root}/${lockfile}`)) return manager
+  }
+  return undefined
+}
+
+export interface BootstrapResult {
+  packageManager?: Exclude<PackageManager, 'auto'>
+  ranSetup: Array<string>
+}
+
+/**
+ * Bootstrap a freshly created sandbox's workspace. Idempotent enough to be safe
+ * on restore: a git clone into a populated dir is skipped by checking for the
+ * target dir first.
+ */
+export async function bootstrapWorkspace(
+  handle: SandboxHandle,
+  workspace: WorkspaceDefinition,
+  options: { signal?: AbortSignal } = {},
+): Promise<BootstrapResult> {
+  const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT
+
+  // Secrets live only in the running sandbox env (never persisted).
+  if (workspace.secrets !== undefined) {
+    const resolved = resolveAllSecrets(workspace.secrets)
+    if (Object.keys(resolved).length > 0) {
+      await handle.env.set(resolved)
+    }
+  }
+
+  // Land the source. Clone into the handle's own default root (each provider
+  // maps the conventional `/workspace` virtual root to its real backing dir),
+  // rather than passing a virtual `dir` that can't be remapped inside a shell
+  // command string.
+  if (workspace.source.type === 'git') {
+    const alreadyCloned = await handle.fs.exists(`${root}/.git`)
+    if (!alreadyCloned) {
+      await handle.git.clone({
+        url: workspace.source.url,
+        ref: workspace.source.ref,
+        auth: workspace.source.auth,
+        ...(workspace.source.depth !== undefined
+          ? { depth: workspace.source.depth }
+          : {}),
+      })
+    }
+  }
+  // 'local' is provider-pre-populated at create; 'none' starts empty.
+
+  // Clone git-skill repos so setup steps (and the harness projector) can use
+  // them. gitSkill clones are always shallow (depth 1) unless the skill's own
+  // repo entry carries a depth override — the WorkspaceSkill `git` variant
+  // does not expose one, so depth always defaults to 1 inside git.clone.
+  const skills = workspace.skills ?? []
+  for (const skill of skills) {
+    if (skill.kind === 'git') {
+      const url = skill.repo.startsWith('http')
+        ? skill.repo
+        : `https://github.com/${skill.repo}.git`
+      const dir = skill.into ?? resolveGitSkillDir(root, skill)
+      const auth =
+        skill.secret !== undefined && workspace.secrets !== undefined
+          ? { token: resolveSecret(workspace.secrets, skill.secret) }
+          : undefined
+      await handle.git.clone({
+        url,
+        dir,
+        ...(auth !== undefined ? { auth } : {}),
+        depth: 1,
+      })
+    }
+  }
+
+  // Write AGENTS.md (and its per-CLI symlinks) when instructions are provided
+  // directly on the workspace, via a fileSkill whose path is `AGENTS.md`, or
+  // when named workspace scripts should be surfaced for the agent.
+  let agentsContent: string | undefined
+  if (
+    workspace.instructions !== undefined &&
+    workspace.instructions.length > 0
+  ) {
+    agentsContent = workspace.instructions
+  } else {
+    const agentsFileSkill = skills.find(
+      (s): s is Extract<typeof s, { kind: 'file' }> =>
+        s.kind === 'file' && s.path === 'AGENTS.md',
+    )
+    if (agentsFileSkill !== undefined) {
+      agentsContent = agentsFileSkill.content
+    }
+  }
+  agentsContent = mergeAgentsContent(agentsContent, workspace.scripts)
+  if (agentsContent !== undefined) {
+    await writeAgentsFile(handle, root, agentsContent)
+  }
+
+  // Write all other fileSkills directly into the workspace root.
+  for (const skill of skills) {
+    if (skill.kind === 'file' && skill.path !== 'AGENTS.md') {
+      await handle.fs.write(`${root}/${skill.path}`, skill.content)
+    }
+  }
+
+  const packageManager = await detectPackageManager(handle, workspace, root)
+
+  // Run setup over a single persistent shell so `cd`/exports persist across
+  // serial steps. Parallel groups fork the shell's current cwd+env into
+  // concurrent one-shot exec calls.
+  const ranSetup: Array<string> = []
+  const plan = buildSetupPlan(workspace.setup)
+  if (plan.length > 0) {
+    const shell = await createBootstrapShell(handle, { cwd: root })
+    try {
+      for (const group of plan) {
+        if (group.kind === 'serial') {
+          const result = await shell.run(group.command)
+          if (result.exitCode !== 0) {
+            const tail = result.stdout.trim().slice(-1500)
+            throw new Error(
+              `setup step failed: ${group.command} (exit ${result.exitCode})${tail ? `\n${tail}` : ''}`,
+            )
+          }
+          ranSetup.push(group.command)
+        } else {
+          const { cwd, env } = await shell.forkState()
+          const results = await Promise.all(
+            group.commands.map((command) =>
+              handle.process
+                .exec(command, {
+                  cwd,
+                  env,
+                  ...(options.signal ? { signal: options.signal } : {}),
+                })
+                .then((res) => ({ command, res })),
+            ),
+          )
+          const failed = results.find((entry) => entry.res.exitCode !== 0)
+          if (failed !== undefined) {
+            const tail = `${failed.res.stdout}\n${failed.res.stderr}`
+              .trim()
+              .slice(-1500)
+            throw new Error(
+              `setup step failed: ${failed.command} (exit ${failed.res.exitCode})${tail ? `\n${tail}` : ''}`,
+            )
+          }
+          ranSetup.push(...group.commands)
+        }
+      }
+    } finally {
+      await shell.dispose()
+    }
+  }
+
+  return { packageManager, ranSetup }
+}

package/src/bridge-events.ts

@@ -0,0 +1,112 @@
+/**
+ * Helpers that let a harness adapter surface custom events emitted by BRIDGED
+ * tools (via {@link ToolBridgeCoreOptions.emitCustomEvent}) on its live output
+ * stream.
+ *
+ * The bridge runs out-of-band from the harness's own event stream, so a bridged
+ * tool's progress/console events have no path to the client on their own. An
+ * adapter creates a {@link BridgeEventChannel}, hands its `emitCustomEvent` to
+ * the bridge provisioner, and {@link mergeChunkStreams | merges} the channel's
+ * stream into its translated output — so events interleave live while the agent
+ * runs (e.g. code mode's `code_mode:console` logs during a long execution).
+ */
+import { EventType } from '@tanstack/ai'
+import type { StreamChunk } from '@tanstack/ai'
+
+export interface BridgeEventChannel {
+  /** Pass as the bridge's `emitCustomEvent`; buffers a CUSTOM chunk for the stream. */
+  emitCustomEvent: (eventName: string, value: Record<string, unknown>) => void
+  /** Live CUSTOM-chunk stream; ends after {@link close} once drained. */
+  stream: AsyncIterable<StreamChunk>
+  /** Stop the stream (call when the run's main output is done). */
+  close: () => void
+}
+
+/** Create a channel whose emitted events become CUSTOM {@link StreamChunk}s. */
+export function createBridgeEventChannel(meta: {
+  model: string
+  threadId?: string
+  runId?: string
+}): BridgeEventChannel {
+  const buffer: Array<StreamChunk> = []
+  let notify: (() => void) | null = null
+  let closed = false
+
+  async function* stream(): AsyncIterable<StreamChunk> {
+    for (;;) {
+      const next = buffer.shift()
+      if (next !== undefined) {
+        yield next
+        continue
+      }
+      if (closed) return
+      await new Promise<void>((resolve) => {
+        notify = resolve
+      })
+      notify = null
+    }
+  }
+
+  return {
+    emitCustomEvent(eventName, value) {
+      if (closed) return
+      buffer.push({
+        type: EventType.CUSTOM,
+        name: eventName,
+        value,
+        timestamp: Date.now(),
+        model: meta.model,
+        ...(meta.threadId !== undefined && { threadId: meta.threadId }),
+        ...(meta.runId !== undefined && { runId: meta.runId }),
+      })
+      notify?.()
+    },
+    close() {
+      closed = true
+      notify?.()
+    },
+    stream: stream(),
+  }
+}
+
+/**
+ * Merge a `side` chunk stream into a `base` chunk stream, yielding from whichever
+ * settles first. Terminates when `base` ends (the run is over), then releases the
+ * side iterator — so a never-ending channel (until closed) doesn't hang the merge.
+ */
+export async function* mergeChunkStreams(
+  base: AsyncIterable<StreamChunk>,
+  side: AsyncIterable<StreamChunk>,
+): AsyncIterable<StreamChunk> {
+  const baseIt = base[Symbol.asyncIterator]()
+  const sideIt = side[Symbol.asyncIterator]()
+  let baseNext = baseIt.next().then((r) => ({ from: 'base' as const, r }))
+  let sideNext = sideIt.next().then((r) => ({ from: 'side' as const, r }))
+  let sideLive = true
+  try {
+    for (;;) {
+      const winner = await Promise.race(
+        sideLive ? [baseNext, sideNext] : [baseNext],
+      )
+      if (winner.from === 'base') {
+        if (winner.r.done) return
+        yield winner.r.value
+        baseNext = baseIt.next().then((r) => ({ from: 'base' as const, r }))
+      } else if (winner.r.done) {
+        sideLive = false
+      } else {
+        yield winner.r.value
+        sideNext = sideIt.next().then((r) => ({ from: 'side' as const, r }))
+      }
+    }
+  } finally {
+    // Fire-and-forget: do NOT await the side return. The channel generator is
+    // suspended on a promise that only `close()` resolves, and `close()` runs in
+    // the adapter's `finally` AFTER this merge completes — awaiting here would
+    // deadlock. The adapter's `close()` lets the generator unwind afterwards.
+    const baseReturn = baseIt.return?.(undefined)
+    if (baseReturn) void baseReturn.catch(() => {})
+    const sideReturn = sideIt.return?.(undefined)
+    if (sideReturn) void sideReturn.catch(() => {})
+  }
+}

package/src/capabilities.ts

@@ -0,0 +1,47 @@
+/**
+ * Capability tokens the sandbox layer provides/consumes through the
+ * `@tanstack/ai` middleware capability system.
+ *
+ * - `SandboxCapability` is PROVIDED by `withSandbox` and REQUIRED by harness
+ *   adapters (`requires: [SandboxCapability]`).
+ * - `SandboxStoreCapability` / `LocksCapability` are OPTIONALLY required by
+ *   `withSandbox`. v1 falls back to in-memory defaults; the future persistence
+ *   package PROVIDES durable implementations.
+ */
+import { createCapability } from '@tanstack/ai'
+import type { SandboxHandle } from './contracts'
+import type { LockStore, SandboxStore } from './store'
+import type { SandboxPolicy } from './policy'
+import type { ToolBridgeProvisioner } from './tool-bridge'
+
+export const SandboxCapability = createCapability<SandboxHandle>()('sandbox')
+
+export const SandboxStoreCapability =
+  createCapability<SandboxStore>()('sandbox-store')
+
+export const LocksCapability = createCapability<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 const SandboxPolicyCapability =
+  createCapability<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 const ToolBridgeProvisionerCapability =
+  createCapability<ToolBridgeProvisioner>()('tool-bridge-provisioner')
+
+/** Destructured accessors for adapters: `getSandbox(ctx)` reads the handle. */
+export const [getSandbox, provideSandbox] = SandboxCapability
+export const [getSandboxStore, provideSandboxStore] = SandboxStoreCapability
+export const [getLocks, provideLocks] = LocksCapability
+export const [getSandboxPolicy, provideSandboxPolicy] = SandboxPolicyCapability
+export const [getToolBridgeProvisioner, provideToolBridgeProvisioner] =
+  ToolBridgeProvisionerCapability