@tanstack/ai-sandbox-cloudflare 0.1.0

package/dist/esm/agent.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `@tanstack/ai-sandbox-cloudflare/agent` — the Workers-runtime building blocks
+ * for running a TanStack AI sandbox agent on Cloudflare with minimal app code.
+ *
+ * The headline API is {@link createCloudflareSandboxAgent}: one configured
+ * function call returns the Durable Object coordinator + the Sandbox DO + the
+ * Worker fetch handler, so an app's `worker.ts` is just export wiring. The
+ * coordinator base classes, the concrete coordinators, the Worker factory, and
+ * the durable run-log are exported too for apps that want to compose them
+ * directly.
+ *
+ * This entry imports `cloudflare:workers` and is Workers-only — keep it out of
+ * the node-importable main entry (`@tanstack/ai-sandbox-cloudflare`).
+ */
+export { createCloudflareSandboxAgent } from './factory.js';
+export type { CloudflareSandboxAgent, CloudflareSandboxAgentConfig, DoDrivesAgentConfig, ColocatedAgentConfig, SandboxAgentEnv, } from './factory.js';
+export { SandboxCoordinator, resolveBridgeOrigin, resolvePreviewHost, } from './coordinator.js';
+export type { StartRunInput } from './coordinator.js';
+export { exposePreviewTool, PREVIEW_GUIDANCE } from './preview-tool.js';
+export type { PreviewToolEnv } from './preview-tool.js';
+export { ChatSandboxCoordinator } from './chat-coordinator.js';
+export type { ChatCoordinatorEnv, ChatRunConfig } from './chat-coordinator.js';
+export { ContainerSandboxCoordinator } from './container-coordinator.js';
+export type { ContainerCoordinatorEnv, ContainerRunConfig, } from './container-coordinator.js';
+export { parseContainerRunRequest } from './protocol.js';
+export type { ContainerRunRequest, HarnessId } from './protocol.js';
+export { createSandboxAgentWorker } from './worker.js';
+export type { ResolveCoordinator } from './worker.js';
+export { DurableObjectRunEventLog } from './run-log-do.js';
+export { timingSafeBearerEqualWeb } from './web-crypto.js';

package/dist/esm/agent.js

@@ -0,0 +1,25 @@
+import { createCloudflareSandboxAgent } from "./factory.js";
+import { SandboxCoordinator } from "./coordinator.js";
+import { PREVIEW_GUIDANCE, exposePreviewTool } from "./preview-tool.js";
+import { ChatSandboxCoordinator } from "./chat-coordinator.js";
+import { ContainerSandboxCoordinator } from "./container-coordinator.js";
+import { parseContainerRunRequest } from "./protocol.js";
+import { createSandboxAgentWorker } from "./worker.js";
+import { DurableObjectRunEventLog } from "./run-log-do.js";
+import { timingSafeBearerEqualWeb } from "./web-crypto.js";
+import { resolveBridgeOrigin, resolvePreviewHost } from "./public-host.js";
+export {
+  ChatSandboxCoordinator,
+  ContainerSandboxCoordinator,
+  DurableObjectRunEventLog,
+  PREVIEW_GUIDANCE,
+  SandboxCoordinator,
+  createCloudflareSandboxAgent,
+  createSandboxAgentWorker,
+  exposePreviewTool,
+  parseContainerRunRequest,
+  resolveBridgeOrigin,
+  resolvePreviewHost,
+  timingSafeBearerEqualWeb
+};
+//# sourceMappingURL=agent.js.map

package/dist/esm/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}

package/dist/esm/chat-coordinator.d.ts

@@ -0,0 +1,75 @@
+import { SandboxCoordinator, StartRunInput } from './coordinator.js';
+import { AnyTextAdapter, AnyTool, StreamChunk, SystemPrompt } from '@tanstack/ai';
+import { SandboxDefinition } from '@tanstack/ai-sandbox';
+/**
+ * The Env bindings a {@link ChatSandboxCoordinator} requires. The bridge origin the
+ * SANDBOX calls back on needs a hostname; `PUBLIC_HOSTNAME` is OPTIONAL — when
+ * unset, the coordinator derives it from the trigger request (locally →
+ * `host.docker.internal`; safe on Cloudflare). See {@link resolveBridgeOrigin}.
+ */
+export interface ChatCoordinatorEnv {
+    /**
+     * Hostname the CONTAINER uses to reach the Worker's tool-bridge (`/_bridge`).
+     * Optional: unset → derived from each trigger request (deployed: the request
+     * host; local dev: `host.docker.internal`). Set it only to override — e.g. a
+     * stable named-tunnel host. See {@link resolveBridgeOrigin}. (Browser-facing
+     * preview URLs use a separate `PREVIEW_HOSTNAME`; see {@link resolvePreviewHost}.)
+     */
+    PUBLIC_HOSTNAME?: string;
+}
+/** What {@link ChatSandboxCoordinator.config} returns for one run. */
+export interface ChatRunConfig {
+    /** The harness/text adapter `chat()` runs (e.g. `claudeCodeText('sonnet')`). */
+    adapter: AnyTextAdapter;
+    /** The sandbox the agent executes in, projected by `withSandbox`. */
+    sandbox: SandboxDefinition;
+    /** chat()-provided server tools bridged into the harness over MCP. */
+    tools?: Array<AnyTool>;
+    /** Base system prompts prepended to the run's `chat()` (e.g. `[PREVIEW_GUIDANCE]`). */
+    systemPrompts?: Array<SystemPrompt>;
+}
+export declare abstract class ChatSandboxCoordinator<TEnv extends ChatCoordinatorEnv = ChatCoordinatorEnv> extends SandboxCoordinator<TEnv> {
+    /**
+     * Live per-run bridges, keyed by runId. In-memory by design: a bridge is only
+     * reachable while its run is in flight, and `ctx.waitUntil(done)` keeps THIS
+     * instance alive (un-hibernated) for the run's whole lifetime — so the agent's
+     * MCP calls always hit the instance that provisioned the bridge. A request for
+     * a run with no live bridge (finished, or never started here) is a hard 404,
+     * not a silent re-provision.
+     */
+    private readonly bridges;
+    /**
+     * Resolve the adapter, sandbox, and chat()-tools for one run. Implemented by
+     * the app subclass (or supplied by {@link createCloudflareSandboxAgent}); this
+     * is the only model-specific input the DO-drives coordinator needs.
+     */
+    protected abstract config(input: StartRunInput): ChatRunConfig;
+    /**
+     * Run `chat()` IN the DO, streaming its `StreamChunk`s. `stream: true` (with no
+     * outputSchema) makes chat() return an `AsyncIterable<StreamChunk>` directly —
+     * no cast needed for the run driver. Both middlewares run `setup` before
+     * streaming begins: our middleware provides the DO-backed bridge provisioner,
+     * and `withSandbox` provides the sandbox handle the harness adapter needs.
+     */
+    protected buildRunStream(input: StartRunInput): AsyncIterable<StreamChunk>;
+    /** Drop the per-run bridge once the run is terminal (override from base). */
+    protected onRunSettled(runId: string): void;
+    /**
+     * A tiny middleware that PROVIDES our DO-backed {@link ToolBridgeProvisioner}.
+     * The harness adapter reads it via `getOptional` and falls back to the
+     * `node:http` host transport when absent — here we override that so the bridge
+     * is served from this DO's `fetch` handler instead of a TCP listener.
+     */
+    private bridgeProvisionerMiddleware;
+    /**
+     * Stand up the per-run bridge: register the tool core + a fresh bearer token
+     * on this DO, and hand back a URL the SANDBOX can reach — the Worker's public
+     * hostname routed to `/_bridge/:runId`. The `threadId` query lets the Worker
+     * route the agent's MCP calls back to THIS coordinator. No raw socket is opened.
+     */
+    private makeBridgeProvisioner;
+    /** Serve `/_bridge/:runId` (the in-sandbox agent's MCP calls) from the base fetch. */
+    protected handleRoute(request: Request, parts: Array<string>): Promise<Response> | Response;
+    /** Serve one MCP JSON-RPC request for a run after a constant-time token check. */
+    private serveBridge;
+}

package/dist/esm/chat-coordinator.js

@@ -0,0 +1,135 @@
+import { chat, defineChatMiddleware } from "@tanstack/ai";
+import { withSandbox, ToolBridgeProvisionerCapability, createToolBridgeCore, handleBridgeJsonRpc } from "@tanstack/ai-sandbox";
+import { SandboxCoordinator } from "./coordinator.js";
+import { timingSafeBearerEqualWeb } from "./web-crypto.js";
+import { resolveBridgeOrigin } from "./public-host.js";
+class ChatSandboxCoordinator extends SandboxCoordinator {
+  /**
+   * Live per-run bridges, keyed by runId. In-memory by design: a bridge is only
+   * reachable while its run is in flight, and `ctx.waitUntil(done)` keeps THIS
+   * instance alive (un-hibernated) for the run's whole lifetime — so the agent's
+   * MCP calls always hit the instance that provisioned the bridge. A request for
+   * a run with no live bridge (finished, or never started here) is a hard 404,
+   * not a silent re-provision.
+   */
+  bridges = /* @__PURE__ */ new Map();
+  // ===========================================================================
+  // The one per-model seam: run chat() in the DO
+  // ===========================================================================
+  /**
+   * Run `chat()` IN the DO, streaming its `StreamChunk`s. `stream: true` (with no
+   * outputSchema) makes chat() return an `AsyncIterable<StreamChunk>` directly —
+   * no cast needed for the run driver. Both middlewares run `setup` before
+   * streaming begins: our middleware provides the DO-backed bridge provisioner,
+   * and `withSandbox` provides the sandbox handle the harness adapter needs.
+   */
+  buildRunStream(input) {
+    const { adapter, sandbox, tools, systemPrompts } = this.config(input);
+    const sessionId = input.metadata?.sessionId;
+    const modelOptions = typeof sessionId === "string" && sessionId !== "" ? { sessionId } : void 0;
+    return chat({
+      threadId: input.threadId,
+      adapter,
+      messages: input.messages,
+      stream: true,
+      ...tools !== void 0 ? { tools } : {},
+      ...systemPrompts !== void 0 ? { systemPrompts } : {},
+      ...modelOptions !== void 0 ? { modelOptions } : {},
+      middleware: [
+        this.bridgeProvisionerMiddleware(input),
+        withSandbox(sandbox)
+      ]
+    });
+  }
+  /** Drop the per-run bridge once the run is terminal (override from base). */
+  onRunSettled(runId) {
+    this.bridges.delete(runId);
+  }
+  // ===========================================================================
+  // The DO-backed tool-bridge provisioner + endpoint
+  // ===========================================================================
+  /**
+   * A tiny middleware that PROVIDES our DO-backed {@link ToolBridgeProvisioner}.
+   * The harness adapter reads it via `getOptional` and falls back to the
+   * `node:http` host transport when absent — here we override that so the bridge
+   * is served from this DO's `fetch` handler instead of a TCP listener.
+   */
+  bridgeProvisionerMiddleware(input) {
+    const provisioner = this.makeBridgeProvisioner(input);
+    return defineChatMiddleware({
+      name: "do-tool-bridge-provisioner",
+      provides: [ToolBridgeProvisionerCapability],
+      setup: (ctx) => {
+        ctx.provide(ToolBridgeProvisionerCapability, provisioner);
+      }
+    });
+  }
+  /**
+   * Stand up the per-run bridge: register the tool core + a fresh bearer token
+   * on this DO, and hand back a URL the SANDBOX can reach — the Worker's public
+   * hostname routed to `/_bridge/:runId`. The `threadId` query lets the Worker
+   * route the agent's MCP calls back to THIS coordinator. No raw socket is opened.
+   */
+  makeBridgeProvisioner(input) {
+    const env = this.env;
+    const bridges = this.bridges;
+    const { runId, threadId } = input;
+    const origin = resolveBridgeOrigin(env, input);
+    return {
+      provision(tools, options) {
+        const token = crypto.randomUUID() + crypto.randomUUID().replace(/-/g, "");
+        const core = createToolBridgeCore(tools, {
+          ...options.context !== void 0 ? { context: options.context } : {},
+          ...options.signal !== void 0 ? { signal: options.signal } : {},
+          ...options.permission !== void 0 ? { permission: options.permission } : {}
+        });
+        bridges.set(runId, { token, core });
+        return Promise.resolve({
+          name: "tanstack",
+          url: `${origin}/_bridge/${runId}?threadId=${encodeURIComponent(threadId)}`,
+          token,
+          close: () => {
+            bridges.delete(runId);
+            return Promise.resolve();
+          }
+        });
+      }
+    };
+  }
+  /** Serve `/_bridge/:runId` (the in-sandbox agent's MCP calls) from the base fetch. */
+  handleRoute(request, parts) {
+    if (parts[0] === "_bridge" && typeof parts[1] === "string") {
+      return this.serveBridge(parts[1], request);
+    }
+    return super.handleRoute(request, parts);
+  }
+  /** Serve one MCP JSON-RPC request for a run after a constant-time token check. */
+  async serveBridge(runId, request) {
+    const bridge = this.bridges.get(runId);
+    if (!bridge)
+      return new Response("no active bridge for run", { status: 404 });
+    if (!timingSafeBearerEqualWeb(
+      request.headers.get("authorization") ?? void 0,
+      bridge.token
+    )) {
+      return new Response("unauthorized", { status: 401 });
+    }
+    let message;
+    try {
+      message = await request.json();
+    } catch {
+      return this.jsonResponse({
+        jsonrpc: "2.0",
+        id: null,
+        error: { code: -32700, message: "Parse error" }
+      });
+    }
+    const reply = await handleBridgeJsonRpc(bridge.core, message);
+    if (reply === null) return new Response(null, { status: 202 });
+    return this.jsonResponse(reply);
+  }
+}
+export {
+  ChatSandboxCoordinator
+};
+//# sourceMappingURL=chat-coordinator.js.map

package/dist/esm/chat-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-coordinator.js","sources":["../../src/chat-coordinator.ts"],"sourcesContent":["/**\n * `ChatSandboxCoordinator` — the concrete {@link SandboxCoordinator} for the\n * DO-DRIVES model: the Durable Object runs `chat()` ITSELF and hosts the MCP\n * tool-bridge from its own `fetch` handler.\n *\n *     Worker (stateless trigger)\n *        → ChatSandboxCoordinator (this DO: runs chat(), owns the sandbox + log)\n *           → Cloudflare Sandbox (the container the agent executes in)\n *\n * It implements the one per-model seam, {@link buildRunStream}, by running\n * `chat()` in the DO with two middlewares: our DO-backed tool-bridge provisioner\n * (so the bridge is served from this DO instead of a `node:http` listener) and\n * `withSandbox(...)` (the handle the harness adapter needs). The per-run config —\n * which adapter, which sandbox, which chat()-tools — is the subclass's\n * {@link config} method; everything else (run-log, streaming tail, watchdog) is\n * inherited from the base.\n *\n * The MCP tool-bridge lives at `/_bridge/:runId`, gated by a per-run bearer\n * token, served from {@link handleRoute}. The in-sandbox agent reaches it via\n * the Worker's public hostname.\n *\n * NOTE: Workers-runtime code — compiles against the real Cloudflare + TanStack\n * AI types; not runtime-verified in this repo (no Workers runtime here).\n */\nimport { chat, defineChatMiddleware } from '@tanstack/ai'\nimport {\n  ToolBridgeProvisionerCapability,\n  createToolBridgeCore,\n  handleBridgeJsonRpc,\n  withSandbox,\n} from '@tanstack/ai-sandbox'\nimport { SandboxCoordinator, resolveBridgeOrigin } from './coordinator'\nimport { timingSafeBearerEqualWeb } from './web-crypto'\nimport type { StartRunInput } from './coordinator'\nimport type {\n  AnyTextAdapter,\n  AnyTool,\n  StreamChunk,\n  SystemPrompt,\n} from '@tanstack/ai'\nimport type {\n  ProvisionedBridge,\n  SandboxDefinition,\n  ToolBridgeCore,\n  ToolBridgeProvisioner,\n} from '@tanstack/ai-sandbox'\n\n/**\n * The Env bindings a {@link ChatSandboxCoordinator} requires. The bridge origin the\n * SANDBOX calls back on needs a hostname; `PUBLIC_HOSTNAME` is OPTIONAL — when\n * unset, the coordinator derives it from the trigger request (locally →\n * `host.docker.internal`; safe on Cloudflare). See {@link resolveBridgeOrigin}.\n */\nexport interface ChatCoordinatorEnv {\n  /**\n   * Hostname the CONTAINER uses to reach the Worker's tool-bridge (`/_bridge`).\n   * Optional: unset → derived from each trigger request (deployed: the request\n   * host; local dev: `host.docker.internal`). Set it only to override — e.g. a\n   * stable named-tunnel host. See {@link resolveBridgeOrigin}. (Browser-facing\n   * preview URLs use a separate `PREVIEW_HOSTNAME`; see {@link resolvePreviewHost}.)\n   */\n  PUBLIC_HOSTNAME?: string\n}\n\n/** What {@link ChatSandboxCoordinator.config} returns for one run. */\nexport interface ChatRunConfig {\n  /** The harness/text adapter `chat()` runs (e.g. `claudeCodeText('sonnet')`). */\n  adapter: AnyTextAdapter\n  /** The sandbox the agent executes in, projected by `withSandbox`. */\n  sandbox: SandboxDefinition\n  /** chat()-provided server tools bridged into the harness over MCP. */\n  tools?: Array<AnyTool>\n  /** Base system prompts prepended to the run's `chat()` (e.g. `[PREVIEW_GUIDANCE]`). */\n  systemPrompts?: Array<SystemPrompt>\n}\n\n/** Per-run bridge state so `/_bridge/:runId` can authenticate + serve. */\ninterface BridgeState {\n  token: string\n  core: ToolBridgeCore\n}\n\nexport abstract class ChatSandboxCoordinator<\n  TEnv extends ChatCoordinatorEnv = ChatCoordinatorEnv,\n> extends SandboxCoordinator<TEnv> {\n  /**\n   * Live per-run bridges, keyed by runId. In-memory by design: a bridge is only\n   * reachable while its run is in flight, and `ctx.waitUntil(done)` keeps THIS\n   * instance alive (un-hibernated) for the run's whole lifetime — so the agent's\n   * MCP calls always hit the instance that provisioned the bridge. A request for\n   * a run with no live bridge (finished, or never started here) is a hard 404,\n   * not a silent re-provision.\n   */\n  private readonly bridges = new Map<string, BridgeState>()\n\n  // ===========================================================================\n  // Subclass seam: the per-run configuration\n  // ===========================================================================\n\n  /**\n   * Resolve the adapter, sandbox, and chat()-tools for one run. Implemented by\n   * the app subclass (or supplied by {@link createCloudflareSandboxAgent}); this\n   * is the only model-specific input the DO-drives coordinator needs.\n   */\n  protected abstract config(input: StartRunInput): ChatRunConfig\n\n  // ===========================================================================\n  // The one per-model seam: run chat() in the DO\n  // ===========================================================================\n\n  /**\n   * Run `chat()` IN the DO, streaming its `StreamChunk`s. `stream: true` (with no\n   * outputSchema) makes chat() return an `AsyncIterable<StreamChunk>` directly —\n   * no cast needed for the run driver. Both middlewares run `setup` before\n   * streaming begins: our middleware provides the DO-backed bridge provisioner,\n   * and `withSandbox` provides the sandbox handle the harness adapter needs.\n   */\n  protected override buildRunStream(\n    input: StartRunInput,\n  ): AsyncIterable<StreamChunk> {\n    const { adapter, sandbox, tools, systemPrompts } = this.config(input)\n    const sessionId = input.metadata?.sessionId\n    const modelOptions =\n      typeof sessionId === 'string' && sessionId !== ''\n        ? { sessionId }\n        : undefined\n    return chat({\n      threadId: input.threadId,\n      adapter,\n      messages: input.messages,\n      stream: true,\n      ...(tools !== undefined ? { tools } : {}),\n      ...(systemPrompts !== undefined ? { systemPrompts } : {}),\n      ...(modelOptions !== undefined ? { modelOptions } : {}),\n      middleware: [\n        this.bridgeProvisionerMiddleware(input),\n        withSandbox(sandbox),\n      ],\n    })\n  }\n\n  /** Drop the per-run bridge once the run is terminal (override from base). */\n  protected override onRunSettled(runId: string): void {\n    this.bridges.delete(runId)\n  }\n\n  // ===========================================================================\n  // The DO-backed tool-bridge provisioner + endpoint\n  // ===========================================================================\n\n  /**\n   * A tiny middleware that PROVIDES our DO-backed {@link ToolBridgeProvisioner}.\n   * The harness adapter reads it via `getOptional` and falls back to the\n   * `node:http` host transport when absent — here we override that so the bridge\n   * is served from this DO's `fetch` handler instead of a TCP listener.\n   */\n  private bridgeProvisionerMiddleware(input: StartRunInput) {\n    const provisioner = this.makeBridgeProvisioner(input)\n    return defineChatMiddleware({\n      name: 'do-tool-bridge-provisioner',\n      provides: [ToolBridgeProvisionerCapability],\n      setup: (ctx) => {\n        ctx.provide(ToolBridgeProvisionerCapability, provisioner)\n      },\n    })\n  }\n\n  /**\n   * Stand up the per-run bridge: register the tool core + a fresh bearer token\n   * on this DO, and hand back a URL the SANDBOX can reach — the Worker's public\n   * hostname routed to `/_bridge/:runId`. The `threadId` query lets the Worker\n   * route the agent's MCP calls back to THIS coordinator. No raw socket is opened.\n   */\n  private makeBridgeProvisioner(input: StartRunInput): ToolBridgeProvisioner {\n    const env = this.env\n    const bridges = this.bridges\n    const { runId, threadId } = input\n    // Container→Worker origin: `PUBLIC_HOSTNAME` if set, else derived from the\n    // trigger request (locally → host.docker.internal). The bearer token rides\n    // this URL. See `resolveBridgeOrigin`.\n    const origin = resolveBridgeOrigin(env, input)\n    return {\n      provision(tools, options): Promise<ProvisionedBridge> {\n        const token =\n          crypto.randomUUID() + crypto.randomUUID().replace(/-/g, '')\n        const core = createToolBridgeCore(tools, {\n          ...(options.context !== undefined\n            ? { context: options.context }\n            : {}),\n          ...(options.signal !== undefined ? { signal: options.signal } : {}),\n          ...(options.permission !== undefined\n            ? { permission: options.permission }\n            : {}),\n        })\n        bridges.set(runId, { token, core })\n        return Promise.resolve({\n          name: 'tanstack',\n          url: `${origin}/_bridge/${runId}?threadId=${encodeURIComponent(threadId)}`,\n          token,\n          close: () => {\n            bridges.delete(runId)\n            return Promise.resolve()\n          },\n        })\n      },\n    }\n  }\n\n  /** Serve `/_bridge/:runId` (the in-sandbox agent's MCP calls) from the base fetch. */\n  protected override handleRoute(\n    request: Request,\n    parts: Array<string>,\n  ): Promise<Response> | Response {\n    if (parts[0] === '_bridge' && typeof parts[1] === 'string') {\n      return this.serveBridge(parts[1], request)\n    }\n    return super.handleRoute(request, parts)\n  }\n\n  /** Serve one MCP JSON-RPC request for a run after a constant-time token check. */\n  private async serveBridge(\n    runId: string,\n    request: Request,\n  ): Promise<Response> {\n    const bridge = this.bridges.get(runId)\n    if (!bridge)\n      return new Response('no active bridge for run', { status: 404 })\n    if (\n      !timingSafeBearerEqualWeb(\n        request.headers.get('authorization') ?? undefined,\n        bridge.token,\n      )\n    ) {\n      return new Response('unauthorized', { status: 401 })\n    }\n    let message: unknown\n    try {\n      message = await request.json()\n    } catch {\n      // A malformed body must still produce a valid JSON-RPC error so the agent's\n      // MCP client can react, rather than an opaque DO 500 that can wedge the run.\n      return this.jsonResponse({\n        jsonrpc: '2.0',\n        id: null,\n        error: { code: -32700, message: 'Parse error' },\n      })\n    }\n    const reply = await handleBridgeJsonRpc(bridge.core, message)\n    // A notification (no id) yields null → MCP expects an empty 202 ack.\n    if (reply === null) return new Response(null, { status: 202 })\n    return this.jsonResponse(reply)\n  }\n}\n"],"names":[],"mappings":";;;;;AAkFO,MAAe,+BAEZ,mBAAyB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAShB,8BAAc,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAwBZ,eACjB,OAC4B;AAC5B,UAAM,EAAE,SAAS,SAAS,OAAO,kBAAkB,KAAK,OAAO,KAAK;AACpE,UAAM,YAAY,MAAM,UAAU;AAClC,UAAM,eACJ,OAAO,cAAc,YAAY,cAAc,KAC3C,EAAE,cACF;AACN,WAAO,KAAK;AAAA,MACV,UAAU,MAAM;AAAA,MAChB;AAAA,MACA,UAAU,MAAM;AAAA,MAChB,QAAQ;AAAA,MACR,GAAI,UAAU,SAAY,EAAE,MAAA,IAAU,CAAA;AAAA,MACtC,GAAI,kBAAkB,SAAY,EAAE,cAAA,IAAkB,CAAA;AAAA,MACtD,GAAI,iBAAiB,SAAY,EAAE,aAAA,IAAiB,CAAA;AAAA,MACpD,YAAY;AAAA,QACV,KAAK,4BAA4B,KAAK;AAAA,QACtC,YAAY,OAAO;AAAA,MAAA;AAAA,IACrB,CACD;AAAA,EACH;AAAA;AAAA,EAGmB,aAAa,OAAqB;AACnD,SAAK,QAAQ,OAAO,KAAK;AAAA,EAC3B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYQ,4BAA4B,OAAsB;AACxD,UAAM,cAAc,KAAK,sBAAsB,KAAK;AACpD,WAAO,qBAAqB;AAAA,MAC1B,MAAM;AAAA,MACN,UAAU,CAAC,+BAA+B;AAAA,MAC1C,OAAO,CAAC,QAAQ;AACd,YAAI,QAAQ,iCAAiC,WAAW;AAAA,MAC1D;AAAA,IAAA,CACD;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQQ,sBAAsB,OAA6C;AACzE,UAAM,MAAM,KAAK;AACjB,UAAM,UAAU,KAAK;AACrB,UAAM,EAAE,OAAO,SAAA,IAAa;AAI5B,UAAM,SAAS,oBAAoB,KAAK,KAAK;AAC7C,WAAO;AAAA,MACL,UAAU,OAAO,SAAqC;AACpD,cAAM,QACJ,OAAO,eAAe,OAAO,aAAa,QAAQ,MAAM,EAAE;AAC5D,cAAM,OAAO,qBAAqB,OAAO;AAAA,UACvC,GAAI,QAAQ,YAAY,SACpB,EAAE,SAAS,QAAQ,QAAA,IACnB,CAAA;AAAA,UACJ,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,OAAA,IAAW,CAAA;AAAA,UAChE,GAAI,QAAQ,eAAe,SACvB,EAAE,YAAY,QAAQ,eACtB,CAAA;AAAA,QAAC,CACN;AACD,gBAAQ,IAAI,OAAO,EAAE,OAAO,MAAM;AAClC,eAAO,QAAQ,QAAQ;AAAA,UACrB,MAAM;AAAA,UACN,KAAK,GAAG,MAAM,YAAY,KAAK,aAAa,mBAAmB,QAAQ,CAAC;AAAA,UACxE;AAAA,UACA,OAAO,MAAM;AACX,oBAAQ,OAAO,KAAK;AACpB,mBAAO,QAAQ,QAAA;AAAA,UACjB;AAAA,QAAA,CACD;AAAA,MACH;AAAA,IAAA;AAAA,EAEJ;AAAA;AAAA,EAGmB,YACjB,SACA,OAC8B;AAC9B,QAAI,MAAM,CAAC,MAAM,aAAa,OAAO,MAAM,CAAC,MAAM,UAAU;AAC1D,aAAO,KAAK,YAAY,MAAM,CAAC,GAAG,OAAO;AAAA,IAC3C;AACA,WAAO,MAAM,YAAY,SAAS,KAAK;AAAA,EACzC;AAAA;AAAA,EAGA,MAAc,YACZ,OACA,SACmB;AACnB,UAAM,SAAS,KAAK,QAAQ,IAAI,KAAK;AACrC,QAAI,CAAC;AACH,aAAO,IAAI,SAAS,4BAA4B,EAAE,QAAQ,KAAK;AACjE,QACE,CAAC;AAAA,MACC,QAAQ,QAAQ,IAAI,eAAe,KAAK;AAAA,MACxC,OAAO;AAAA,IAAA,GAET;AACA,aAAO,IAAI,SAAS,gBAAgB,EAAE,QAAQ,KAAK;AAAA,IACrD;AACA,QAAI;AACJ,QAAI;AACF,gBAAU,MAAM,QAAQ,KAAA;AAAA,IAC1B,QAAQ;AAGN,aAAO,KAAK,aAAa;AAAA,QACvB,SAAS;AAAA,QACT,IAAI;AAAA,QACJ,OAAO,EAAE,MAAM,QAAQ,SAAS,cAAA;AAAA,MAAc,CAC/C;AAAA,IACH;AACA,UAAM,QAAQ,MAAM,oBAAoB,OAAO,MAAM,OAAO;AAE5D,QAAI,UAAU,KAAM,QAAO,IAAI,SAAS,MAAM,EAAE,QAAQ,KAAK;AAC7D,WAAO,KAAK,aAAa,KAAK;AAAA,EAChC;AACF;"}

package/dist/esm/container-coordinator.d.ts

@@ -0,0 +1,114 @@
+import { SandboxCoordinator, StartRunInput } from './coordinator.js';
+import { HarnessId } from './protocol.js';
+import { AnyTool, StreamChunk } from '@tanstack/ai';
+import { WorkspaceDefinition } from '@tanstack/ai-sandbox';
+import { Sandbox } from '@cloudflare/sandbox';
+/**
+ * The Env bindings a {@link ContainerSandboxCoordinator} requires. The
+ * `tool-exec` URL the CONTAINER calls back on needs a hostname; `PUBLIC_HOSTNAME`
+ * is OPTIONAL (request-derived when unset; locally → `host.docker.internal` — see
+ * {@link resolveBridgeOrigin}).
+ *
+ * Auth is HARNESS-AGNOSTIC: the in-container CLI's API key is NOT a fixed field on
+ * this env. Instead each run's workspace DECLARES the secret names it needs (via
+ * `createSecrets`), and the coordinator copies those names out of the Worker `env`
+ * into the container env at boot. So a Claude run declares `ANTHROPIC_API_KEY`, a
+ * codex run declares `CODEX_API_KEY`, and neither name is baked into the package —
+ * the concrete key binding lives on the APP's env type, not here.
+ */
+export interface ContainerCoordinatorEnv {
+    /** The `@cloudflare/sandbox` Sandbox DO namespace (the container hosts). */
+    Sandbox: DurableObjectNamespace<Sandbox>;
+    /**
+     * Hostname the container uses to reach the DO's `/tool-exec` endpoint. Optional:
+     * unset → derived from the trigger request (deployed: request host; local dev:
+     * `host.docker.internal`). Set it only to override. See {@link resolveBridgeOrigin}.
+     */
+    PUBLIC_HOSTNAME?: string;
+}
+/** What {@link ContainerSandboxCoordinator.config} returns for one run. */
+export interface ContainerRunConfig {
+    /**
+     * The REAL host tools. Their `execute()` runs HERE, in the DO — the
+     * in-container agent only ever reaches them via `/tool-exec/:runId`. Only the
+     * serialized descriptors cross to the container.
+     */
+    hostTools: Array<AnyTool>;
+    /** Workspace the in-container runner bootstraps for the agent. */
+    workspace: WorkspaceDefinition;
+    /** Which in-sandbox harness the runner spawns. */
+    harness: HarnessId;
+    /** Model id passed to that harness. */
+    model: string;
+    /** Runtime context forwarded to each host tool's `execute()` (DB / app state). */
+    context?: unknown;
+}
+export declare abstract class ContainerSandboxCoordinator<TEnv extends ContainerCoordinatorEnv = ContainerCoordinatorEnv> extends SandboxCoordinator<TEnv> {
+    /**
+     * Live per-run tool-exec tokens, keyed by runId. In-memory by design: a run's
+     * tool-exec endpoint is only reachable while the run is in flight, and
+     * `ctx.waitUntil(done)` keeps THIS instance alive for the run's lifetime, so
+     * the container's callbacks always hit the instance that minted the token.
+     */
+    private readonly toolExec;
+    /**
+     * In-flight runner boot, memoized so two runs starting near-simultaneously on
+     * this instance don't both spawn `container-runner` (the second would hit
+     * EADDRINUSE on RUNNER_PORT). Cleared once boot settles.
+     */
+    private runnerBoot?;
+    /** Last `/health` probe error, surfaced if the runner never comes up. */
+    private lastProbeError?;
+    /**
+     * Resolve the host tools, workspace, harness, and model for one run.
+     * Implemented by the app subclass (or supplied by
+     * {@link createCloudflareSandboxAgent}).
+     */
+    protected abstract config(input: StartRunInput): ContainerRunConfig;
+    /**
+     * Mint the per-run tool-exec token, POST `/run` to the in-container runner, and
+     * yield its NDJSON chunks. The token is registered BEFORE the container is told
+     * to run, so a tool callback can never arrive before the token exists.
+     */
+    protected buildRunStream(input: StartRunInput): AsyncIterable<StreamChunk>;
+    /**
+     * Once the run is terminal, abort any host tool still running on its behalf
+     * (so a tool that outlived the run doesn't leak), then drop the per-run state.
+     */
+    protected onRunSettled(runId: string): void;
+    /**
+     * POST `/run` to the in-container runner and yield its NDJSON chunks. The DO
+     * reaches the runner DIRECTLY over the sandbox binding (`containerFetch` to
+     * RUNNER_PORT) — this internal channel needs no public hostname. The runner
+     * gets the host-tool descriptors plus the `/tool-exec` URL + token it calls
+     * back on.
+     */
+    private driveContainer;
+    /**
+     * Ensure the in-container runner is listening on RUNNER_PORT. The base image's
+     * ENTRYPOINT is the sandbox CONTROL server, not our runner — so we start the
+     * bundled runner as a background process via that control server. Idempotent
+     * for a thread-reused container: if `/health` already answers, we skip spawn.
+     */
+    private ensureRunner;
+    /**
+     * Copy the run's DECLARED secret names out of the Worker `env` into a plain
+     * record for the container env. The workspace's `createSecrets` carries only the
+     * names across the `/run` boundary; the VALUES come from `env` by that name —
+     * which is how `ANTHROPIC_API_KEY` / `CODEX_API_KEY` / any harness key reach the
+     * CLI without the package hardcoding which one. A declared name missing from
+     * `env` is skipped here and fails loudly later in the runner's
+     * `reconstituteWorkspace` (never a silent keyless run).
+     */
+    private secretEnvFromWorkspace;
+    private bootRunner;
+    private runnerHealthy;
+    protected handleRoute(request: Request, parts: Array<string>): Promise<Response> | Response;
+    /**
+     * Execute a host tool the in-container agent called back for. The token gates
+     * it (constant-time Web Crypto compare); the REAL tool's `execute()` runs here
+     * via {@link executeHostTool} and its raw result returns as `{ result }`. An
+     * unknown tool or a thrown `execute()` is surfaced as a 4xx/5xx, never masked.
+     */
+    private serveToolExec;
+}

package/dist/esm/container-coordinator.js

@@ -0,0 +1,256 @@
+import { EventType } from "@tanstack/ai";
+import { toolDescriptors, isToolExecRequest, executeHostTool } from "@tanstack/ai-sandbox";
+import { getSandbox } from "@cloudflare/sandbox";
+import { SandboxCoordinator } from "./coordinator.js";
+import { timingSafeBearerEqualWeb } from "./web-crypto.js";
+import { resolveBridgeOrigin } from "./public-host.js";
+const RUNNER_PORT = 8080;
+function isStreamChunk(value) {
+  return value !== null && typeof value === "object" && "type" in value;
+}
+async function* ndjsonToChunks(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let result = await reader.read();
+  while (!result.done) {
+    buffer += decoder.decode(result.value, { stream: true });
+    let newline = buffer.indexOf("\n");
+    while (newline !== -1) {
+      const line = buffer.slice(0, newline).trim();
+      buffer = buffer.slice(newline + 1);
+      newline = buffer.indexOf("\n");
+      if (line === "") continue;
+      const chunk = parseChunkLine(line);
+      yield chunk;
+      if (chunk.type === EventType.RUN_ERROR) return;
+    }
+    result = await reader.read();
+  }
+  buffer += decoder.decode();
+  const tail = buffer.trim();
+  if (tail !== "") yield parseChunkLine(tail);
+}
+function parseChunkLine(line) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    return {
+      type: EventType.RUN_ERROR,
+      message: `runner sent unparseable NDJSON: ${line.slice(0, 200)}`
+    };
+  }
+  if (!isStreamChunk(parsed)) {
+    return {
+      type: EventType.RUN_ERROR,
+      message: "runner sent a non-chunk line"
+    };
+  }
+  return parsed;
+}
+class ContainerSandboxCoordinator extends SandboxCoordinator {
+  /**
+   * Live per-run tool-exec tokens, keyed by runId. In-memory by design: a run's
+   * tool-exec endpoint is only reachable while the run is in flight, and
+   * `ctx.waitUntil(done)` keeps THIS instance alive for the run's lifetime, so
+   * the container's callbacks always hit the instance that minted the token.
+   */
+  toolExec = /* @__PURE__ */ new Map();
+  /**
+   * In-flight runner boot, memoized so two runs starting near-simultaneously on
+   * this instance don't both spawn `container-runner` (the second would hit
+   * EADDRINUSE on RUNNER_PORT). Cleared once boot settles.
+   */
+  runnerBoot;
+  /** Last `/health` probe error, surfaced if the runner never comes up. */
+  lastProbeError;
+  // ===========================================================================
+  // The one per-model seam: drive the in-container runner
+  // ===========================================================================
+  /**
+   * Mint the per-run tool-exec token, POST `/run` to the in-container runner, and
+   * yield its NDJSON chunks. The token is registered BEFORE the container is told
+   * to run, so a tool callback can never arrive before the token exists.
+   */
+  buildRunStream(input) {
+    const runConfig = this.config(input);
+    const token = crypto.randomUUID() + crypto.randomUUID().replace(/-/g, "");
+    this.toolExec.set(input.runId, {
+      token,
+      hostTools: runConfig.hostTools,
+      ...runConfig.context !== void 0 ? { context: runConfig.context } : {},
+      abort: new AbortController()
+    });
+    return this.driveContainer(input, runConfig, token);
+  }
+  /**
+   * Once the run is terminal, abort any host tool still running on its behalf
+   * (so a tool that outlived the run doesn't leak), then drop the per-run state.
+   */
+  onRunSettled(runId) {
+    const state = this.toolExec.get(runId);
+    if (state) state.abort.abort();
+    this.toolExec.delete(runId);
+  }
+  /**
+   * POST `/run` to the in-container runner and yield its NDJSON chunks. The DO
+   * reaches the runner DIRECTLY over the sandbox binding (`containerFetch` to
+   * RUNNER_PORT) — this internal channel needs no public hostname. The runner
+   * gets the host-tool descriptors plus the `/tool-exec` URL + token it calls
+   * back on.
+   */
+  async *driveContainer(input, runConfig, token) {
+    const sandbox = getSandbox(this.env.Sandbox, input.threadId);
+    await this.ensureRunner(sandbox, runConfig.workspace);
+    const origin = resolveBridgeOrigin(this.env, input);
+    const body = {
+      runId: input.runId,
+      threadId: input.threadId,
+      messages: input.messages,
+      harness: runConfig.harness,
+      model: runConfig.model,
+      workspace: runConfig.workspace,
+      // Serialize the DO's real tools to wire descriptors for the container.
+      toolDescriptors: toolDescriptors(runConfig.hostTools),
+      // The container calls back here for host-tool EXECUTION. It must be a URL
+      // the CONTAINER can reach, so it goes via the Worker's public hostname.
+      toolExecUrl: `${origin}/tool-exec/${input.runId}?threadId=${encodeURIComponent(input.threadId)}`,
+      toolExecToken: token
+    };
+    const response = await sandbox.containerFetch(
+      "http://runner/run",
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body)
+      },
+      RUNNER_PORT
+    );
+    if (!response.ok || !response.body) {
+      const text = await response.text();
+      yield {
+        type: EventType.RUN_ERROR,
+        message: `container runner failed: ${response.status} ${text.slice(0, 200)}`
+      };
+      return;
+    }
+    yield* ndjsonToChunks(response.body);
+  }
+  /**
+   * Ensure the in-container runner is listening on RUNNER_PORT. The base image's
+   * ENTRYPOINT is the sandbox CONTROL server, not our runner — so we start the
+   * bundled runner as a background process via that control server. Idempotent
+   * for a thread-reused container: if `/health` already answers, we skip spawn.
+   */
+  ensureRunner(sandbox, workspace) {
+    if (this.runnerBoot) return this.runnerBoot;
+    const boot = this.bootRunner(sandbox, workspace).finally(() => {
+      this.runnerBoot = void 0;
+    });
+    this.runnerBoot = boot;
+    return boot;
+  }
+  /**
+   * Copy the run's DECLARED secret names out of the Worker `env` into a plain
+   * record for the container env. The workspace's `createSecrets` carries only the
+   * names across the `/run` boundary; the VALUES come from `env` by that name —
+   * which is how `ANTHROPIC_API_KEY` / `CODEX_API_KEY` / any harness key reach the
+   * CLI without the package hardcoding which one. A declared name missing from
+   * `env` is skipped here and fails loudly later in the runner's
+   * `reconstituteWorkspace` (never a silent keyless run).
+   */
+  secretEnvFromWorkspace(workspace) {
+    const env = this.env;
+    const out = {};
+    for (const name of Object.keys(workspace.secrets ?? {})) {
+      const value = env[name];
+      if (typeof value === "string" && value !== "") out[name] = value;
+    }
+    return out;
+  }
+  async bootRunner(sandbox, workspace) {
+    if (await this.runnerHealthy(sandbox)) return;
+    const secretEnv = this.secretEnvFromWorkspace(workspace);
+    if (Object.keys(secretEnv).length > 0) {
+      await sandbox.setEnvVars(secretEnv);
+    }
+    await sandbox.startProcess(`node /app/container-runner.mjs`, {
+      env: { RUNNER_PORT: String(RUNNER_PORT) }
+    });
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+      if (await this.runnerHealthy(sandbox)) return;
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    const detail = this.lastProbeError instanceof Error ? `: ${this.lastProbeError.message}` : this.lastProbeError !== void 0 ? `: ${String(this.lastProbeError)}` : "";
+    throw new Error(
+      `in-container runner did not become healthy in time${detail}`
+    );
+  }
+  async runnerHealthy(sandbox) {
+    try {
+      const res = await sandbox.containerFetch(
+        "http://runner/health",
+        { method: "GET" },
+        RUNNER_PORT
+      );
+      return res.ok;
+    } catch (error) {
+      this.lastProbeError = error;
+      return false;
+    }
+  }
+  // ===========================================================================
+  // The host-tool-exec callback (`/tool-exec/:runId`), from the base fetch
+  // ===========================================================================
+  handleRoute(request, parts) {
+    if (parts[0] === "tool-exec" && typeof parts[1] === "string") {
+      return this.serveToolExec(parts[1], request);
+    }
+    return super.handleRoute(request, parts);
+  }
+  /**
+   * Execute a host tool the in-container agent called back for. The token gates
+   * it (constant-time Web Crypto compare); the REAL tool's `execute()` runs here
+   * via {@link executeHostTool} and its raw result returns as `{ result }`. An
+   * unknown tool or a thrown `execute()` is surfaced as a 4xx/5xx, never masked.
+   */
+  async serveToolExec(runId, request) {
+    const state = this.toolExec.get(runId);
+    if (!state) return new Response("no active run", { status: 404 });
+    if (!timingSafeBearerEqualWeb(
+      request.headers.get("authorization") ?? void 0,
+      state.token
+    )) {
+      return new Response("unauthorized", { status: 401 });
+    }
+    let payload;
+    try {
+      payload = await request.json();
+    } catch {
+      return this.jsonResponse({ error: "body must be valid JSON" }, 400);
+    }
+    if (!isToolExecRequest(payload)) {
+      return this.jsonResponse({ error: "body must be { name, args }" }, 400);
+    }
+    try {
+      const result = await executeHostTool(
+        state.hostTools,
+        payload.name,
+        payload.args,
+        {
+          ...state.context !== void 0 ? { context: state.context } : {},
+          signal: state.abort.signal
+        }
+      );
+      return this.jsonResponse({ result });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return this.jsonResponse({ error: message }, 500);
+    }
+  }
+}
+export {
+  ContainerSandboxCoordinator
+};
+//# sourceMappingURL=container-coordinator.js.map