@tanstack/ai-sandbox 0.1.0

package/src/key.ts

@@ -0,0 +1,70 @@
+/**
+ * Compound sandbox identity. We never key a resumable sandbox on `threadId`
+ * alone — that would resume the WRONG environment when the provider,
+ * workspace, image, or tenant changes. The key folds all of those in, so any
+ * change busts the sandbox and forces a fresh create+bootstrap (safe default).
+ */
+import type { WorkspaceDefinition } from './workspace'
+
+/** 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 }
+}
+
+/** Deterministic, dependency-free 64-bit FNV-1a hash → hex string. */
+function fnv1a(input: string): string {
+  // Two 32-bit lanes to approximate 64-bit without BigInt overhead concerns.
+  let h1 = 0x811c9dc5
+  let h2 = 0x811c9dc5
+  for (let i = 0; i < input.length; i++) {
+    const c = input.charCodeAt(i)
+    h1 ^= c & 0xff
+    h1 = Math.imul(h1, 0x01000193)
+    h2 ^= (c >> 8) & 0xff
+    h2 = Math.imul(h2, 0x01000193)
+  }
+  const hex = (n: number): string => (n >>> 0).toString(16).padStart(8, '0')
+  return hex(h1) + hex(h2)
+}
+
+/** Canonical, key-sorted JSON so logically-equal inputs hash identically. */
+function canonical(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value)
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`
+  const keys = Object.keys(value).sort()
+  return `{${keys
+    .map(
+      (k) =>
+        `${JSON.stringify(k)}:${canonical((value as Record<string, unknown>)[k])}`,
+    )
+    .join(',')}}`
+}
+
+/**
+ * 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 function computeWorkspaceHash(
+  workspace: WorkspaceDefinition | undefined,
+): string {
+  if (!workspace) return fnv1a('no-workspace')
+  const { secrets: _secrets, ...rest } = workspace
+  return fnv1a(canonical(rest))
+}
+
+/** Compute the compound sandbox instance key. */
+export function computeSandboxKey(input: SandboxKeyInput): string {
+  const material = canonical({
+    threadId: input.threadId,
+    sandboxId: input.sandboxId,
+    providerName: input.providerName,
+    workspaceHash: computeWorkspaceHash(input.workspace),
+    tenant: input.tenant ?? null,
+  })
+  return fnv1a(material)
+}

package/src/middleware.ts

@@ -0,0 +1,233 @@
+/**
+ * `withSandbox(definition)` — the middleware that PROVIDES the
+ * {@link SandboxCapability} a harness adapter requires.
+ *
+ * - `setup`: resume-or-create the sandbox (via the definition's ensure
+ *   algorithm), provide the handle, using the optional SandboxStore/Locks
+ *   capabilities when a persistence middleware supplied them (in-memory
+ *   fallback otherwise). If `fileEvents` is not false, starts a watcher
+ *   that dispatches to sandbox-scoped hooks and forwards to the runtime sink.
+ * - `onFinish`/`onAbort`/`onError`: stop the watcher, snapshot (`after-run`)
+ *   and/or destroy per lifecycle.
+ *
+ * NOTE: streamed sandbox lifecycle events (sandbox.created, workspace.setup.*)
+ * are emitted by the harness adapter's chatStream (which can yield CUSTOM
+ * chunks), not from here — middleware setup runs before streaming begins.
+ */
+import { defineChatMiddleware } from '@tanstack/ai'
+import { getSandboxRuntime } from '@tanstack/ai/adapter-internals'
+import {
+  LocksCapability,
+  SandboxCapability,
+  SandboxStoreCapability,
+  provideSandbox,
+  provideSandboxPolicy,
+} from './capabilities'
+import { computeWorkspaceHash } from './key'
+import { ProjectionCapability, provideWorkspaceProjection } from './projection'
+import { resolveSecret } from './secrets'
+import { watchWorkspace } from './watch'
+import { DEFAULT_WORKSPACE_ROOT } from './bootstrap'
+import type {
+  AbortInfo,
+  ChatMiddlewareContext,
+  DefinedChatMiddleware,
+  SandboxFileEvent,
+} from '@tanstack/ai'
+import type { SandboxHandle } from './contracts'
+import type {
+  SandboxDefinition,
+  SandboxEnsureContext,
+  SandboxHooks,
+} from './sandbox'
+import type { SandboxWatchHandle } from './watch'
+
+/** Per-request state we need to carry from `setup` to the terminal hooks. */
+interface SandboxRunState {
+  handle: SandboxHandle
+  ensureCtx: SandboxEnsureContext
+  watcher?: SandboxWatchHandle
+}
+
+const runState = new WeakMap<object, SandboxRunState>()
+
+/** Defensively pull tenant scoping out of the runtime context, if present. */
+function tenantFrom(
+  context: unknown,
+): { userId?: string; orgId?: string } | undefined {
+  if (context === null || typeof context !== 'object') return undefined
+  const c = context as Record<string, unknown>
+  const userId = typeof c.userId === 'string' ? c.userId : undefined
+  const orgId = typeof c.orgId === 'string' ? c.orgId : undefined
+  if (userId === undefined && orgId === undefined) return undefined
+  return { userId, orgId }
+}
+
+function buildEnsureCtx(ctx: ChatMiddlewareContext): SandboxEnsureContext {
+  return {
+    threadId: ctx.threadId,
+    runId: ctx.runId,
+    store: ctx.getOptional(SandboxStoreCapability),
+    locks: ctx.getOptional(LocksCapability),
+    tenant: tenantFrom(ctx.context),
+    signal: ctx.signal,
+  }
+}
+
+/**
+ * Dispatch a sandbox file event to the per-type hooks declared on the
+ * definition. Errors in individual hooks are swallowed so one bad hook
+ * cannot break the run.
+ */
+async function dispatchDefinitionHooks(
+  hooks: SandboxHooks | undefined,
+  event: SandboxFileEvent,
+): Promise<void> {
+  if (!hooks) return
+  const typed = (
+    {
+      create: 'onFileCreate',
+      change: 'onFileChange',
+      delete: 'onFileDelete',
+    } as const
+  )[event.type]
+  for (const fn of [hooks.onFile, hooks[typed]]) {
+    if (!fn) continue
+    try {
+      await fn(event)
+    } catch {
+      // swallowed — one bad hook must not break the run
+    }
+  }
+}
+
+export function withSandbox(
+  definition: SandboxDefinition,
+): DefinedChatMiddleware<
+  unknown,
+  readonly [],
+  readonly [typeof SandboxCapability, typeof ProjectionCapability]
+> {
+  return defineChatMiddleware({
+    name: 'sandbox',
+    provides: [SandboxCapability, ProjectionCapability],
+    // SandboxPolicyCapability is provided conditionally (only when the
+    // definition has a policy), so it is intentionally NOT declared here —
+    // consumers read it via `getOptional`.
+    optionalRequires: [SandboxStoreCapability, LocksCapability],
+
+    async setup(ctx) {
+      const ensureCtx = buildEnsureCtx(ctx)
+      const handle = await definition.ensure(ensureCtx)
+      provideSandbox(ctx, handle)
+      if (definition.policy) provideSandboxPolicy(ctx, definition.policy)
+
+      const workspace = definition.workspace
+      if (workspace !== undefined) {
+        const root = workspace.root ?? DEFAULT_WORKSPACE_ROOT
+        const workspaceHash = computeWorkspaceHash(workspace)
+        const secrets = workspace.secrets
+        provideWorkspaceProjection(ctx, {
+          skills: workspace.skills ?? [],
+          plugins: workspace.plugins ?? [],
+          resolveSecret: (ref) => {
+            if (secrets === undefined) {
+              throw new Error(
+                `resolveSecret: no secrets defined on this workspace (ref: "${ref.__secretName}")`,
+              )
+            }
+            return resolveSecret(secrets, ref)
+          },
+          markerPath: `${root}/.tanstack-projected-${workspaceHash}`,
+          root,
+          ...(workspace.scripts !== undefined
+            ? { scripts: workspace.scripts }
+            : {}),
+        })
+      }
+
+      const hooks = definition.hooks
+      await hooks?.onReady?.(handle)
+
+      let watcher: SandboxWatchHandle | undefined
+      if (definition.fileEvents !== false) {
+        const runtime = getSandboxRuntime(ctx, { optional: true })
+        watcher = await watchWorkspace(handle, {
+          onEvent: (event: SandboxFileEvent) => {
+            void dispatchDefinitionHooks(hooks, event)
+            runtime?.emit(event)
+          },
+          ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
+        })
+      }
+
+      runState.set(ctx, { handle, ensureCtx, ...(watcher ? { watcher } : {}) })
+    },
+
+    async onFinish(ctx) {
+      const state = runState.get(ctx)
+      if (!state) return
+      const { handle, ensureCtx } = state
+
+      await state.watcher?.stop()
+
+      const lifecycle = definition.lifecycle
+
+      if (
+        lifecycle?.snapshot === 'after-run' &&
+        handle.capabilities.snapshots &&
+        handle.snapshot
+      ) {
+        const snapshot = await handle.snapshot(`after-run-${ctx.runId}`)
+        const store = ensureCtx.store
+        if (store) {
+          const key = definition.key(ensureCtx)
+          const existing = await store.get(key)
+          if (existing) {
+            await store.upsert({
+              ...existing,
+              latestSnapshotId: snapshot.id,
+              updatedAt: Date.now(),
+            })
+          }
+        }
+      }
+
+      if (lifecycle?.destroyOnComplete) {
+        await definition.destroy(ensureCtx)
+        await definition.hooks?.onDestroy?.()
+      }
+    },
+
+    async onAbort(ctx, _info: AbortInfo) {
+      const state = runState.get(ctx)
+      if (!state) return
+
+      await state.watcher?.stop()
+
+      // ALWAYS tear down on an explicit abort, regardless of `destroyOnComplete`.
+      // The in-sandbox agent process is not killed by closing its IO stream
+      // (e.g. a Docker exec survives client disconnect), so the only reliable way
+      // to stop it — and the token/cost drain of its ongoing API calls — is to
+      // destroy the sandbox (stop the container/VM). `keepAlive` /
+      // `destroyOnComplete:false` governs *successful completion*, never cancel.
+      await definition.destroy(state.ensureCtx)
+      await definition.hooks?.onDestroy?.()
+    },
+
+    async onError(ctx, info) {
+      const state = runState.get(ctx)
+      if (!state) return
+
+      await state.watcher?.stop()
+      await definition.hooks?.onError?.(info.error)
+
+      // On failure, only tear down when the lifecycle says so; otherwise leave
+      // the sandbox for a resumed retry.
+      if (definition.lifecycle?.destroyOnComplete) {
+        await definition.destroy(state.ensureCtx)
+        await definition.hooks?.onDestroy?.()
+      }
+    },
+  })
+}

package/src/ngrok.ts

@@ -0,0 +1,85 @@
+/**
+ * ngrok-backed tool-bridge provisioner — make the host tool bridge reachable
+ * from REMOTE sandboxes (Daytona, Vercel, …) while developing locally.
+ *
+ * The default bridge ({@link nodeHttpBridgeProvisioner}) binds `localhost`, so
+ * only same-machine providers (local-process, Docker) can reach it. A cloud
+ * sandbox is a remote VM and can't dial your machine's loopback. This
+ * provisioner stands up the normal loopback bridge, opens an ngrok tunnel to its
+ * port, and advertises the public `https://…/mcp` URL (with the same per-run
+ * bearer token) to the sandbox — so bridged tools / code mode work there too.
+ *
+ * In PRODUCTION you don't need this: a deployed orchestrator already has a public
+ * URL, so a provisioner can advertise that directly (derived from the request).
+ * ngrok is the local-dev stand-in for "the orchestrator is reachable".
+ *
+ * `@ngrok/ngrok` is an OPTIONAL peer dependency — it's loaded lazily, so this
+ * subpath imports cleanly without it; only {@link withNgrokBridge} /
+ * {@link ngrokBridgeProvisioner} require it at run time. Set `NGROK_AUTHTOKEN`.
+ */
+import { defineChatMiddleware } from '@tanstack/ai'
+import { provideToolBridgeProvisioner } from './capabilities'
+import { startHostToolBridge } from './tool-bridge'
+import type { ToolBridgeProvisioner } from './tool-bridge'
+
+/** Whether ngrok tunnelling is configured (an authtoken is present). */
+export function ngrokConfigured(): boolean {
+  return Boolean(process.env.NGROK_AUTHTOKEN)
+}
+
+/**
+ * A {@link ToolBridgeProvisioner} that tunnels the loopback bridge through ngrok
+ * (one ephemeral tunnel per run; both are torn down together). Requires the
+ * optional `@ngrok/ngrok` peer dependency and `NGROK_AUTHTOKEN`.
+ */
+export const ngrokBridgeProvisioner: ToolBridgeProvisioner = {
+  async provision(tools, options) {
+    // Lazy + optional: only needed when this provisioner actually runs.
+    const { default: ngrok } = await import('@ngrok/ngrok')
+    const { provider: _provider, ...core } = options
+    const bridge = await startHostToolBridge(tools, {
+      hostForSandbox: '127.0.0.1',
+      bindAddress: '127.0.0.1',
+      ...core,
+    })
+    try {
+      const port = Number(new URL(bridge.url).port)
+      const listener = await ngrok.forward({
+        addr: port,
+        authtoken_from_env: true,
+      })
+      const publicUrl = listener.url()
+      if (!publicUrl) {
+        throw new Error('ngrok did not return a public URL')
+      }
+      return {
+        ...bridge,
+        url: `${publicUrl}/mcp`,
+        close: async () => {
+          try {
+            await listener.close()
+          } finally {
+            await bridge.close()
+          }
+        },
+      }
+    } catch (error) {
+      // Don't leak the loopback bridge if the tunnel couldn't be opened.
+      await bridge.close()
+      throw error
+    }
+  },
+}
+
+/**
+ * Chat middleware that routes the tool bridge through ngrok. Add it AFTER
+ * `withSandbox(...)` for cloud providers so the in-sandbox harness can reach the
+ * host tools. Not needed for local-process / Docker (they reach the bridge
+ * directly) — just don't add it there.
+ */
+export const withNgrokBridge = defineChatMiddleware({
+  name: 'ngrok-bridge',
+  setup(ctx) {
+    provideToolBridgeProvisioner(ctx, ngrokBridgeProvisioner)
+  },
+})

package/src/policy.ts

@@ -0,0 +1,111 @@
+/**
+ * Sandbox policy — a portable, harness-agnostic description of what the agent
+ * may do. Each harness adapter MAPS this onto its native permission system
+ * (Claude Code → canUseTool + allowedTools/disallowedTools/permissionMode).
+ *
+ * Command rules are matched as glob/prefix patterns against the command line.
+ * Precedence is deny > ask > allow; unmatched commands fall to `default`.
+ * `'ask'` surfaces the existing resume-based `approval-requested` flow.
+ */
+
+export type PolicyDecision = 'allow' | 'ask' | 'deny'
+
+export interface CommandRules {
+  /** Glob/prefix patterns to allow outright (e.g. 'pnpm *', 'git diff'). */
+  allow?: Array<string>
+  /** Patterns that require approval before running. */
+  ask?: Array<string>
+  /** Patterns to refuse (e.g. 'sudo *', 'rm -rf *'). */
+  deny?: Array<string>
+}
+
+/** Coarse, non-command capability gates for tools like Write/Edit and network. */
+export interface CapabilityRules {
+  /** File-modifying tools (Write/Edit). Defaults to the policy `default`. */
+  fileWrite?: PolicyDecision
+  /** Outbound network access. Defaults to the policy `default`. */
+  network?: PolicyDecision
+}
+
+export interface SandboxPolicy {
+  commands?: CommandRules
+  capabilities?: CapabilityRules
+  /** Decision for anything not matched by a rule. Defaults to `'ask'`. */
+  default?: PolicyDecision
+}
+
+export function defineSandboxPolicy(policy: SandboxPolicy): SandboxPolicy {
+  return policy
+}
+
+/** Convert a glob/prefix pattern to a RegExp anchored to the full command. */
+function patternToRegExp(pattern: string): RegExp {
+  // Escape regex metacharacters except '*', then turn '*' into '.*'.
+  const escaped = pattern
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '.*')
+  return new RegExp(`^${escaped}$`)
+}
+
+/**
+ * All equivalent forms of a command line when workspace scripts are defined:
+ * the literal command, its expanded script value, and any script name that
+ * expands to the same value.
+ */
+export function commandAliases(
+  command: string,
+  scripts: Record<string, string> | undefined,
+): Array<string> {
+  const trimmed = command.trim()
+  const aliases = new Set<string>([trimmed])
+  if (scripts === undefined) return [...aliases]
+
+  const expanded = scripts[trimmed]
+  if (expanded !== undefined) aliases.add(expanded)
+
+  for (const [name, value] of Object.entries(scripts)) {
+    if (value === trimmed) aliases.add(name)
+  }
+  return [...aliases]
+}
+
+function patternMatchesCommand(
+  pattern: string,
+  command: string,
+  scripts: Record<string, string> | undefined,
+): boolean {
+  const commandForms = commandAliases(command, scripts)
+  for (const patternForm of commandAliases(pattern, scripts)) {
+    const re = patternToRegExp(patternForm)
+    if (commandForms.some((form) => re.test(form))) return true
+  }
+  return false
+}
+
+/**
+ * Resolve a command line against the policy. Precedence: deny > ask > allow,
+ * then `default` (defaults to `'ask'`). Exported for adapter permission
+ * mappers and unit tests.
+ *
+ * When `scripts` is provided, policy patterns may match either a script name
+ * or its expanded command value (and vice versa for the command under test).
+ */
+export function evaluateCommand(
+  command: string,
+  policy: SandboxPolicy | undefined,
+  scripts?: Record<string, string>,
+): PolicyDecision {
+  const fallback = policy?.default ?? 'ask'
+  const rules = policy?.commands
+  if (!rules) return fallback
+
+  const matches = (patterns: Array<string> | undefined): boolean =>
+    (patterns ?? []).some((pattern) =>
+      patternMatchesCommand(pattern, command, scripts),
+    )
+
+  if (matches(rules.deny)) return 'deny'
+  if (matches(rules.ask)) return 'ask'
+  if (matches(rules.allow)) return 'allow'
+  return fallback
+}

package/src/projection.ts

@@ -0,0 +1,46 @@
+/**
+ * Workspace projection capability — provided by `withSandbox` and consumed by
+ * harness adapters (claude-code, codex, opencode) to idempotently
+ * project skills, plugins, and resolved secrets into the native harness format.
+ *
+ * The capability carries the raw provisioning inputs (skills, plugins, a
+ * resolve function for secret refs) together with a marker path that lets
+ * adapters guard the projection with a one-time idempotency file.
+ */
+import { createCapability } from '@tanstack/ai'
+import type { SecretRef } from './secrets'
+import type { WorkspaceSkill } from './workspace'
+
+/**
+ * The shape provided to harness adapters via the sandbox projection capability.
+ * Harness adapters read this in their `chatStream` setup to project workspace
+ * inputs into their native format (MCP config, skills dirs, plugin installs).
+ */
+export interface WorkspaceProjection {
+  /** Skills declared on the workspace — MCP servers, file skills, git repos, etc. */
+  skills: Array<WorkspaceSkill>
+  /** Harness plugin identifiers to install idempotently. */
+  plugins: Array<string>
+  /**
+   * Resolve a SecretRef to its plaintext value. Bound to the workspace's
+   * secrets registry; throws when the ref is unknown.
+   */
+  resolveSecret: (ref: SecretRef) => string
+  /**
+   * Absolute path to the idempotency marker file. Harness adapters write this
+   * file after a successful projection so subsequent runs skip re-projection.
+   * The file is NOT included in snapshots — absent on restore, triggering
+   * re-projection (which re-writes any secret-bearing config files).
+   */
+  markerPath: string
+  /** Workspace root inside the sandbox (e.g. `/workspace`). */
+  root: string
+  /** Named commands declared on the workspace (e.g. `{ test: 'pnpm test' }`). */
+  scripts?: Record<string, string>
+}
+
+export const ProjectionCapability =
+  createCapability<WorkspaceProjection>()('sandbox-projection')
+
+export const [getWorkspaceProjection, provideWorkspaceProjection] =
+  ProjectionCapability