@tanstack/ai-sandbox 0.5.6 → 0.5.9

package/README.md

@@ -74,6 +74,13 @@ Pick a **provider** package for where the sandbox runs:
 | `@tanstack/ai-sandbox-daytona`       | Daytona cloud sandboxes, snapshots     |
 | `@tanstack/ai-sandbox-upstash-box`   | Upstash Box cloud sandboxes, snapshots |
 | `@tanstack/ai-sandbox-sprites`       | Sprites stateful sandboxes             |
+| `@tanstack/ai-sandbox-blaxel`        | Blaxel cloud sandboxes and previews    |
+
+Install the provider you select separately. For Blaxel:
+
+```bash
+npm install @tanstack/ai-sandbox-blaxel
+```
 
 **Harness adapters** are separate packages. The default path is **Grok Build** (`@tanstack/ai-grok-build`); others include `@tanstack/ai-claude-code`, `@tanstack/ai-codex`, and `@tanstack/ai-opencode`. All require `withSandbox(...)` middleware — `chat()` fails fast without it.
 

package/dist/esm/tool-bridge.js

@@ -1,5 +1,6 @@
 import { randomBytes, timingSafeEqual } from "node:crypto";
 import { createServer } from "node:http";
+import { once } from "node:events";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -221,7 +222,7 @@ async function startHostToolBridge(tools, options) {
 			if (!res.headersSent) res.writeHead(500).end("bridge error");
 		});
 	});
-	await new Promise((resolve) => httpServer.listen(0, bindAddress, resolve));
+	await once(httpServer.listen(0, bindAddress), "listening");
 	const port = httpServer.address().port;
 	return {
 		name: BRIDGED_MCP_SERVER_NAME,

package/dist/esm/tool-bridge.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-bridge.js","names":[],"sources":["../../src/tool-bridge.ts"],"sourcesContent":["/**\n * MCP tool-proxy bridge, shared by all harness adapters.\n *\n * Exposes chat()-provided server tools to an in-sandbox agent as an MCP server.\n * The agent (inside the sandbox) calls `mcp__tanstack__<tool>`; the call is\n * proxied OUT to a bridge endpoint, where the tool's `execute()` runs in the\n * orchestrator process (with its closures / DB / secrets), and the result is\n * returned into the sandbox.\n *\n * The bridge is split into a transport-agnostic CORE and a TRANSPORT:\n * - {@link createToolBridgeCore} owns tool dispatch + the permission resolver\n *   (no I/O). It is what makes the bridge portable.\n * - {@link startHostToolBridge} is the `node:http` transport for a long-running\n *   host (laptop / CI / Docker orchestrator). It binds loopback unless the\n *   sandbox must reach it via `host.docker.internal`, and authenticates with a\n *   constant-time bearer check.\n * - A serverless/edge orchestrator (e.g. a Durable Object) instead serves the\n *   SAME core from its own `fetch` handler — no raw TCP listener — see\n *   {@link handleBridgeJsonRpc} and the Cloudflare example.\n */\nimport { createServer } from 'node:http'\nimport { randomBytes, timingSafeEqual } from 'node:crypto'\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'\nimport {\n  CallToolRequestSchema,\n  ListToolsRequestSchema,\n} from '@modelcontextprotocol/sdk/types.js'\nimport type { AddressInfo } from 'node:net'\nimport type { AnyTool } from '@tanstack/ai'\n\n/**\n * Name of the bridged MCP server. The agent sees tools as\n * `mcp__tanstack__<tool>`; each adapter's stream translator strips this prefix\n * so tool-call events match the names the application registered.\n */\nexport const BRIDGED_MCP_SERVER_NAME = 'tanstack'\n\n/** Hostname the sandbox uses to reach the bridge endpoint, per provider. */\nexport function hostForSandbox(provider: string): string {\n  return provider === 'docker' || provider === 'sbx'\n    ? 'host.docker.internal'\n    : '127.0.0.1'\n}\n\n/** Result of a permission decision returned to the harness's prompt tool. */\nexport interface PermissionToolResult {\n  behavior: 'allow' | 'deny'\n  message?: string\n  updatedInput?: unknown\n}\n\nexport interface BridgePermission {\n  toolName: string\n  resolve: (input: {\n    tool_name?: string\n    input?: unknown\n  }) => PermissionToolResult | Promise<PermissionToolResult>\n}\n\nexport interface ToolBridgeCoreOptions {\n  /** Runtime context forwarded to each tool's `execute()`. */\n  context?: unknown\n  /** Abort signal forwarded to each tool's `execute()`. */\n  signal?: AbortSignal\n  /**\n   * Forwarded to each tool's `execute()` so a bridged tool can stream progress /\n   * custom events back to the client mid-execution (e.g. code mode's\n   * `code_mode:console` logs). Without it those events are silently dropped — the\n   * bridge runs out-of-band from the main tool executor, so the executor's own\n   * `emitCustomEvent` never reaches a bridged tool. The harness adapter supplies\n   * one that injects a CUSTOM chunk into its live output stream.\n   */\n  emitCustomEvent?: (eventName: string, value: Record<string, unknown>) => void\n  /**\n   * Optional permission-prompt tool (e.g. for Claude Code's\n   * `--permission-prompt-tool`). When set, the bridge exposes an extra MCP tool\n   * `<name>` whose handler returns the orchestrator's allow/deny decision.\n   */\n  permission?: BridgePermission\n}\n\n/** An MCP tool descriptor as advertised to the in-sandbox agent. */\nexport interface ToolDescriptor {\n  name: string\n  description?: string\n  inputSchema: { type: 'object'; [key: string]: unknown }\n}\n\n/**\n * Coerce a tool's `inputSchema` into the object-schema shape MCP advertises,\n * substituting an empty object schema when it isn't already a JSON-schema object\n * (project rule: a guard, not an `as` cast).\n */\nfunction toObjectSchema(schema: unknown): {\n  type: 'object'\n  [key: string]: unknown\n} {\n  if (\n    schema !== null &&\n    typeof schema === 'object' &&\n    'type' in schema &&\n    schema.type === 'object'\n  ) {\n    return { ...schema, type: 'object' }\n  }\n  return { type: 'object', properties: {} }\n}\n\n/** MCP `tools/call` result shape. */\nexport interface ToolCallResult {\n  content: Array<{ type: 'text'; text: string }>\n  isError?: boolean\n}\n\n/**\n * Transport-agnostic bridge logic: list tools, and dispatch a tool/permission\n * call. No sockets, no auth — a transport ({@link startHostToolBridge} or a\n * `fetch` handler) wraps this and owns I/O + the bearer check.\n */\nexport interface ToolBridgeCore {\n  listTools: () => Array<ToolDescriptor>\n  callTool: (name: string, args: unknown) => Promise<ToolCallResult>\n}\n\n/** Build the transport-agnostic bridge core for the given tools. */\nexport function createToolBridgeCore(\n  tools: Array<AnyTool>,\n  options: ToolBridgeCoreOptions = {},\n): ToolBridgeCore {\n  const toolsByName = new Map(tools.map((tool) => [tool.name, tool]))\n  const permission = options.permission\n\n  const permissionDescriptor: ToolDescriptor | undefined = permission\n    ? {\n        name: permission.toolName,\n        description:\n          'Permission prompt: returns {behavior:\"allow\"|\"deny\"} for a requested action.',\n        inputSchema: { type: 'object', properties: {} },\n      }\n    : undefined\n\n  return {\n    listTools() {\n      return [\n        ...tools.map((tool) => ({\n          name: tool.name,\n          description: tool.description,\n          inputSchema: toObjectSchema(tool.inputSchema),\n        })),\n        ...(permissionDescriptor ? [permissionDescriptor] : []),\n      ]\n    },\n\n    async callTool(name, args) {\n      if (permission && name === permission.toolName) {\n        const result = await permission.resolve(args ?? {})\n        return { content: [{ type: 'text', text: JSON.stringify(result) }] }\n      }\n      const tool = toolsByName.get(name)\n      if (!tool?.execute) throw new Error(`Unknown tool: ${name}`)\n      try {\n        const result: unknown = await tool.execute(args ?? {}, {\n          context: options.context,\n          abortSignal: options.signal,\n          // No-op default so tools that always call it (e.g. code mode) don't\n          // crash when the transport didn't wire a sink.\n          emitCustomEvent: options.emitCustomEvent ?? (() => {}),\n        })\n        const text =\n          typeof result === 'string' ? result : JSON.stringify(result)\n        return { content: [{ type: 'text', text }] }\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error)\n        return {\n          isError: true,\n          content: [\n            { type: 'text', text: `Tool execution failed: ${message}` },\n          ],\n        }\n      }\n    },\n  }\n}\n\n/**\n * Minimal JSON-RPC dispatcher over a {@link ToolBridgeCore}, so a `fetch`-based\n * transport (Worker / Durable Object) can serve MCP `initialize` / `tools/list`\n * / `tools/call` without the node-specific HTTP transport. Returns the JSON-RPC\n * response object, or `null` for a notification (no `id`).\n */\nexport async function handleBridgeJsonRpc(\n  core: ToolBridgeCore,\n  message: unknown,\n): Promise<unknown> {\n  if (message === null || typeof message !== 'object') {\n    return {\n      jsonrpc: '2.0',\n      id: null,\n      error: { code: -32600, message: 'Invalid Request' },\n    }\n  }\n  const rpc = message as { id?: unknown; method?: unknown; params?: unknown }\n  const id = rpc.id ?? null\n  const respond = (result: unknown): unknown => ({ jsonrpc: '2.0', id, result })\n  switch (rpc.method) {\n    case 'initialize':\n      return respond({\n        protocolVersion: '2024-11-05',\n        capabilities: { tools: {} },\n        serverInfo: { name: BRIDGED_MCP_SERVER_NAME, version: '1.0.0' },\n      })\n    case 'notifications/initialized':\n      return null\n    case 'tools/list':\n      return respond({ tools: core.listTools() })\n    case 'tools/call': {\n      const params = (rpc.params ?? {}) as {\n        name?: unknown\n        arguments?: unknown\n      }\n      if (typeof params.name !== 'string') {\n        return {\n          jsonrpc: '2.0',\n          id,\n          error: { code: -32602, message: 'Invalid params: name' },\n        }\n      }\n      return respond(await core.callTool(params.name, params.arguments ?? {}))\n    }\n    default:\n      return {\n        jsonrpc: '2.0',\n        id,\n        error: { code: -32601, message: 'Method not found' },\n      }\n  }\n}\n\n/**\n * Constant-time check of an `Authorization: Bearer <token>` header against the\n * expected token. Length mismatch returns false early (token length is not\n * secret); equal-length comparison is timing-safe.\n */\nexport function timingSafeBearerEqual(\n  header: string | undefined,\n  token: string,\n): boolean {\n  if (header === undefined) return false\n  const a = Buffer.from(header)\n  const b = Buffer.from(`Bearer ${token}`)\n  if (a.length !== b.length) return false\n  return timingSafeEqual(a, b)\n}\n\nexport interface HostToolBridge {\n  /** MCP server name; tools appear to the agent as `mcp__<name>__<tool>`. */\n  name: string\n  /** URL the SANDBOX uses to reach this bridge. */\n  url: string\n  /** Per-run bearer token gating the endpoint. */\n  token: string\n  close: () => Promise<void>\n}\n\nexport interface StartBridgeOptions extends ToolBridgeCoreOptions {\n  /** Hostname the sandbox uses to reach the host (e.g. `host.docker.internal`). */\n  hostForSandbox: string\n  /**\n   * Address to bind the listener to. Defaults to `127.0.0.1` (loopback) and is\n   * widened to `0.0.0.0` only when the sandbox reaches the host via\n   * `host.docker.internal` (a container can't reach the host's loopback).\n   */\n  bindAddress?: string\n}\n\nfunction buildMcpServer(core: ToolBridgeCore): McpServer {\n  const server = new McpServer(\n    { name: BRIDGED_MCP_SERVER_NAME, version: '1.0.0' },\n    { capabilities: { tools: {} } },\n  )\n  server.server.setRequestHandler(ListToolsRequestSchema, () => ({\n    tools: core.listTools(),\n  }))\n  server.server.setRequestHandler(CallToolRequestSchema, async (request) => {\n    const result = await core.callTool(\n      request.params.name,\n      request.params.arguments ?? {},\n    )\n    return {\n      content: result.content,\n      ...(result.isError ? { isError: true } : {}),\n    }\n  })\n  return server\n}\n\n/**\n * Start the `node:http` MCP tool-proxy bridge for the given tools. For a\n * long-running host (laptop / CI / Docker orchestrator). Serverless/edge\n * orchestrators serve {@link createToolBridgeCore} from their own `fetch`\n * handler instead.\n */\nexport async function startHostToolBridge(\n  tools: Array<AnyTool>,\n  options: StartBridgeOptions,\n): Promise<HostToolBridge> {\n  const token = randomBytes(24).toString('hex')\n  const core = createToolBridgeCore(tools, options)\n  // Loopback by default; widen to all interfaces only for the Docker bridge,\n  // which a container reaches via host.docker.internal (host gateway).\n  const bindAddress =\n    options.bindAddress ??\n    (options.hostForSandbox === 'host.docker.internal'\n      ? '0.0.0.0'\n      : '127.0.0.1')\n\n  const httpServer = createServer((req, res) => {\n    void (async () => {\n      if (!timingSafeBearerEqual(req.headers['authorization'], token)) {\n        res.writeHead(401).end('unauthorized')\n        return\n      }\n      const server = buildMcpServer(core)\n      const transport = new StreamableHTTPServerTransport({\n        sessionIdGenerator: undefined,\n      })\n      res.on('close', () => {\n        void transport.close()\n        void server.close()\n      })\n      await server.connect(transport)\n\n      let body = ''\n      for await (const chunk of req) body += chunk\n      let parsed: unknown\n      try {\n        parsed = body ? JSON.parse(body) : undefined\n      } catch {\n        // Malformed agent request → 400, distinct from an internal 500.\n        if (!res.headersSent) res.writeHead(400).end('invalid JSON body')\n        return\n      }\n      await transport.handleRequest(req, res, parsed)\n    })().catch((error: unknown) => {\n      // Log the underlying fault — on the host/Docker path there is no run-log\n      // capturing it, so swallowing it leaves an operator with nothing.\n      console.error('[tool-bridge] request handler failed:', error)\n      if (!res.headersSent) res.writeHead(500).end('bridge error')\n    })\n  })\n\n  await new Promise<void>((resolve) =>\n    httpServer.listen(0, bindAddress, resolve),\n  )\n  const port = (httpServer.address() as AddressInfo).port\n  const url = `http://${options.hostForSandbox}:${port}/mcp`\n\n  return {\n    name: BRIDGED_MCP_SERVER_NAME,\n    url,\n    token,\n    close: () =>\n      new Promise<void>((resolve) => httpServer.close(() => resolve())),\n  }\n}\n\n/** A provisioned, reachable bridge endpoint (same shape as {@link HostToolBridge}). */\nexport type ProvisionedBridge = HostToolBridge\n\nexport interface ToolBridgeProvisionOptions extends ToolBridgeCoreOptions {\n  /** Sandbox provider name, to derive how the sandbox reaches the bridge. */\n  provider: string\n}\n\n/**\n * Stands up the tool-bridge endpoint for a run. The seam that makes the bridge\n * portable across runtimes: a harness adapter asks its capability context for a\n * provisioner and uses {@link nodeHttpBridgeProvisioner} as the default (host /\n * Docker). A serverless/edge orchestrator PROVIDES its own — e.g. a Durable\n * Object that mounts {@link createToolBridgeCore} / {@link handleBridgeJsonRpc}\n * on its `fetch` handler and returns a sandbox-reachable URL — so no raw TCP\n * listener is needed.\n */\nexport interface ToolBridgeProvisioner {\n  provision: (\n    tools: Array<AnyTool>,\n    options: ToolBridgeProvisionOptions,\n  ) => Promise<ProvisionedBridge>\n}\n\n/** Default provisioner: a `node:http` listener on the host. */\nexport const nodeHttpBridgeProvisioner: ToolBridgeProvisioner = {\n  provision(tools, options) {\n    const { provider, ...core } = options\n    return startHostToolBridge(tools, {\n      hostForSandbox: hostForSandbox(provider),\n      ...core,\n    })\n  },\n}\n"],"mappings":"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"}
+{"version":3,"file":"tool-bridge.js","names":[],"sources":["../../src/tool-bridge.ts"],"sourcesContent":["/**\n * MCP tool-proxy bridge, shared by all harness adapters.\n *\n * Exposes chat()-provided server tools to an in-sandbox agent as an MCP server.\n * The agent (inside the sandbox) calls `mcp__tanstack__<tool>`; the call is\n * proxied OUT to a bridge endpoint, where the tool's `execute()` runs in the\n * orchestrator process (with its closures / DB / secrets), and the result is\n * returned into the sandbox.\n *\n * The bridge is split into a transport-agnostic CORE and a TRANSPORT:\n * - {@link createToolBridgeCore} owns tool dispatch + the permission resolver\n *   (no I/O). It is what makes the bridge portable.\n * - {@link startHostToolBridge} is the `node:http` transport for a long-running\n *   host (laptop / CI / Docker orchestrator). It binds loopback unless the\n *   sandbox must reach it via `host.docker.internal`, and authenticates with a\n *   constant-time bearer check.\n * - A serverless/edge orchestrator (e.g. a Durable Object) instead serves the\n *   SAME core from its own `fetch` handler — no raw TCP listener — see\n *   {@link handleBridgeJsonRpc} and the Cloudflare example.\n */\nimport { createServer } from 'node:http'\nimport { randomBytes, timingSafeEqual } from 'node:crypto'\nimport { once } from 'node:events'\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'\nimport { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'\nimport {\n  CallToolRequestSchema,\n  ListToolsRequestSchema,\n} from '@modelcontextprotocol/sdk/types.js'\nimport type { AddressInfo } from 'node:net'\nimport type { AnyTool } from '@tanstack/ai'\n\n/**\n * Name of the bridged MCP server. The agent sees tools as\n * `mcp__tanstack__<tool>`; each adapter's stream translator strips this prefix\n * so tool-call events match the names the application registered.\n */\nexport const BRIDGED_MCP_SERVER_NAME = 'tanstack'\n\n/** Hostname the sandbox uses to reach the bridge endpoint, per provider. */\nexport function hostForSandbox(provider: string): string {\n  return provider === 'docker' || provider === 'sbx'\n    ? 'host.docker.internal'\n    : '127.0.0.1'\n}\n\n/** Result of a permission decision returned to the harness's prompt tool. */\nexport interface PermissionToolResult {\n  behavior: 'allow' | 'deny'\n  message?: string\n  updatedInput?: unknown\n}\n\nexport interface BridgePermission {\n  toolName: string\n  resolve: (input: {\n    tool_name?: string\n    input?: unknown\n  }) => PermissionToolResult | Promise<PermissionToolResult>\n}\n\nexport interface ToolBridgeCoreOptions {\n  /** Runtime context forwarded to each tool's `execute()`. */\n  context?: unknown\n  /** Abort signal forwarded to each tool's `execute()`. */\n  signal?: AbortSignal\n  /**\n   * Forwarded to each tool's `execute()` so a bridged tool can stream progress /\n   * custom events back to the client mid-execution (e.g. code mode's\n   * `code_mode:console` logs). Without it those events are silently dropped — the\n   * bridge runs out-of-band from the main tool executor, so the executor's own\n   * `emitCustomEvent` never reaches a bridged tool. The harness adapter supplies\n   * one that injects a CUSTOM chunk into its live output stream.\n   */\n  emitCustomEvent?: (eventName: string, value: Record<string, unknown>) => void\n  /**\n   * Optional permission-prompt tool (e.g. for Claude Code's\n   * `--permission-prompt-tool`). When set, the bridge exposes an extra MCP tool\n   * `<name>` whose handler returns the orchestrator's allow/deny decision.\n   */\n  permission?: BridgePermission\n}\n\n/** An MCP tool descriptor as advertised to the in-sandbox agent. */\nexport interface ToolDescriptor {\n  name: string\n  description?: string\n  inputSchema: { type: 'object'; [key: string]: unknown }\n}\n\n/**\n * Coerce a tool's `inputSchema` into the object-schema shape MCP advertises,\n * substituting an empty object schema when it isn't already a JSON-schema object\n * (project rule: a guard, not an `as` cast).\n */\nfunction toObjectSchema(schema: unknown): {\n  type: 'object'\n  [key: string]: unknown\n} {\n  if (\n    schema !== null &&\n    typeof schema === 'object' &&\n    'type' in schema &&\n    schema.type === 'object'\n  ) {\n    return { ...schema, type: 'object' }\n  }\n  return { type: 'object', properties: {} }\n}\n\n/** MCP `tools/call` result shape. */\nexport interface ToolCallResult {\n  content: Array<{ type: 'text'; text: string }>\n  isError?: boolean\n}\n\n/**\n * Transport-agnostic bridge logic: list tools, and dispatch a tool/permission\n * call. No sockets, no auth — a transport ({@link startHostToolBridge} or a\n * `fetch` handler) wraps this and owns I/O + the bearer check.\n */\nexport interface ToolBridgeCore {\n  listTools: () => Array<ToolDescriptor>\n  callTool: (name: string, args: unknown) => Promise<ToolCallResult>\n}\n\n/** Build the transport-agnostic bridge core for the given tools. */\nexport function createToolBridgeCore(\n  tools: Array<AnyTool>,\n  options: ToolBridgeCoreOptions = {},\n): ToolBridgeCore {\n  const toolsByName = new Map(tools.map((tool) => [tool.name, tool]))\n  const permission = options.permission\n\n  const permissionDescriptor: ToolDescriptor | undefined = permission\n    ? {\n        name: permission.toolName,\n        description:\n          'Permission prompt: returns {behavior:\"allow\"|\"deny\"} for a requested action.',\n        inputSchema: { type: 'object', properties: {} },\n      }\n    : undefined\n\n  return {\n    listTools() {\n      return [\n        ...tools.map((tool) => ({\n          name: tool.name,\n          description: tool.description,\n          inputSchema: toObjectSchema(tool.inputSchema),\n        })),\n        ...(permissionDescriptor ? [permissionDescriptor] : []),\n      ]\n    },\n\n    async callTool(name, args) {\n      if (permission && name === permission.toolName) {\n        const result = await permission.resolve(args ?? {})\n        return { content: [{ type: 'text', text: JSON.stringify(result) }] }\n      }\n      const tool = toolsByName.get(name)\n      if (!tool?.execute) throw new Error(`Unknown tool: ${name}`)\n      try {\n        const result: unknown = await tool.execute(args ?? {}, {\n          context: options.context,\n          abortSignal: options.signal,\n          // No-op default so tools that always call it (e.g. code mode) don't\n          // crash when the transport didn't wire a sink.\n          emitCustomEvent: options.emitCustomEvent ?? (() => {}),\n        })\n        const text =\n          typeof result === 'string' ? result : JSON.stringify(result)\n        return { content: [{ type: 'text', text }] }\n      } catch (error) {\n        const message = error instanceof Error ? error.message : String(error)\n        return {\n          isError: true,\n          content: [\n            { type: 'text', text: `Tool execution failed: ${message}` },\n          ],\n        }\n      }\n    },\n  }\n}\n\n/**\n * Minimal JSON-RPC dispatcher over a {@link ToolBridgeCore}, so a `fetch`-based\n * transport (Worker / Durable Object) can serve MCP `initialize` / `tools/list`\n * / `tools/call` without the node-specific HTTP transport. Returns the JSON-RPC\n * response object, or `null` for a notification (no `id`).\n */\nexport async function handleBridgeJsonRpc(\n  core: ToolBridgeCore,\n  message: unknown,\n): Promise<unknown> {\n  if (message === null || typeof message !== 'object') {\n    return {\n      jsonrpc: '2.0',\n      id: null,\n      error: { code: -32600, message: 'Invalid Request' },\n    }\n  }\n  const rpc = message as { id?: unknown; method?: unknown; params?: unknown }\n  const id = rpc.id ?? null\n  const respond = (result: unknown): unknown => ({ jsonrpc: '2.0', id, result })\n  switch (rpc.method) {\n    case 'initialize':\n      return respond({\n        protocolVersion: '2024-11-05',\n        capabilities: { tools: {} },\n        serverInfo: { name: BRIDGED_MCP_SERVER_NAME, version: '1.0.0' },\n      })\n    case 'notifications/initialized':\n      return null\n    case 'tools/list':\n      return respond({ tools: core.listTools() })\n    case 'tools/call': {\n      const params = (rpc.params ?? {}) as {\n        name?: unknown\n        arguments?: unknown\n      }\n      if (typeof params.name !== 'string') {\n        return {\n          jsonrpc: '2.0',\n          id,\n          error: { code: -32602, message: 'Invalid params: name' },\n        }\n      }\n      return respond(await core.callTool(params.name, params.arguments ?? {}))\n    }\n    default:\n      return {\n        jsonrpc: '2.0',\n        id,\n        error: { code: -32601, message: 'Method not found' },\n      }\n  }\n}\n\n/**\n * Constant-time check of an `Authorization: Bearer <token>` header against the\n * expected token. Length mismatch returns false early (token length is not\n * secret); equal-length comparison is timing-safe.\n */\nexport function timingSafeBearerEqual(\n  header: string | undefined,\n  token: string,\n): boolean {\n  if (header === undefined) return false\n  const a = Buffer.from(header)\n  const b = Buffer.from(`Bearer ${token}`)\n  if (a.length !== b.length) return false\n  return timingSafeEqual(a, b)\n}\n\nexport interface HostToolBridge {\n  /** MCP server name; tools appear to the agent as `mcp__<name>__<tool>`. */\n  name: string\n  /** URL the SANDBOX uses to reach this bridge. */\n  url: string\n  /** Per-run bearer token gating the endpoint. */\n  token: string\n  close: () => Promise<void>\n}\n\nexport interface StartBridgeOptions extends ToolBridgeCoreOptions {\n  /** Hostname the sandbox uses to reach the host (e.g. `host.docker.internal`). */\n  hostForSandbox: string\n  /**\n   * Address to bind the listener to. Defaults to `127.0.0.1` (loopback) and is\n   * widened to `0.0.0.0` only when the sandbox reaches the host via\n   * `host.docker.internal` (a container can't reach the host's loopback).\n   */\n  bindAddress?: string\n}\n\nfunction buildMcpServer(core: ToolBridgeCore): McpServer {\n  const server = new McpServer(\n    { name: BRIDGED_MCP_SERVER_NAME, version: '1.0.0' },\n    { capabilities: { tools: {} } },\n  )\n  server.server.setRequestHandler(ListToolsRequestSchema, () => ({\n    tools: core.listTools(),\n  }))\n  server.server.setRequestHandler(CallToolRequestSchema, async (request) => {\n    const result = await core.callTool(\n      request.params.name,\n      request.params.arguments ?? {},\n    )\n    return {\n      content: result.content,\n      ...(result.isError ? { isError: true } : {}),\n    }\n  })\n  return server\n}\n\n/**\n * Start the `node:http` MCP tool-proxy bridge for the given tools. For a\n * long-running host (laptop / CI / Docker orchestrator). Serverless/edge\n * orchestrators serve {@link createToolBridgeCore} from their own `fetch`\n * handler instead.\n */\nexport async function startHostToolBridge(\n  tools: Array<AnyTool>,\n  options: StartBridgeOptions,\n): Promise<HostToolBridge> {\n  const token = randomBytes(24).toString('hex')\n  const core = createToolBridgeCore(tools, options)\n  // Loopback by default; widen to all interfaces only for the Docker bridge,\n  // which a container reaches via host.docker.internal (host gateway).\n  const bindAddress =\n    options.bindAddress ??\n    (options.hostForSandbox === 'host.docker.internal'\n      ? '0.0.0.0'\n      : '127.0.0.1')\n\n  const httpServer = createServer((req, res) => {\n    void (async () => {\n      if (!timingSafeBearerEqual(req.headers['authorization'], token)) {\n        res.writeHead(401).end('unauthorized')\n        return\n      }\n      const server = buildMcpServer(core)\n      const transport = new StreamableHTTPServerTransport({\n        sessionIdGenerator: undefined,\n      })\n      res.on('close', () => {\n        void transport.close()\n        void server.close()\n      })\n      await server.connect(transport)\n\n      let body = ''\n      for await (const chunk of req) body += chunk\n      let parsed: unknown\n      try {\n        parsed = body ? JSON.parse(body) : undefined\n      } catch {\n        // Malformed agent request → 400, distinct from an internal 500.\n        if (!res.headersSent) res.writeHead(400).end('invalid JSON body')\n        return\n      }\n      await transport.handleRequest(req, res, parsed)\n    })().catch((error: unknown) => {\n      // Log the underlying fault — on the host/Docker path there is no run-log\n      // capturing it, so swallowing it leaves an operator with nothing.\n      console.error('[tool-bridge] request handler failed:', error)\n      if (!res.headersSent) res.writeHead(500).end('bridge error')\n    })\n  })\n\n  await once(httpServer.listen(0, bindAddress), 'listening')\n  const port = (httpServer.address() as AddressInfo).port\n  const url = `http://${options.hostForSandbox}:${port}/mcp`\n\n  return {\n    name: BRIDGED_MCP_SERVER_NAME,\n    url,\n    token,\n    close: () =>\n      new Promise<void>((resolve) => httpServer.close(() => resolve())),\n  }\n}\n\n/** A provisioned, reachable bridge endpoint (same shape as {@link HostToolBridge}). */\nexport type ProvisionedBridge = HostToolBridge\n\nexport interface ToolBridgeProvisionOptions extends ToolBridgeCoreOptions {\n  /** Sandbox provider name, to derive how the sandbox reaches the bridge. */\n  provider: string\n}\n\n/**\n * Stands up the tool-bridge endpoint for a run. The seam that makes the bridge\n * portable across runtimes: a harness adapter asks its capability context for a\n * provisioner and uses {@link nodeHttpBridgeProvisioner} as the default (host /\n * Docker). A serverless/edge orchestrator PROVIDES its own — e.g. a Durable\n * Object that mounts {@link createToolBridgeCore} / {@link handleBridgeJsonRpc}\n * on its `fetch` handler and returns a sandbox-reachable URL — so no raw TCP\n * listener is needed.\n */\nexport interface ToolBridgeProvisioner {\n  provision: (\n    tools: Array<AnyTool>,\n    options: ToolBridgeProvisionOptions,\n  ) => Promise<ProvisionedBridge>\n}\n\n/** Default provisioner: a `node:http` listener on the host. */\nexport const nodeHttpBridgeProvisioner: ToolBridgeProvisioner = {\n  provision(tools, options) {\n    const { provider, ...core } = options\n    return startHostToolBridge(tools, {\n      hostForSandbox: hostForSandbox(provider),\n      ...core,\n    })\n  },\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-sandbox",
-  "version": "0.5.6",
+  "version": "0.5.9",
   "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",
@@ -56,13 +56,13 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@tanstack/ai-skills": "^0.1.2"
+    "@tanstack/ai-skills": "^0.1.4"
   },
   "peerDependencies": {
     "@ngrok/ngrok": "^1.0.0",
     "vitest": "^4.1.10",
-    "@tanstack/ai": "^0.53.0",
-    "@tanstack/ai-persistence": "^0.5.6"
+    "@tanstack/ai": "^0.55.0",
+    "@tanstack/ai-persistence": "^0.6.0"
   },
   "peerDependenciesMeta": {
     "@ngrok/ngrok": {
@@ -79,8 +79,8 @@
     "@ngrok/ngrok": "^1.7.0",
     "@vitest/coverage-v8": "4.1.10",
     "vitest": "^4.1.10",
-    "@tanstack/ai": "0.53.0",
-    "@tanstack/ai-persistence": "0.5.6"
+    "@tanstack/ai-persistence": "0.6.0",
+    "@tanstack/ai": "0.55.0"
   },
   "scripts": {
     "build": "vite build",

package/skills/ai-sandbox/SKILL.md

@@ -48,9 +48,10 @@ agent CLI **inside** the sandbox and streams its events back.
 ## Setup — Claude Code in a Docker sandbox
 
 ```typescript
-import { chat } from '@tanstack/ai'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
 import { claudeCodeText } from '@tanstack/ai-claude-code'
 import {
+  createSecrets,
   defineSandbox,
   defineWorkspace,
   withSandbox,
@@ -65,17 +66,25 @@ const sandbox = defineSandbox({
     packageManager: 'pnpm',
     setup: ['corepack enable', 'pnpm install'],
     scripts: { test: 'pnpm test' },
-    secrets: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? '' },
+    secrets: createSecrets({
+      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)],
-})
+export async function POST(request: Request) {
+  const { threadId, messages } = await request.json()
+
+  const stream = chat({
+    threadId,
+    adapter: claudeCodeText('sonnet'),
+    messages,
+    middleware: [withSandbox(sandbox)],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 ## Type-safe secrets
@@ -165,6 +174,8 @@ serial and parallel groups over a **persistent shell** whose cwd/env carry over
 between serial steps:
 
 ```typescript
+import { githubRepo, defineWorkspace } from '@tanstack/ai-sandbox'
+
 defineWorkspace({
   source: githubRepo({ repo: 'owner/app' }),
   setup: ({ serial, parallel }) => {
@@ -183,10 +194,17 @@ When the provider supports snapshots, bootstrap takes one automatically after
 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
-}
+import { defineSandbox } from '@tanstack/ai-sandbox'
+import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+
+const sandbox = defineSandbox({
+  id: 'repo-agent',
+  provider: dockerSandbox({ image: 'node:22' }),
+  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.
@@ -199,8 +217,15 @@ middleware in this order, with the same persistence value in both places:
 
 ```typescript
 import { withPersistence } from '@tanstack/ai-persistence'
-import { memorySandboxSnapshots, withSandbox } from '@tanstack/ai-sandbox'
+import {
+  InMemorySandboxInstanceStore,
+  memorySandboxSnapshots,
+  withSandbox,
+} from '@tanstack/ai-sandbox'
+// Your `defineSandbox(...)` result.
+import { sandbox } from './sandbox'
 
+const instances = new InMemorySandboxInstanceStore()
 const snapshots = await memorySandboxSnapshots({ sandbox, instances })
 
 const middleware = [
@@ -321,20 +346,30 @@ distributed lock: either `withLocks` from `@tanstack/ai/locks` (ordered
 **before** `withSandbox`) or the `locks` option.
 
 ```typescript
-import { chat } from '@tanstack/ai'
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
 import { InMemoryLockStore, withLocks } from '@tanstack/ai/locks'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
 import { withSandbox } from '@tanstack/ai-sandbox'
+// Your `defineSandbox(...)` result.
+import { sandbox } from './sandbox'
 // Production: your BYO store — docs/sandbox/durability.md
 import { instanceStore } from './sandbox-instance-store'
 
-chat({
-  adapter,
-  messages,
-  middleware: [
-    withLocks(new InMemoryLockStore()), // multi-replica: distributed lock
-    withSandbox(sandbox, { instances: instanceStore }),
-  ],
-})
+export async function POST(request: Request) {
+  const { threadId, messages } = await request.json()
+
+  const stream = chat({
+    threadId,
+    adapter: claudeCodeText('sonnet'),
+    messages,
+    middleware: [
+      withLocks(new InMemoryLockStore()), // multi-replica: distributed lock
+      withSandbox(sandbox, { instances: instanceStore }),
+    ],
+  })
+
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 The store option takes precedence over an ambient `SandboxInstanceStoreCapability`
@@ -360,8 +395,11 @@ middleware via the `sandbox` group (run-scoped):
 import { defineSandbox, withSandbox } from '@tanstack/ai-sandbox'
 // `defineChatMiddleware` is core's, not this package's — `@tanstack/ai-sandbox`
 // consumes it too (see its own `src/middleware.ts`).
-import { defineChatMiddleware } from '@tanstack/ai'
+import { chat, defineChatMiddleware } from '@tanstack/ai'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
 import { dockerSandbox } from '@tanstack/ai-sandbox-docker'
+import { db } from './db'
+import { metrics } from './metrics'
 
 // Sandbox-scoped hooks (all optional):
 const sandbox = defineSandbox({
@@ -392,6 +430,13 @@ const auditMiddleware = defineChatMiddleware({
 
 // No extra middleware needed — sandbox.file CUSTOM events are emitted
 // automatically. Read them from the stream:
+const stream = chat({
+  threadId: 'thread-1',
+  adapter: claudeCodeText('sonnet'),
+  messages: [{ role: 'user', content: 'Add a README.' }],
+  middleware: [auditMiddleware, withSandbox(sandbox)],
+})
+
 for await (const chunk of stream) {
   if (chunk.type === 'CUSTOM' && chunk.name === 'sandbox.file') {
     const value = chunk.value
@@ -412,7 +457,10 @@ outside a `chat()` run:
 
 ```typescript
 import { watchWorkspace } from '@tanstack/ai-sandbox'
+// Your `defineSandbox(...)` result.
+import { sandbox } from './sandbox'
 
+const handle = await sandbox.ensure({ threadId: 'thread-1', runId: 'run-1' })
 const watcher = await watchWorkspace(handle, {
   onEvent: (e) => console.log(e.type, e.path),
   ignore: ['.git', 'node_modules'], // default
@@ -424,8 +472,24 @@ 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
+import { chat, toServerSentEventsResponse } from '@tanstack/ai'
+import { claudeCodeText } from '@tanstack/ai-claude-code'
+import { withSandbox } from '@tanstack/ai-sandbox'
+import { sandbox } from './sandbox'
+
+export async function POST(request: Request) {
+  const { threadId, messages } = await request.json()
+
+  const stream = chat({
+    threadId,
+    adapter: claudeCodeText('sonnet'),
+    messages,
+    middleware: [withSandbox(sandbox)],
+    debug: { sandbox: true }, // or debug: true to enable all categories
+  })
+
+  return toServerSentEventsResponse(stream)
+}
 ```
 
 ## Edge / serverless execution
@@ -551,12 +615,17 @@ file from byte 0 at any point, including after the original host has died.
 
 ```typescript
 import { spawnNdjson } from '@tanstack/ai-sandbox'
-
-for await (const event of spawnNdjson(sandbox, agentCommand, {
-  cwd,
-  journal: { runId }, // durability is opt-in: pass `journal` to route through it
-})) {
-  // parsed NDJSON objects, translated by the harness adapter as usual
+import type { SandboxHandle } from '@tanstack/ai-sandbox'
+
+export async function runAgent(handle: SandboxHandle, runId: string) {
+  const agentCommand = 'claude -p --output-format stream-json'
+  for await (const event of spawnNdjson(handle, agentCommand, {
+    cwd: '/workspace',
+    journal: { runId }, // durability is opt-in: pass `journal` to route through it
+  })) {
+    // parsed NDJSON objects, translated by the harness adapter as usual
+    console.log(event)
+  }
 }
 ```
 
@@ -1006,6 +1075,17 @@ import {
 } from '@tanstack/ai-sandbox'
 import type { RunRecord } from '@tanstack/ai'
 import type { ReapResult, RunExitProbe } from '@tanstack/ai-sandbox'
+// Your distributed LockStore, the same one `withSandbox` gets.
+import { locks } from './locks'
+// Your persistence — the SAME RunStore the chat routes use.
+import { runs } from './persistence'
+// Your `defineSandbox(...)` result and the `SandboxInstanceStore` you passed to
+// `withSandbox(sandbox, { instances })`.
+import { instances, sandbox } from './sandbox'
+// The per-run log factory, resolving the SAME log the producing route wrote.
+import { durabilityFor } from './durability'
+// The same `drive` the attach route passes to `sandboxRunDriver`.
+import { driveRun } from './drive-run'
 
 async function hasFinished(record: RunRecord): Promise<RunExitProbe> {
   if (record.sandboxKey === undefined) return { state: 'unknown' }

package/src/tool-bridge.ts

@@ -20,6 +20,7 @@
  */
 import { createServer } from 'node:http'
 import { randomBytes, timingSafeEqual } from 'node:crypto'
+import { once } from 'node:events'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
 import {
@@ -350,9 +351,7 @@ export async function startHostToolBridge(
     })
   })
 
-  await new Promise<void>((resolve) =>
-    httpServer.listen(0, bindAddress, resolve),
-  )
+  await once(httpServer.listen(0, bindAddress), 'listening')
   const port = (httpServer.address() as AddressInfo).port
   const url = `http://${options.hostForSandbox}:${port}/mcp`