@tanstack/ai-sandbox 0.2.4 → 0.3.0

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

@@ -1 +1 @@
-{"version":3,"file":"tool-bridge.js","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' ? 'host.docker.internal' : '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"],"names":[],"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 { 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' ? 'host.docker.internal' : '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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"}

package/dist/esm/tool-history.d.ts

@@ -0,0 +1,62 @@
+import { ModelMessage, StreamChunk } from '@tanstack/ai';
+/**
+ * What the recorder writes into. `ChatMiddlewareContext.messages` is a
+ * `ReadonlyArray`, so the transcript grows by REPLACING the array — the same way the
+ * engine itself syncs `middlewareCtx.messages`.
+ */
+interface TranscriptTarget {
+    messages: ReadonlyArray<ModelMessage>;
+}
+export interface ToolHistoryRecorder {
+    /** Feed every chunk. Observes only — never transforms or drops. */
+    observe: (chunk: StreamChunk, target: TranscriptTarget) => void;
+    /**
+     * Re-append anything missing from the transcript.
+     *
+     * The engine reassigns `middlewareCtx.messages` from its own array whenever it
+     * syncs config (once per agent iteration), which discards writes made during the
+     * previous iteration's stream. Reconciling at each iteration boundary and again at
+     * finish makes the result independent of that, and independent of where this
+     * middleware sits relative to persistence in the middleware array.
+     */
+    reconcile: (target: TranscriptTarget) => void;
+}
+/**
+ * True when this tool call was executed by the HARNESS inside the sandbox, and
+ * recorded into the transcript for display, rather than executed by the agent loop.
+ *
+ * Use it to decide what your own `MessageStore` keeps — these calls are display
+ * history, so dropping or capping them is safe (they are already stripped from the
+ * request to the model on the next turn). Also works on a `tool-call` UI part, whose
+ * `metadata` is copied straight from the model message.
+ *
+ * `metadata` is `unknown` on both, so the key can only be read behind a typeof/`in`
+ * check; this mirrors the core `isProviderExecutedToolCall` convention.
+ *
+ * ```ts
+ * import { isSandboxToolCall } from '@tanstack/ai-sandbox'
+ *
+ * const kept = messages.filter(
+ *   (message) => !message.toolCalls?.every(isSandboxToolCall),
+ * )
+ * ```
+ */
+export declare function isSandboxToolCall(toolCall: {
+    metadata?: unknown;
+} | null | undefined): boolean;
+export declare function createToolHistoryRecorder(): ToolHistoryRecorder;
+/**
+ * Drop recorded harness tool calls from a list of messages bound for the model.
+ *
+ * A stored transcript becomes the history for the NEXT turn. These calls name tools
+ * the provider was never given, and one triage-sized run is hundreds of kilobytes of
+ * tool output — so replaying them is wasteful at best and rejected at worst. They stay
+ * in `ctx.messages` (which is what gets stored and rendered); only the request to the
+ * model loses them.
+ *
+ * An assistant message is dropped only when EVERY call on it is observed, so a mixed
+ * message — one engine tool call plus one harness tool call — is left alone rather than
+ * silently losing the engine's half.
+ */
+export declare function stripObservedToolCalls(messages: ReadonlyArray<ModelMessage>): Array<ModelMessage>;
+export {};

package/dist/esm/tool-history.js

@@ -0,0 +1,171 @@
+import { EventType } from "@tanstack/ai";
+//#region src/tool-history.ts
+/**
+* Turn a harness's PASSTHROUGH tool-call chunks into transcript messages, so a
+* finished run's tool cards survive a reload.
+*
+* Why this is needed at all: a harness executes its tools INSIDE the sandbox, so
+* `chat()` only relays its `TOOL_CALL_*` chunks — it never writes an assistant
+* message for them (`addAssistantToolCallMessage` is gated on the engine having
+* executed the tool itself). Chat persistence stores `ctx.messages`, so the whole
+* tool history existed only in the delivery log. Replaying that log is what makes
+* "switch away and come back" show everything; a FINISHED thread has no run to
+* rejoin, hydrates from the message store instead, and so came back as nothing but
+* the prompt and the final answer.
+*
+* Recording the calls as ordinary `toolCalls` + `role: 'tool'` messages needs no new
+* wire format and no client change: `modelMessagesToUIMessages` already merges a tool
+* result into the call it belongs to and marks the part complete, and
+* `reconstructChat` already runs that converter.
+*/
+/**
+* Metadata key set on every tool call recorded here.
+*
+* INTERNAL, and deliberately not exported: an app asks {@link isSandboxToolCall}
+* instead of knowing the key. Renaming it is a storage-visible change, because it ends
+* up inside stored `toolCalls[].metadata`, so the recorder test pins the literal.
+*/
+var SANDBOX_OBSERVED = "sandboxObserved";
+/**
+* True when this tool call was executed by the HARNESS inside the sandbox, and
+* recorded into the transcript for display, rather than executed by the agent loop.
+*
+* Use it to decide what your own `MessageStore` keeps — these calls are display
+* history, so dropping or capping them is safe (they are already stripped from the
+* request to the model on the next turn). Also works on a `tool-call` UI part, whose
+* `metadata` is copied straight from the model message.
+*
+* `metadata` is `unknown` on both, so the key can only be read behind a typeof/`in`
+* check; this mirrors the core `isProviderExecutedToolCall` convention.
+*
+* ```ts
+* import { isSandboxToolCall } from '@tanstack/ai-sandbox'
+*
+* const kept = messages.filter(
+*   (message) => !message.toolCalls?.every(isSandboxToolCall),
+* )
+* ```
+*/
+function isSandboxToolCall(toolCall) {
+	const metadata = toolCall?.metadata;
+	return typeof metadata === "object" && metadata !== null && SANDBOX_OBSERVED in metadata && metadata[SANDBOX_OBSERVED] === true;
+}
+/** Does the transcript already carry this tool call, from any source? */
+function hasCall(messages, id) {
+	return messages.some((message) => message.toolCalls?.some((call) => call.id === id));
+}
+/** Does the transcript already carry this tool result? */
+function hasResult(messages, id) {
+	return messages.some((message) => message.role === "tool" && message.toolCallId === id);
+}
+function callMessage(id, name, args) {
+	return {
+		role: "assistant",
+		content: null,
+		toolCalls: [{
+			id,
+			type: "function",
+			function: {
+				name,
+				arguments: args
+			},
+			metadata: { [SANDBOX_OBSERVED]: true }
+		}]
+	};
+}
+function resultMessage(id, content) {
+	return {
+		role: "tool",
+		toolCallId: id,
+		content
+	};
+}
+function createToolHistoryRecorder() {
+	const open = /* @__PURE__ */ new Map();
+	/** Completed calls in the order they ran — the order `reconcile` restores. */
+	const recorded = [];
+	const results = /* @__PURE__ */ new Map();
+	function appendCall(target, id, name, args) {
+		if (hasCall(target.messages, id)) return;
+		target.messages = [...target.messages, callMessage(id, name, args)];
+	}
+	function appendResult(target, id, content) {
+		if (hasResult(target.messages, id)) return;
+		target.messages = [...target.messages, resultMessage(id, content)];
+	}
+	return {
+		observe(chunk, target) {
+			if (chunk.type === EventType.TOOL_CALL_START) {
+				const name = chunk.toolCallName ?? chunk.toolName;
+				if (!name) return;
+				open.set(chunk.toolCallId, {
+					name,
+					args: ""
+				});
+				return;
+			}
+			if (chunk.type === EventType.TOOL_CALL_ARGS) {
+				const call = open.get(chunk.toolCallId);
+				if (!call) return;
+				call.args = chunk.args ?? call.args + chunk.delta;
+				return;
+			}
+			if (chunk.type === EventType.TOOL_CALL_END) {
+				const call = open.get(chunk.toolCallId);
+				if (!call) return;
+				open.delete(chunk.toolCallId);
+				const args = chunk.input !== void 0 ? JSON.stringify(chunk.input) : call.args;
+				recorded.push({
+					id: chunk.toolCallId,
+					name: call.name,
+					args
+				});
+				appendCall(target, chunk.toolCallId, call.name, args);
+				return;
+			}
+			if (chunk.type === EventType.TOOL_CALL_RESULT) {
+				if (typeof chunk.content !== "string") return;
+				results.set(chunk.toolCallId, chunk.content);
+				appendResult(target, chunk.toolCallId, chunk.content);
+			}
+		},
+		reconcile(target) {
+			for (const { id, name, args } of recorded) {
+				appendCall(target, id, name, args);
+				const result = results.get(id);
+				if (result !== void 0) appendResult(target, id, result);
+			}
+		}
+	};
+}
+/**
+* Drop recorded harness tool calls from a list of messages bound for the model.
+*
+* A stored transcript becomes the history for the NEXT turn. These calls name tools
+* the provider was never given, and one triage-sized run is hundreds of kilobytes of
+* tool output — so replaying them is wasteful at best and rejected at worst. They stay
+* in `ctx.messages` (which is what gets stored and rendered); only the request to the
+* model loses them.
+*
+* An assistant message is dropped only when EVERY call on it is observed, so a mixed
+* message — one engine tool call plus one harness tool call — is left alone rather than
+* silently losing the engine's half.
+*/
+function stripObservedToolCalls(messages) {
+	const dropped = /* @__PURE__ */ new Set();
+	const kept = [];
+	for (const message of messages) {
+		const calls = message.toolCalls;
+		if (calls && calls.length > 0 && calls.every(isSandboxToolCall)) {
+			for (const call of calls) dropped.add(call.id);
+			continue;
+		}
+		if (message.role === "tool" && message.toolCallId !== void 0 && dropped.has(message.toolCallId)) continue;
+		kept.push(message);
+	}
+	return kept;
+}
+//#endregion
+export { createToolHistoryRecorder, isSandboxToolCall, stripObservedToolCalls };
+
+//# sourceMappingURL=tool-history.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tool-history.js","names":[],"sources":["../../src/tool-history.ts"],"sourcesContent":["/**\n * Turn a harness's PASSTHROUGH tool-call chunks into transcript messages, so a\n * finished run's tool cards survive a reload.\n *\n * Why this is needed at all: a harness executes its tools INSIDE the sandbox, so\n * `chat()` only relays its `TOOL_CALL_*` chunks — it never writes an assistant\n * message for them (`addAssistantToolCallMessage` is gated on the engine having\n * executed the tool itself). Chat persistence stores `ctx.messages`, so the whole\n * tool history existed only in the delivery log. Replaying that log is what makes\n * \"switch away and come back\" show everything; a FINISHED thread has no run to\n * rejoin, hydrates from the message store instead, and so came back as nothing but\n * the prompt and the final answer.\n *\n * Recording the calls as ordinary `toolCalls` + `role: 'tool'` messages needs no new\n * wire format and no client change: `modelMessagesToUIMessages` already merges a tool\n * result into the call it belongs to and marks the part complete, and\n * `reconstructChat` already runs that converter.\n */\nimport { EventType } from '@tanstack/ai'\nimport type { ModelMessage, StreamChunk } from '@tanstack/ai'\n\n/**\n * Metadata key set on every tool call recorded here.\n *\n * INTERNAL, and deliberately not exported: an app asks {@link isSandboxToolCall}\n * instead of knowing the key. Renaming it is a storage-visible change, because it ends\n * up inside stored `toolCalls[].metadata`, so the recorder test pins the literal.\n */\nconst SANDBOX_OBSERVED = 'sandboxObserved'\n\n/**\n * What the recorder writes into. `ChatMiddlewareContext.messages` is a\n * `ReadonlyArray`, so the transcript grows by REPLACING the array — the same way the\n * engine itself syncs `middlewareCtx.messages`.\n */\ninterface TranscriptTarget {\n  messages: ReadonlyArray<ModelMessage>\n}\n\ninterface OpenCall {\n  name: string\n  /** Accumulated `TOOL_CALL_ARGS` deltas; superseded by `input` when the adapter sends it. */\n  args: string\n}\n\nexport interface ToolHistoryRecorder {\n  /** Feed every chunk. Observes only — never transforms or drops. */\n  observe: (chunk: StreamChunk, target: TranscriptTarget) => void\n  /**\n   * Re-append anything missing from the transcript.\n   *\n   * The engine reassigns `middlewareCtx.messages` from its own array whenever it\n   * syncs config (once per agent iteration), which discards writes made during the\n   * previous iteration's stream. Reconciling at each iteration boundary and again at\n   * finish makes the result independent of that, and independent of where this\n   * middleware sits relative to persistence in the middleware array.\n   */\n  reconcile: (target: TranscriptTarget) => void\n}\n\n/**\n * True when this tool call was executed by the HARNESS inside the sandbox, and\n * recorded into the transcript for display, rather than executed by the agent loop.\n *\n * Use it to decide what your own `MessageStore` keeps — these calls are display\n * history, so dropping or capping them is safe (they are already stripped from the\n * request to the model on the next turn). Also works on a `tool-call` UI part, whose\n * `metadata` is copied straight from the model message.\n *\n * `metadata` is `unknown` on both, so the key can only be read behind a typeof/`in`\n * check; this mirrors the core `isProviderExecutedToolCall` convention.\n *\n * ```ts\n * import { isSandboxToolCall } from '@tanstack/ai-sandbox'\n *\n * const kept = messages.filter(\n *   (message) => !message.toolCalls?.every(isSandboxToolCall),\n * )\n * ```\n */\nexport function isSandboxToolCall(\n  toolCall: { metadata?: unknown } | null | undefined,\n): boolean {\n  const metadata = toolCall?.metadata\n  return (\n    typeof metadata === 'object' &&\n    metadata !== null &&\n    SANDBOX_OBSERVED in metadata &&\n    metadata[SANDBOX_OBSERVED] === true\n  )\n}\n\n/** Does the transcript already carry this tool call, from any source? */\nfunction hasCall(messages: ReadonlyArray<ModelMessage>, id: string): boolean {\n  return messages.some((message) =>\n    message.toolCalls?.some((call) => call.id === id),\n  )\n}\n\n/** Does the transcript already carry this tool result? */\nfunction hasResult(messages: ReadonlyArray<ModelMessage>, id: string): boolean {\n  return messages.some(\n    (message) => message.role === 'tool' && message.toolCallId === id,\n  )\n}\n\nfunction callMessage(id: string, name: string, args: string): ModelMessage {\n  return {\n    role: 'assistant',\n    content: null,\n    toolCalls: [\n      {\n        id,\n        type: 'function',\n        function: { name, arguments: args },\n        metadata: { [SANDBOX_OBSERVED]: true },\n      },\n    ],\n  }\n}\n\nfunction resultMessage(id: string, content: string): ModelMessage {\n  return { role: 'tool', toolCallId: id, content }\n}\n\nexport function createToolHistoryRecorder(): ToolHistoryRecorder {\n  const open = new Map<string, OpenCall>()\n  /** Completed calls in the order they ran — the order `reconcile` restores. */\n  const recorded: Array<{ id: string; name: string; args: string }> = []\n  const results = new Map<string, string>()\n\n  function appendCall(\n    target: TranscriptTarget,\n    id: string,\n    name: string,\n    args: string,\n  ): void {\n    // An id already present is either the engine's own (it executed the tool itself)\n    // or a chunk seen before — a journal replay on takeover re-emits the whole\n    // stream. Either way a second write would duplicate the card.\n    if (hasCall(target.messages, id)) return\n    target.messages = [...target.messages, callMessage(id, name, args)]\n  }\n\n  function appendResult(\n    target: TranscriptTarget,\n    id: string,\n    content: string,\n  ): void {\n    if (hasResult(target.messages, id)) return\n    target.messages = [...target.messages, resultMessage(id, content)]\n  }\n\n  const recorder: ToolHistoryRecorder = {\n    // An if/else chain rather than a `switch`: only four of the ~20 chunk types are\n    // interesting here, and a `switch` on `chunk.type` has to enumerate all of them\n    // to satisfy the exhaustiveness lint.\n    observe(chunk, target) {\n      if (chunk.type === EventType.TOOL_CALL_START) {\n        // `toolCallName` is the AG-UI field; `toolName` is its deprecated alias, and\n        // that alias is what several harness adapters still emit.\n        const name = chunk.toolCallName ?? chunk.toolName\n        if (!name) return\n        open.set(chunk.toolCallId, { name, args: '' })\n        return\n      }\n      if (chunk.type === EventType.TOOL_CALL_ARGS) {\n        const call = open.get(chunk.toolCallId)\n        if (!call) return\n        // `args` is the accumulated-so-far field. Prefer it over stitching deltas:\n        // an adapter that sends both would otherwise double the arguments.\n        call.args = chunk.args ?? call.args + chunk.delta\n        return\n      }\n      if (chunk.type === EventType.TOOL_CALL_END) {\n        const call = open.get(chunk.toolCallId)\n        if (!call) return\n        open.delete(chunk.toolCallId)\n        // `input` is the final PARSED input, so it beats the streamed string, which\n        // can be a truncated fragment if the arguments stream was cut short.\n        const args =\n          chunk.input !== undefined ? JSON.stringify(chunk.input) : call.args\n        recorded.push({ id: chunk.toolCallId, name: call.name, args })\n        appendCall(target, chunk.toolCallId, call.name, args)\n        return\n      }\n      if (chunk.type === EventType.TOOL_CALL_RESULT) {\n        // AG-UI types `content` as a string; anything else is not a result we can\n        // store as a `role: 'tool'` message.\n        if (typeof chunk.content !== 'string') return\n        results.set(chunk.toolCallId, chunk.content)\n        appendResult(target, chunk.toolCallId, chunk.content)\n      }\n    },\n\n    reconcile(target) {\n      for (const { id, name, args } of recorded) {\n        appendCall(target, id, name, args)\n        const result = results.get(id)\n        // The result goes straight after its own call, so a restored transcript reads\n        // in the order the tools actually ran.\n        if (result !== undefined) appendResult(target, id, result)\n      }\n    },\n  }\n  return recorder\n}\n\n/**\n * Drop recorded harness tool calls from a list of messages bound for the model.\n *\n * A stored transcript becomes the history for the NEXT turn. These calls name tools\n * the provider was never given, and one triage-sized run is hundreds of kilobytes of\n * tool output — so replaying them is wasteful at best and rejected at worst. They stay\n * in `ctx.messages` (which is what gets stored and rendered); only the request to the\n * model loses them.\n *\n * An assistant message is dropped only when EVERY call on it is observed, so a mixed\n * message — one engine tool call plus one harness tool call — is left alone rather than\n * silently losing the engine's half.\n */\nexport function stripObservedToolCalls(\n  messages: ReadonlyArray<ModelMessage>,\n): Array<ModelMessage> {\n  const dropped = new Set<string>()\n  const kept: Array<ModelMessage> = []\n  for (const message of messages) {\n    const calls = message.toolCalls\n    if (calls && calls.length > 0 && calls.every(isSandboxToolCall)) {\n      for (const call of calls) dropped.add(call.id)\n      continue\n    }\n    // Orphaning a result is worse than keeping it: a provider rejects a tool result\n    // whose call is not in the history.\n    if (\n      message.role === 'tool' &&\n      message.toolCallId !== undefined &&\n      dropped.has(message.toolCallId)\n    ) {\n      continue\n    }\n    kept.push(message)\n  }\n  return kept\n}\n"],"mappings":"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"}