@tanstack/ai-sandbox 0.1.0

package/dist/esm/workspace.d.ts

@@ -0,0 +1,128 @@
+import { SetupInput } from './setup-plan.js';
+import { BearerRef, SecretRef, Secrets } from './secrets.js';
+/**
+ * Workspace definition — the portable description of what the agent sees
+ * inside the sandbox. Each harness adapter PROJECTS this into its own native
+ * format via `projectWorkspace()` (e.g. Claude Code → CLAUDE.md + .claude/skills
+ * + --mcp-config). The definition itself is provider- and harness-agnostic.
+ */
+/** Where the working tree comes from. */
+export type WorkspaceSource = {
+    type: 'git';
+    url: string;
+    ref?: string;
+    auth?: {
+        username?: string;
+        token: string;
+    };
+    /**
+     * Clone depth. Defaults to `1` (shallow). Pass a number for a specific
+     * depth, or `'full'` to fetch the entire history.
+     */
+    depth?: number | 'full';
+} | {
+    type: 'local';
+    path: string;
+} | {
+    type: 'none';
+};
+/** Clone a git repo into the workspace. `githubRepo` is a convenience wrapper. */
+export declare function gitSource(input: {
+    url: string;
+    ref?: string;
+    auth?: {
+        username?: string;
+        token: string;
+    };
+    depth?: number | 'full';
+}): WorkspaceSource;
+export declare function githubRepo(input: {
+    repo: string;
+    ref?: string;
+    auth?: {
+        username?: string;
+        token: string;
+    };
+    depth?: number | 'full';
+}): WorkspaceSource;
+export declare function localSource(path: string): WorkspaceSource;
+/**
+ * An MCP server config where header names/values may be plain strings or
+ * unresolved SecretRef values. Secrets are resolved by each harness projector
+ * at projection time — never at definition time.
+ */
+export type McpConfig = {
+    headers?: Record<string, string | SecretRef | BearerRef>;
+    [key: string]: unknown;
+};
+/** A unit of agent guidance/config projected into the harness's native format. */
+export type WorkspaceSkill = {
+    kind: 'file';
+    path: string;
+    content: string;
+} | {
+    kind: 'agent-skill';
+    name: string;
+} | {
+    kind: 'mcp';
+    name: string;
+    config: McpConfig;
+} | {
+    kind: 'git';
+    /** Short `owner/repo` or a full HTTPS URL. */
+    repo: string;
+    /** Optional SecretRef for private-repo authentication. */
+    secret?: SecretRef;
+    /** Absolute path inside the sandbox to clone into. Defaults to a `.tanstack-skills/<repo>` dir under the workspace root. */
+    into?: string;
+};
+/** Write a file (e.g. CLAUDE.md) into the workspace / harness config. */
+export declare function fileSkill(input: {
+    path: string;
+    content: string;
+}): WorkspaceSkill;
+/** Reference a named agent skill the harness should load. */
+export declare function agentSkill(name: string): WorkspaceSkill;
+/** Project an MCP server into the harness. Header values may be SecretRefs. */
+export declare function mcpSkill(name: string, config: McpConfig): WorkspaceSkill;
+/**
+ * Clone a git repository as a workspace skill (e.g. a private skill repo).
+ * The clone is performed during bootstrap; `secret` is resolved from the
+ * workspace `secrets` registry at that time.
+ */
+export declare function gitSkill(input: {
+    repo: string;
+    secret?: SecretRef;
+    into?: string;
+}): WorkspaceSkill;
+export type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'auto';
+export interface WorkspaceDefinition {
+    source: WorkspaceSource;
+    /** Defaults to `'auto'` — detect from the lockfile after the source lands. */
+    packageManager?: PackageManager;
+    /** Commands run once during bootstrap. Accepts a string array (serial) or a builder function for serial/parallel groups. */
+    setup?: SetupInput;
+    /** Named commands the agent/user can invoke (e.g. { test: 'pnpm test' }). */
+    scripts?: Record<string, string>;
+    /** Guidance/config projected into the harness. */
+    skills?: Array<WorkspaceSkill>;
+    /**
+     * Natural-language instructions written to AGENTS.md (and symlinked as
+     * CLAUDE.md, GEMINI.md, etc.) inside the sandbox during bootstrap.
+     */
+    instructions?: string;
+    /**
+     * Harness plugin identifiers installed idempotently by each harness
+     * projector (e.g. `['@anthropic/plugin-foo']` for Claude Code).
+     */
+    plugins?: Array<string>;
+    /**
+     * Typed secret references. The underlying values are injected into the
+     * sandbox env at create/resume — NEVER written to snapshots, the
+     * SandboxStore, or the event log.
+     */
+    secrets?: Secrets;
+    /** Workspace root inside the sandbox. Defaults to `/workspace`. */
+    root?: string;
+}
+export declare function defineWorkspace(definition: WorkspaceDefinition): WorkspaceDefinition;

package/dist/esm/workspace.js

@@ -0,0 +1,42 @@
+function gitSource(input) {
+  return { type: "git", ...input };
+}
+function githubRepo(input) {
+  const url = input.repo.startsWith("http") ? input.repo : `https://github.com/${input.repo}.git`;
+  return {
+    type: "git",
+    url,
+    ref: input.ref,
+    auth: input.auth,
+    depth: input.depth
+  };
+}
+function localSource(path) {
+  return { type: "local", path };
+}
+function fileSkill(input) {
+  return { kind: "file", ...input };
+}
+function agentSkill(name) {
+  return { kind: "agent-skill", name };
+}
+function mcpSkill(name, config) {
+  return { kind: "mcp", name, config };
+}
+function gitSkill(input) {
+  return { kind: "git", ...input };
+}
+function defineWorkspace(definition) {
+  return definition;
+}
+export {
+  agentSkill,
+  defineWorkspace,
+  fileSkill,
+  gitSkill,
+  gitSource,
+  githubRepo,
+  localSource,
+  mcpSkill
+};
+//# sourceMappingURL=workspace.js.map

package/dist/esm/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sources":["../../src/workspace.ts"],"sourcesContent":["import type { SetupInput } from './setup-plan'\nimport type { BearerRef, SecretRef, Secrets } from './secrets'\n\n/**\n * Workspace definition — the portable description of what the agent sees\n * inside the sandbox. Each harness adapter PROJECTS this into its own native\n * format via `projectWorkspace()` (e.g. Claude Code → CLAUDE.md + .claude/skills\n * + --mcp-config). The definition itself is provider- and harness-agnostic.\n */\n\n/** Where the working tree comes from. */\nexport type WorkspaceSource =\n  | {\n      type: 'git'\n      url: string\n      ref?: string\n      auth?: { username?: string; token: string }\n      /**\n       * Clone depth. Defaults to `1` (shallow). Pass a number for a specific\n       * depth, or `'full'` to fetch the entire history.\n       */\n      depth?: number | 'full'\n    }\n  | { type: 'local'; path: string }\n  | { type: 'none' }\n\n/** Clone a git repo into the workspace. `githubRepo` is a convenience wrapper. */\nexport function gitSource(input: {\n  url: string\n  ref?: string\n  auth?: { username?: string; token: string }\n  depth?: number | 'full'\n}): WorkspaceSource {\n  return { type: 'git', ...input }\n}\n\nexport function githubRepo(input: {\n  repo: string\n  ref?: string\n  auth?: { username?: string; token: string }\n  depth?: number | 'full'\n}): WorkspaceSource {\n  const url = input.repo.startsWith('http')\n    ? input.repo\n    : `https://github.com/${input.repo}.git`\n  return {\n    type: 'git',\n    url,\n    ref: input.ref,\n    auth: input.auth,\n    depth: input.depth,\n  }\n}\n\nexport function localSource(path: string): WorkspaceSource {\n  return { type: 'local', path }\n}\n\n/**\n * An MCP server config where header names/values may be plain strings or\n * unresolved SecretRef values. Secrets are resolved by each harness projector\n * at projection time — never at definition time.\n */\nexport type McpConfig = {\n  headers?: Record<string, string | SecretRef | BearerRef>\n  [key: string]: unknown\n}\n\n/** A unit of agent guidance/config projected into the harness's native format. */\nexport type WorkspaceSkill =\n  | { kind: 'file'; path: string; content: string }\n  | { kind: 'agent-skill'; name: string }\n  | { kind: 'mcp'; name: string; config: McpConfig }\n  | {\n      kind: 'git'\n      /** Short `owner/repo` or a full HTTPS URL. */\n      repo: string\n      /** Optional SecretRef for private-repo authentication. */\n      secret?: SecretRef\n      /** Absolute path inside the sandbox to clone into. Defaults to a `.tanstack-skills/<repo>` dir under the workspace root. */\n      into?: string\n    }\n\n/** Write a file (e.g. CLAUDE.md) into the workspace / harness config. */\nexport function fileSkill(input: {\n  path: string\n  content: string\n}): WorkspaceSkill {\n  return { kind: 'file', ...input }\n}\n\n/** Reference a named agent skill the harness should load. */\nexport function agentSkill(name: string): WorkspaceSkill {\n  return { kind: 'agent-skill', name }\n}\n\n/** Project an MCP server into the harness. Header values may be SecretRefs. */\nexport function mcpSkill(name: string, config: McpConfig): WorkspaceSkill {\n  return { kind: 'mcp', name, config }\n}\n\n/**\n * Clone a git repository as a workspace skill (e.g. a private skill repo).\n * The clone is performed during bootstrap; `secret` is resolved from the\n * workspace `secrets` registry at that time.\n */\nexport function gitSkill(input: {\n  repo: string\n  secret?: SecretRef\n  into?: string\n}): WorkspaceSkill {\n  return { kind: 'git', ...input }\n}\n\nexport type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun' | 'auto'\n\nexport interface WorkspaceDefinition {\n  source: WorkspaceSource\n  /** Defaults to `'auto'` — detect from the lockfile after the source lands. */\n  packageManager?: PackageManager\n  /** Commands run once during bootstrap. Accepts a string array (serial) or a builder function for serial/parallel groups. */\n  setup?: SetupInput\n  /** Named commands the agent/user can invoke (e.g. { test: 'pnpm test' }). */\n  scripts?: Record<string, string>\n  /** Guidance/config projected into the harness. */\n  skills?: Array<WorkspaceSkill>\n  /**\n   * Natural-language instructions written to AGENTS.md (and symlinked as\n   * CLAUDE.md, GEMINI.md, etc.) inside the sandbox during bootstrap.\n   */\n  instructions?: string\n  /**\n   * Harness plugin identifiers installed idempotently by each harness\n   * projector (e.g. `['@anthropic/plugin-foo']` for Claude Code).\n   */\n  plugins?: Array<string>\n  /**\n   * Typed secret references. The underlying values are injected into the\n   * sandbox env at create/resume — NEVER written to snapshots, the\n   * SandboxStore, or the event log.\n   */\n  secrets?: Secrets\n  /** Workspace root inside the sandbox. Defaults to `/workspace`. */\n  root?: string\n}\n\nexport function defineWorkspace(\n  definition: WorkspaceDefinition,\n): WorkspaceDefinition {\n  return definition\n}\n"],"names":[],"mappings":"AA2BO,SAAS,UAAU,OAKN;AAClB,SAAO,EAAE,MAAM,OAAO,GAAG,MAAA;AAC3B;AAEO,SAAS,WAAW,OAKP;AAClB,QAAM,MAAM,MAAM,KAAK,WAAW,MAAM,IACpC,MAAM,OACN,sBAAsB,MAAM,IAAI;AACpC,SAAO;AAAA,IACL,MAAM;AAAA,IACN;AAAA,IACA,KAAK,MAAM;AAAA,IACX,MAAM,MAAM;AAAA,IACZ,OAAO,MAAM;AAAA,EAAA;AAEjB;AAEO,SAAS,YAAY,MAA+B;AACzD,SAAO,EAAE,MAAM,SAAS,KAAA;AAC1B;AA4BO,SAAS,UAAU,OAGP;AACjB,SAAO,EAAE,MAAM,QAAQ,GAAG,MAAA;AAC5B;AAGO,SAAS,WAAW,MAA8B;AACvD,SAAO,EAAE,MAAM,eAAe,KAAA;AAChC;AAGO,SAAS,SAAS,MAAc,QAAmC;AACxE,SAAO,EAAE,MAAM,OAAO,MAAM,OAAA;AAC9B;AAOO,SAAS,SAAS,OAIN;AACjB,SAAO,EAAE,MAAM,OAAO,GAAG,MAAA;AAC3B;AAkCO,SAAS,gBACd,YACqB;AACrB,SAAO;AACT;"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@tanstack/ai-sandbox",
+  "version": "0.1.0",
+  "description": "Provider-agnostic sandbox layer for TanStack AI — run harness adapters inside isolated sandboxes (defineSandbox, defineWorkspace, withSandbox) with a uniform SandboxHandle, workspace bootstrap, policy, and resumable lifecycle.",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/ai-sandbox"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "typescript",
+    "tanstack",
+    "sandbox",
+    "harness",
+    "agent",
+    "coding-agent",
+    "isolation",
+    "workspace"
+  ],
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    },
+    "./ngrok": {
+      "types": "./dist/esm/ngrok.d.ts",
+      "import": "./dist/esm/ngrok.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "skills"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "peerDependencies": {
+    "@ngrok/ngrok": "^1.0.0",
+    "@tanstack/ai": "workspace:^"
+  },
+  "peerDependenciesMeta": {
+    "@ngrok/ngrok": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ngrok/ngrok": "^1.7.0",
+    "@tanstack/ai": "workspace:*",
+    "@vitest/coverage-v8": "4.0.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/ai-sandbox/SKILL.md

@@ -0,0 +1,366 @@
+---
+name: ai-sandbox
+description: >
+  Run harness adapters (Claude Code, Codex, OpenCode) INSIDE
+  isolated sandboxes via defineSandbox + withSandbox + a provider
+  (localProcessSandbox / dockerSandbox). Covers declarative provisioning:
+  createSecrets + secret/bearer, skills (agentSkill/gitSkill/mcpSkill/
+  fileSkill), plugins, instructions → canonical AGENTS.md + symlinks projected
+  per harness; shallow-clone default with depth opt-out; serial/parallel setup
+  callback over a persistent shell; snapshot-after-setup default with
+  snapshotMaxAge TTL; defineWorkspace (git/setup/scripts/skills/secrets/
+  instructions/plugins), defineSandboxPolicy (allow/ask/deny), lifecycle/resume,
+  the SandboxHandle (fs/git/process/ports), capability tokens, defineSandbox
+  hooks (onFile/onFileCreate/onFileChange/onFileDelete/onReady/onError/
+  onDestroy) + fileEvents flag, chat middleware sandbox group
+  (defineChatMiddleware sandbox hooks), the sandbox debug category,
+  watchWorkspace as a low-level building block, and the file.changed /
+  sandbox.file / claude-code.session-id events. Use whenever a harness adapter
+  needs a sandbox or when building sandbox providers.
+type: sub-skill
+library: tanstack-ai
+library_version: '0.1.0'
+sources:
+  - 'TanStack/ai:docs/sandbox/overview.md'
+---
+
+# Sandboxes
+
+Harness adapters declare `requires: [SandboxCapability]`. `chat()` errors unless
+some middleware provides it — `withSandbox(...)` does. The adapter then runs the
+agent CLI **inside** the sandbox and streams its events back.
+
+## Setup — Claude Code in a Docker sandbox
+
+```typescript
+import { chat } from '@tanstack/ai'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
+import {
+  defineSandbox,
+  defineWorkspace,
+  withSandbox,
+} from '@tanstack/ai-sandbox'
+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+
+const sandbox = defineSandbox({
+  id: 'repo-agent',
+  provider: dockerSandbox({ image: 'node:22' }),
+  workspace: defineWorkspace({
+    source: { type: 'git', url: 'https://github.com/owner/repo', ref: 'main' },
+    packageManager: 'pnpm',
+    setup: ['corepack enable', 'pnpm install'],
+    scripts: { test: 'pnpm test' },
+    secrets: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? '' },
+  }),
+  lifecycle: { reuse: 'thread', snapshot: 'after-setup', keepAlive: '30m' },
+})
+
+const stream = chat({
+  threadId,
+  adapter: claudeCodeText('sonnet'),
+  messages,
+  middleware: [withSandbox(sandbox)],
+})
+```
+
+## Type-safe secrets
+
+```typescript
+import { createSecrets, bearer } from '@tanstack/ai-sandbox'
+
+const secrets = createSecrets({
+  GH: process.env.GH_TOKEN ?? '',
+  SENTRY: process.env.SENTRY_TOKEN ?? '',
+})
+// secrets.GH is a SecretRef — the underlying string is stored in a
+// non-enumerable symbol-keyed registry and never logged, snapshotted,
+// or written to the sandbox store.
+```
+
+Pass `secrets` to `defineWorkspace({ secrets })` so skill and MCP projectors
+can resolve them. Use `secret: secrets.GH` in `gitSkill` for private-repo auth
+and `secrets.GH` / `bearer(secrets.GH)` in MCP header values:
+
+- `secrets.GH` — resolves to the raw token value.
+- `bearer(secrets.GH)` — resolves to `"Bearer <value>"`.
+
+## Declarative provisioning (skills, plugins, MCP, instructions)
+
+```typescript
+import {
+  agentSkill,
+  gitSkill,
+  mcpSkill,
+  fileSkill,
+  bearer,
+  createSecrets,
+  defineWorkspace,
+} from '@tanstack/ai-sandbox'
+
+const secrets = createSecrets({ GH: process.env.GH_TOKEN ?? '' })
+
+defineWorkspace({
+  source: { type: 'git', url: 'https://github.com/owner/repo' },
+  secrets,
+  skills: [
+    agentSkill('tanstack'), // named skill (no-op with warning on CLIs that lack the concept)
+    gitSkill({
+      repo: 'owner/private-skills',
+      secret: secrets.GH, // resolved at bootstrap time, never stored
+      // into: '/abs/path/inside/sandbox'  // optional; defaults to .tanstack-skills/<repo>
+    }),
+    mcpSkill('my-mcp', {
+      url: 'https://mcp.example.com',
+      headers: { Authorization: bearer(secrets.GH) },
+    }),
+    fileSkill({ path: '.hints.md', content: 'Prefer pnpm.' }),
+  ],
+  plugins: ['@anthropic/plugin-foo'], // no-op with warning on CLIs without a plugin concept
+  instructions: 'Always run `pnpm test` before proposing a change.',
+})
+```
+
+Each skill type is projected per harness (Claude Code → `.mcp.json`; Codex →
+`.codex/config.toml`; OpenCode → `opencode.json`).
+`instructions` is written as `AGENTS.md` at the workspace root; `CLAUDE.md` and
+`GEMINI.md` are created as symlinks (falling back to copies on symlink failure).
+Skills/plugins that a CLI lacks emit a `console.warn` and are skipped.
+
+**`gitSkill` `into` field:** an **absolute path inside the sandbox** where the
+repo is cloned. Defaults to `<root>/.tanstack-skills/<repo-basename>`.
+
+## Fast init
+
+### Shallow clone (`depth`)
+
+`githubRepo` / `gitSource` default to `--depth 1 --single-branch`. Override:
+
+```typescript
+import { githubRepo, defineWorkspace } from '@tanstack/ai-sandbox'
+
+defineWorkspace({ source: githubRepo({ repo: 'owner/app' }) }) // depth 1 (default)
+defineWorkspace({ source: githubRepo({ repo: 'owner/app', depth: 10 }) }) // 10 commits
+defineWorkspace({ source: githubRepo({ repo: 'owner/app', depth: 'full' }) }) // full history
+```
+
+### Serial / parallel `setup` callback
+
+`setup` accepts a plain `Array<string>` (all serial) or a callback that records
+serial and parallel groups over a **persistent shell** whose cwd/env carry over
+between serial steps:
+
+```typescript
+defineWorkspace({
+  source: githubRepo({ repo: 'owner/app' }),
+  setup: ({ serial, parallel }) => {
+    serial('corepack enable')
+    serial('pnpm install')
+    parallel(['pnpm build', 'pnpm typecheck']) // concurrent; inherit cwd+env from shell
+    serial('echo done')
+  },
+})
+```
+
+### Snapshot-after-setup and `snapshotMaxAge`
+
+When the provider supports snapshots, bootstrap takes one automatically after
+`setup` completes. Subsequent runs resume from the snapshot (skipping setup).
+Override or add a TTL:
+
+```typescript
+lifecycle: {
+  snapshot: 'after-setup', // default when provider.capabilities().snapshots
+  snapshotMaxAge: '24h',   // re-create when the snapshot is older than this
+}
+```
+
+Providers without snapshot support skip the step silently.
+
+## Providers
+
+- `localProcessSandbox()` — runs on the host (no isolation; dev loop only).
+- `dockerSandbox({ image })` — isolated container; snapshots, fork, resume-by-id.
+
+Both implement the same `SandboxHandle`: `fs` (read/write/list/mkdir/remove/
+rename/exists), `git` (clone/status/add/commit/push/pull/branch), `process`
+(`exec` + duplex `spawn`), `ports.connect(port)`, `env.set`, optional
+`snapshot()`/`fork()`, `destroy()`. Providers advertise support via
+`capabilities()`; calling an unsupported optional method throws
+`UnsupportedCapabilityError`.
+
+## Policy
+
+```typescript
+import { defineSandboxPolicy } from '@tanstack/ai-sandbox'
+
+const policy = defineSandboxPolicy({
+  commands: {
+    allow: ['pnpm test'],
+    ask: ['curl *'],
+    deny: ['sudo *', 'rm -rf *'],
+  },
+  capabilities: { fileWrite: 'allow', network: 'ask' },
+  default: 'ask', // deny > ask > allow
+})
+// pass to defineSandbox({ policy }); harness adapters map it to native permissions
+```
+
+## Lifecycle &amp; resume
+
+`reuse: 'thread'` resumes one sandbox per `threadId`; the compound key folds in
+provider + workspace hash + tenant so changing the repo/setup/image starts
+fresh. Ensure order: resume running → restore snapshot → create + bootstrap.
+
+## File-event hooks
+
+Watch the workspace for create/change/delete events. Provider-agnostic: native
+`fs.watch` on local-process, a portable `find` poll on Docker/exec-only
+providers (no extra deps or image changes).
+
+Declare hooks on `defineSandbox({ hooks })` (sandbox-scoped) or on any chat
+middleware via the `sandbox` group (run-scoped):
+
+```typescript
+import {
+  defineSandbox,
+  defineChatMiddleware,
+  withSandbox,
+} from '@tanstack/ai-sandbox'
+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+
+// Sandbox-scoped hooks (all optional):
+const sandbox = defineSandbox({
+  id: 'repo-agent',
+  provider: dockerSandbox({ image: 'node:22' }),
+  hooks: {
+    onFile: (e) => console.log(e.type, e.path), // catch-all
+    onFileCreate: (e) => console.log('created', e.path),
+    onFileChange: (e) => console.log('changed', e.path),
+    onFileDelete: (e) => console.log('deleted', e.path),
+    onReady: (handle) => console.log('ready', handle.id),
+    onError: (err) => console.error(err),
+    onDestroy: () => console.log('destroyed'),
+  },
+  fileEvents: true, // default; set false to disable watching entirely
+})
+
+// Run-scoped hooks via chat middleware (ctx is ChatMiddlewareContext):
+const auditMiddleware = defineChatMiddleware({
+  name: 'audit',
+  sandbox: {
+    onFile: (ctx, e) => console.log(ctx.runId, e.type, e.path),
+    onFileCreate: (ctx, e) => db.log({ run: ctx.runId, event: e }),
+    onFileChange: (ctx, e) => metrics.increment('file.change'),
+    onFileDelete: (ctx, e) => console.warn('deleted', e.path),
+  },
+})
+
+// No extra middleware needed — sandbox.file CUSTOM events are emitted
+// automatically. Read them from the stream:
+for await (const chunk of stream) {
+  if (chunk.type === 'CUSTOM' && chunk.name === 'sandbox.file') {
+    const value = chunk.value
+    if (
+      value !== null &&
+      typeof value === 'object' &&
+      'type' in value &&
+      'path' in value
+    ) {
+      console.log('file event', value) // { type, path, timestamp }
+    }
+  }
+}
+```
+
+`watchWorkspace()` is available as a low-level building block for watching
+outside a `chat()` run:
+
+```typescript
+import { watchWorkspace } from '@tanstack/ai-sandbox'
+
+const watcher = await watchWorkspace(handle, {
+  onEvent: (e) => console.log(e.type, e.path),
+  ignore: ['.git', 'node_modules'], // default
+})
+await watcher.stop()
+```
+
+Enable the `sandbox` debug category to log watcher start/stop, event dispatch,
+and lifecycle transitions:
+
+```typescript
+chat({ threadId, adapter, messages, debug: { sandbox: true } })
+// or debug: true to enable all categories
+```
+
+## Edge / serverless execution
+
+A request-scoped Worker can't hold a multi-minute agent run open. The
+serverless/edge model splits this: a **trigger** starts the run and returns
+immediately, a **durable orchestrator** drives it, and clients **tail from a
+resumable cursor**.
+
+Core primitives (`@tanstack/ai-sandbox`, transport- and runtime-agnostic):
+
+- **`RunEventLog` / `InMemoryRunEventLog`** — append-only, `seq`-indexed log of a
+  run's `StreamChunk`s with replay-then-tail reads. A dropped connection / new
+  tab / hibernated orchestrator reconnect by passing their last-seen `seq`
+  (`read({ fromSeq })`). `TerminalRunStatus` = `done | error | aborted`.
+- **`pipeToRunLog` / `RunController`** — the run driver. `pipeToRunLog` pumps a
+  `chat()` stream into a log and **never rejects**: a thrown stream error becomes
+  a terminal `RUN_ERROR` event, so detached clients always observe failures.
+  `RunController.start` is fire-and-track; `attach(runId, { fromSeq })` tails;
+  `drain()` awaits in-flight runs (e.g. in a `waitUntil`).
+- **Transport-agnostic tool-bridge** — `createToolBridgeCore` +
+  `handleBridgeJsonRpc` are the portable core; `startHostToolBridge` is the
+  `node:http` host transport. The `ToolBridgeProvisioner` capability injects the
+  transport, so an edge orchestrator serves the same core from its own `fetch`
+  handler (no raw TCP listener). Default = host transport.
+- **Co-located host-tool seam** — `toolDescriptors` / `remoteToolStubs` /
+  `httpRemoteToolExecutor` (container side) + `executeHostTool` (orchestrator
+  side): only chat()-tool EXECUTION crosses the container→orchestrator boundary,
+  not the whole MCP protocol.
+- **`SandboxCapabilities.writableStdin`** — `false` for providers (e.g.
+  Cloudflare) with no writable host→process stdin; stdin-fed harnesses then
+  deliver the prompt via a file + in-shell redirection (`claude -p … < file`).
+
+Cloudflare runtime (`@tanstack/ai-sandbox-cloudflare`):
+
+- `createCloudflareSandboxAgent(config)` → `{ Coordinator, Sandbox, worker }` —
+  an app's `worker.ts` is one configured call plus the wrangler-required DO
+  re-exports. Two models via `mode`: `do-drives` (the DO runs `chat()`) and
+  `colocated` (harness + bridge run in-container; the DO is a thin coordinator,
+  pair with `runInContainerHarness` from `/runner`).
+- `DurableObjectRunEventLog` mirrors `InMemoryRunEventLog` over DO storage;
+  `timingSafeBearerEqualWeb` is the Web-Crypto constant-time bearer check.
+
+## Events
+
+- `claude-code.session-id` (CUSTOM) — resumable session id → pass back via
+  `modelOptions.sessionId`.
+- `file.changed` (CUSTOM) — `{ path, diff }` working-tree diff after the run.
+- `sandbox.file` (CUSTOM) — `{ type, path, timestamp }` per file create/change/
+  delete, emitted automatically when a sandbox is active.
+
+## Critical rules
+
+- **Harness adapters require a sandbox.** Always include `withSandbox(...)` in
+  `middleware` — without it `chat()` throws a missing-capability error.
+- **Secrets** (`workspace.secrets`) are injected into the sandbox env and never
+  persisted (no snapshots, no sandbox store, no event log). Always create them
+  with `createSecrets(...)` so the values stay hidden behind `SecretRef` tokens.
+  The agent binary (`claude`) must exist in the sandbox image (install it in
+  `setup` or bake it into the image).
+- **Secret-bearing projected files** (e.g. MCP config with resolved header
+  values) are re-written on every projection call so rotated secrets re-apply;
+  they are never included in a snapshot.
+- **chat()-provided `tools` are bridged** into the in-sandbox agent over a
+  host-side MCP tool-proxy: the agent calls them as `mcp__tanstack__<tool>` and
+  each call is proxied back to the host where the tool's `execute()` runs (with
+  its closures / DB / secrets). The agent also has its own native tools
+  (Bash/Edit/Read/…). The host bridge binds on the host; the sandbox reaches it
+  (localhost, or `host.docker.internal` for Docker), gated by a per-run bearer
+  token.
+- Use `localProcessSandbox()` only in trusted/dev contexts (no isolation).
+- Skills/plugins that a CLI lacks (e.g. `agentSkill` on Codex, `plugins` on
+  Codex) warn and skip — they do not throw.