@tanstack/ai-sandbox-cloudflare 0.1.0

package/src/public-host.ts

@@ -0,0 +1,121 @@
+/**
+ * Host resolution for the two DISTINCT public surfaces the sandbox layer exposes.
+ * Kept in its own (Workers-free) module so it stays pure and unit-testable.
+ *
+ * These were once a single `PUBLIC_HOSTNAME`, but they have different reachers and
+ * therefore different correct values:
+ *
+ *  - **Bridge / tool-exec** — the off-isolate CONTAINER calls back into the Worker
+ *    (`/_bridge`, `/tool-exec`). It must reach the Worker, so locally that's
+ *    `host.docker.internal` (the container can't reach the host's `localhost`).
+ *  - **Preview** — the BROWSER opens an `exposePort` URL that `proxyToSandbox`
+ *    routes into the container. It needs WILDCARD DNS, so locally that's
+ *    `*.localhost` (browsers resolve it to loopback with zero setup) and in
+ *    production a CUSTOM DOMAIN (`*.workers.dev` has no wildcard subdomains).
+ */
+
+/** Hostnames that mean "this machine" (the loopback the container can't reach). */
+function isLoopbackHost(host: string): boolean {
+  const name = host.split(':')[0]
+  return name === 'localhost' || name === '127.0.0.1' || name === '0.0.0.0'
+}
+
+/** The port portion of a `host[:port]`, or `fallback` when none is present. */
+function portOf(host: string, fallback: string): string {
+  const colon = host.indexOf(':')
+  return colon === -1 ? fallback : host.slice(colon + 1)
+}
+
+/** `http://` for local hosts (loopback / host.docker.internal), `https://` else. */
+function originForHost(host: string): string {
+  const name = host.split(':')[0]
+  const scheme =
+    isLoopbackHost(host) || name === 'host.docker.internal' ? 'http' : 'https'
+  return `${scheme}://${host}`
+}
+
+/**
+ * Resolve the ORIGIN the off-isolate sandbox CONTAINER uses to call back into the
+ * Worker — the MCP tool-bridge (`/_bridge`) and host-tool execution (`/tool-exec`).
+ * Returns a full origin (scheme + host + optional port), e.g.
+ * `http://host.docker.internal:3001` locally or `https://app.example.com` deployed.
+ *
+ * `PUBLIC_HOSTNAME` wins when set; otherwise we derive from the host the trigger
+ * request arrived on (`input.publicHost`).
+ *
+ * ── Why a callback hostname is unavoidable ──────────────────────────────────────
+ * The container is SEPARATE compute from the Worker isolate; it can only reach the
+ * Worker over the network, so the callback URL must be an absolute host.
+ *
+ * ── Why request-derivation is SAFE on Cloudflare ────────────────────────────────
+ * On a generic Node server the `Host` header is attacker-controlled and trusting it
+ * is a Host-injection / token-exfil vector (the per-run bearer token rides this
+ * URL). Not so behind Cloudflare: the edge dispatches a request to your Worker only
+ * when its hostname matches a route you OWN, so `input.publicHost` is always one of
+ * your own hostnames — never an attacker's.
+ *
+ * ── Local dev: localhost → host.docker.internal ─────────────────────────────────
+ * Locally the trigger arrives on `localhost`, which the container CANNOT reach
+ * (that's the container's own loopback). So we rewrite it to `host.docker.internal`
+ * (the Docker host gateway), keeping the port, over `http`. This removes the need
+ * for a dev tunnel for the bridge entirely.
+ */
+export function resolveBridgeOrigin(
+  env: { PUBLIC_HOSTNAME?: string },
+  input: { publicHost?: string },
+): string {
+  const configured = env.PUBLIC_HOSTNAME?.trim()
+  if (configured) return originForHost(configured)
+  const host = input.publicHost
+  if (!host) {
+    throw new Error(
+      'sandbox agent: no bridge host available — set PUBLIC_HOSTNAME, or run ' +
+        'behind Cloudflare so the Worker can derive it from the trigger request.',
+    )
+  }
+  // Local dev: the container reaches the host machine via the Docker host gateway.
+  if (isLoopbackHost(host)) {
+    return `http://host.docker.internal:${portOf(host, '3001')}`
+  }
+  return originForHost(host)
+}
+
+/**
+ * Resolve the HOST passed to `exposePort` for browser-facing preview URLs (the app
+ * the agent builds). Returns a bare host (the `@cloudflare/sandbox` SDK builds the
+ * `<port>-<id>-<token>.<host>` URL + scheme itself).
+ *
+ * `PREVIEW_HOSTNAME` wins when set; otherwise we derive from the trigger request.
+ *
+ * Preview URLs require WILDCARD DNS, which constrains the value:
+ *  - **Local** → `localhost:<port>`. The SDK's localhost path yields
+ *    `http://<port>-<id>-<token>.localhost:<port>`, which browsers resolve to
+ *    loopback with no DNS setup — so previews work locally with no tunnel.
+ *  - **Deployed** → a CUSTOM DOMAIN with a `*.<domain>` route. `*.workers.dev` has
+ *    no wildcard subdomains (the SDK's `exposePort` throws on it), so we throw a
+ *    clear error pointing at `PREVIEW_HOSTNAME` rather than letting the run fail
+ *    deep in the agent.
+ */
+export function resolvePreviewHost(
+  env: { PREVIEW_HOSTNAME?: string },
+  input: { publicHost?: string },
+): string {
+  const configured = env.PREVIEW_HOSTNAME?.trim()
+  if (configured) return configured
+  const host = input.publicHost
+  if (!host) {
+    throw new Error(
+      'sandbox agent: no preview host available — set PREVIEW_HOSTNAME to a ' +
+        'custom domain with a wildcard route.',
+    )
+  }
+  if (isLoopbackHost(host)) return host
+  if (host.endsWith('.workers.dev')) {
+    throw new Error(
+      'sandbox agent: preview URLs need a custom domain with wildcard DNS — ' +
+        '*.workers.dev has no wildcard subdomains. Set PREVIEW_HOSTNAME to your ' +
+        'custom domain and add a `*.<domain>` route to the Worker.',
+    )
+  }
+  return host
+}

package/src/run-log-do.ts

@@ -0,0 +1,171 @@
+/**
+ * A durable {@link RunEventLog} backed by Durable Object storage — the storage
+ * half of the serverless/edge run model. The coordinator appends every
+ * {@link StreamChunk} the agent emits under a monotonic `seq`; clients tail from
+ * a cursor. Because events are PERSISTED (not held in a caller's open stream), a
+ * reconnecting tab, a dropped WebSocket, or a coordinator that hibernated
+ * between chunks all resume cleanly: replay everything after the client's
+ * `lastSeq`, then live-tail to terminal.
+ *
+ * Mirrors {@link InMemoryRunEventLog} from `@tanstack/ai-sandbox` exactly.
+ * Storage layout (keys scoped by `runId` so one DO can host many runs):
+ * - `rec:<runId>`        → the {@link RunRecord}
+ * - `evt:<runId>:<seq8>` → the chunk for that seq (seq zero-padded to 8 digits
+ *                          so `list({ prefix })` returns events in seq order).
+ *
+ * The live-tail wake-up (the in-memory waiter set) is per-INSTANCE; if the
+ * instance is evicted mid-run, a reader re-reads the persisted backlog and the
+ * `TAIL_POLL_MS` fallback poll keeps it progressing. No event is ever lost.
+ *
+ * NOTE: Workers-runtime code — compiles against `@cloudflare/workers-types`.
+ */
+import { isTerminalRunStatus } from '@tanstack/ai-sandbox'
+import type {
+  RunError,
+  RunEvent,
+  RunEventLog,
+  RunEventLogReadOptions,
+  RunRecord,
+  TerminalRunStatus,
+} from '@tanstack/ai-sandbox'
+import type { StreamChunk } from '@tanstack/ai'
+
+/** How long a post-eviction reader waits before re-polling storage (ms). */
+const TAIL_POLL_MS = 250
+
+const recKey = (runId: string): string => `rec:${runId}`
+const evtKey = (runId: string, seq: number): string =>
+  `evt:${runId}:${String(seq).padStart(8, '0')}`
+const evtPrefix = (runId: string): string => `evt:${runId}:`
+
+export class DurableObjectRunEventLog implements RunEventLog {
+  /** Per-run wake-ups for live-tailing readers on THIS instance. */
+  private readonly waiters = new Map<string, Set<() => void>>()
+
+  constructor(private readonly storage: DurableObjectStorage) {}
+
+  private async require(runId: string): Promise<RunRecord> {
+    const record = await this.storage.get<RunRecord>(recKey(runId))
+    if (!record) throw new Error(`run-log: unknown runId "${runId}"`)
+    return record
+  }
+
+  /** Wake (and clear) every reader blocked on this run. */
+  private wake(runId: string): void {
+    const set = this.waiters.get(runId)
+    if (!set) return
+    const pending = [...set]
+    set.clear()
+    for (const resolve of pending) resolve()
+  }
+
+  async open(input: { runId: string; threadId?: string }): Promise<RunRecord> {
+    const existing = await this.storage.get<RunRecord>(recKey(input.runId))
+    if (existing) return existing
+    const now = Date.now()
+    const record: RunRecord = {
+      runId: input.runId,
+      ...(input.threadId !== undefined ? { threadId: input.threadId } : {}),
+      status: 'running',
+      lastSeq: -1,
+      createdAt: now,
+      updatedAt: now,
+    }
+    await this.storage.put(recKey(input.runId), record)
+    return record
+  }
+
+  async append(runId: string, chunk: StreamChunk): Promise<number> {
+    const record = await this.require(runId)
+    if (isTerminalRunStatus(record.status)) {
+      throw new Error(
+        `run-log: cannot append to terminal run "${runId}" (status=${record.status})`,
+      )
+    }
+    const seq = record.lastSeq + 1
+    const next: RunRecord = { ...record, lastSeq: seq, updatedAt: Date.now() }
+    // One transaction so the appended event and its bumped record commit
+    // together — a reader never sees a lastSeq pointing at a missing event.
+    await this.storage.transaction(async (txn) => {
+      await txn.put(evtKey(runId, seq), chunk)
+      await txn.put(recKey(runId), next)
+    })
+    this.wake(runId)
+    return seq
+  }
+
+  async finish(
+    runId: string,
+    status: TerminalRunStatus,
+    error?: RunError,
+  ): Promise<void> {
+    const record = await this.require(runId)
+    if (isTerminalRunStatus(record.status)) return
+    const next: RunRecord = {
+      ...record,
+      status,
+      ...(error !== undefined ? { error } : {}),
+      updatedAt: Date.now(),
+    }
+    await this.storage.put(recKey(runId), next)
+    this.wake(runId)
+  }
+
+  async get(runId: string): Promise<RunRecord | null> {
+    return (await this.storage.get<RunRecord>(recKey(runId))) ?? null
+  }
+
+  async *read(
+    runId: string,
+    options?: RunEventLogReadOptions,
+  ): AsyncIterable<RunEvent> {
+    await this.require(runId)
+    const signal = options?.signal
+    let cursor = options?.fromSeq ?? -1
+
+    while (!signal?.aborted) {
+      const record = await this.require(runId)
+      // Drain the persisted backlog after the cursor in seq order. The
+      // zero-padded keys make the prefix list naturally ordered.
+      if (cursor < record.lastSeq) {
+        const events = await this.storage.list<StreamChunk>({
+          prefix: evtPrefix(runId),
+          start: evtKey(runId, cursor + 1),
+        })
+        for (const [, chunk] of events) {
+          cursor += 1
+          yield { seq: cursor, chunk }
+          if (signal?.aborted) return
+        }
+        continue
+      }
+      if (isTerminalRunStatus(record.status)) return
+      await this.waitForChange(runId, signal)
+    }
+  }
+
+  /**
+   * Resolve when an append/finish wakes this run, the signal aborts, or the
+   * fallback poll fires (the poll lets a reader that outlived its in-memory
+   * waiter — e.g. after the appending instance was evicted — keep progressing).
+   */
+  private waitForChange(runId: string, signal?: AbortSignal): Promise<void> {
+    return new Promise<void>((resolve) => {
+      let set = this.waiters.get(runId)
+      if (!set) {
+        set = new Set()
+        this.waiters.set(runId, set)
+      }
+      const localSet = set
+      const wake = (): void => {
+        localSet.delete(wake)
+        clearTimeout(timer)
+        if (signal) signal.removeEventListener('abort', wake)
+        resolve()
+      }
+      const timer = setTimeout(wake, TAIL_POLL_MS)
+      localSet.add(wake)
+      if (signal) signal.addEventListener('abort', wake, { once: true })
+    })
+  }
+}

package/src/runner.ts

@@ -0,0 +1,226 @@
+/**
+ * `runInContainerHarness` — the IN-CONTAINER harness runner, shipped from the
+ * package so a co-located app's container program is a single function call.
+ *
+ * This is the heart of the CO-LOCATED model: the agent harness loop AND its MCP
+ * tool-bridge run HERE, on the container's own localhost. The Durable Object
+ * outside never calls `chat()`; it POSTs `/run` to this server and reads the
+ * NDJSON stream back.
+ *
+ *   DO  ── POST /run {messages, harness, model, workspace, toolDescriptors,
+ *                     toolExecUrl, toolExecToken} ──▶  THIS
+ *   THIS ── NDJSON stream of StreamChunk ──────────────────────────────────▶  DO
+ *
+ * It is a tiny `node:http` server (NODE/container side — NOT Workers; it uses
+ * `localProcessSandbox`). On `POST /run` it validates the {@link
+ * ContainerRunRequest}, builds `chat()` with the in-container `local-process`
+ * sandbox and the adapter the CALLER resolves, and streams each {@link
+ * StreamChunk} back as NDJSON (one JSON object per line).
+ *
+ * Why the MCP bridge is genuinely in-container: the in-container sandbox is
+ * `localProcessSandbox()` — the container IS the host — so the harness adapter
+ * serves its tool-bridge over the container's own `localhost` and feeds the
+ * prompt over NATIVE writable stdin (no file-redirect; the bridge URL/token
+ * never leave the container). The MCP protocol never crosses the network.
+ *
+ * The ONE thing that still crosses back to the DO is host-tool EXECUTION: each
+ * tool rebuilt by {@link remoteToolStubs} delegates its `execute()` to {@link
+ * httpRemoteToolExecutor}, which POSTs `{ name, args }` (bearer-gated) to the
+ * DO's `toolExecUrl`:
+ *
+ *   agent → in-container MCP bridge → stub.execute → httpRemoteToolExecutor → DO
+ *
+ * The app supplies only `resolveAdapter` — which `*Text` adapter to build for a
+ * given `{ harness, model }`. The server + `chat()` wiring lives here, so the
+ * package doesn't depend on every adapter package.
+ *
+ * NOTE: container-side Node code — compiles against the real TanStack AI types;
+ * not runtime-verified in this repo (no container build in CI).
+ */
+import { createServer } from 'node:http'
+import { EventType, chat } from '@tanstack/ai'
+import {
+  createSecrets,
+  defineSandbox,
+  defineWorkspace,
+  httpRemoteToolExecutor,
+  remoteToolStubs,
+  withSandbox,
+} from '@tanstack/ai-sandbox'
+import { localProcessSandbox } from '@tanstack/ai-sandbox-local-process'
+import { parseContainerRunRequest } from './protocol'
+import type { IncomingMessage, Server, ServerResponse } from 'node:http'
+import type { AnyTextAdapter, StreamChunk } from '@tanstack/ai'
+import type { WorkspaceDefinition } from '@tanstack/ai-sandbox'
+import type { ContainerRunRequest, HarnessId } from './protocol'
+
+/** The `{ harness, model }` the caller maps to a concrete `*Text` adapter. */
+export interface ResolveAdapterInput {
+  harness: HarnessId
+  model: string
+}
+
+/** Options for {@link runInContainerHarness}. */
+export interface RunInContainerHarnessOptions {
+  /**
+   * Build the text adapter `chat()` runs for one request's `{ harness, model }`.
+   * The app supplies this so the package doesn't depend on every adapter package
+   * — e.g. `({ model }) => claudeCodeText(model)`.
+   */
+  resolveAdapter: (input: ResolveAdapterInput) => AnyTextAdapter
+  /** Port to listen on. Defaults to `RUNNER_PORT` env, then `8080`. */
+  port?: number
+}
+
+/** What {@link runInContainerHarness} returns: the listening `node:http` server. */
+export interface ContainerHarnessServer {
+  /** The underlying `node:http` server (already `listen()`ing). */
+  server: Server
+  /** The port it is listening on. */
+  port: number
+}
+
+/** Read a request body fully into a string (small JSON payloads only). */
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let body = ''
+    req.setEncoding('utf8')
+    req.on('data', (chunk: string) => {
+      body += chunk
+    })
+    req.on('end', () => resolve(body))
+    req.on('error', reject)
+  })
+}
+
+/**
+ * Rebuild the request's workspace with a real `createSecrets`, pulling each
+ * referenced secret's VALUE from the container env. Secret values never cross
+ * the `POST /run` boundary (`createSecrets` stores them under a non-enumerable
+ * symbol, so serializing the workspace carries only the names) — the DO injects
+ * them into the container env via `sandbox.setEnvVars`, and we reconstitute them
+ * here. A referenced secret missing from the env is a hard error, never a silent
+ * keyless run.
+ */
+function reconstituteWorkspace(
+  workspace: WorkspaceDefinition,
+): WorkspaceDefinition {
+  if (workspace.secrets === undefined) return workspace
+  const names = Object.keys(workspace.secrets)
+  if (names.length === 0) return workspace
+  const values: Record<string, string> = {}
+  for (const name of names) {
+    const value = process.env[name]
+    if (value === undefined || value === '') {
+      throw new Error(
+        `runInContainerHarness: secret "${name}" is not set in the container env`,
+      )
+    }
+    values[name] = value
+  }
+  return defineWorkspace({ ...workspace, secrets: createSecrets(values) })
+}
+
+/**
+ * Build the `chat()` stream that runs the harness on THIS container via the
+ * `local-process` sandbox. The agent's `chat()` tools are stubs that delegate
+ * back to the DO; everything else (the harness loop, the MCP bridge, stdin)
+ * stays on localhost.
+ */
+function runAgent(
+  request: ContainerRunRequest,
+  resolveAdapter: (input: ResolveAdapterInput) => AnyTextAdapter,
+): AsyncIterable<StreamChunk> {
+  const sandbox = defineSandbox({
+    // The container IS the host: no isolation, just run on its own filesystem.
+    id: 'colocated-in-container',
+    provider: localProcessSandbox(),
+    // Honor the app's workspace (source / setup / skills / …), with the secrets
+    // re-resolved from the container env.
+    workspace: reconstituteWorkspace(request.workspace),
+  })
+
+  // `stream: true` (no outputSchema) makes chat() return AsyncIterable<StreamChunk>.
+  return chat({
+    threadId: request.threadId,
+    adapter: resolveAdapter({
+      harness: request.harness,
+      model: request.model,
+    }),
+    messages: request.messages,
+    stream: true,
+    // Rebuild the DO's host tools as stubs whose execute() POSTs back to the DO.
+    // The adapter bridges them over the in-container localhost MCP transport.
+    tools: remoteToolStubs(
+      request.toolDescriptors,
+      httpRemoteToolExecutor(request.toolExecUrl, request.toolExecToken),
+    ),
+    // Provide the in-container local-process sandbox handle the adapter needs.
+    middleware: [withSandbox(sandbox)],
+  })
+}
+
+/** Stream the agent's chunks to the response as NDJSON, one object per line. */
+async function handleRun(
+  req: IncomingMessage,
+  res: ServerResponse,
+  resolveAdapter: (input: ResolveAdapterInput) => AnyTextAdapter,
+): Promise<void> {
+  const parsed: unknown = JSON.parse(await readBody(req))
+  const request = parseContainerRunRequest(parsed)
+  res.writeHead(200, {
+    'content-type': 'application/x-ndjson',
+    'cache-control': 'no-cache',
+  })
+  // The DO appends each line to its durable run-log; here we are the producer,
+  // so we surface a mid-stream failure as a terminal RUN_ERROR line the DO will
+  // append + finish on, never a silently truncated stream.
+  try {
+    for await (const chunk of runAgent(request, resolveAdapter)) {
+      res.write(`${JSON.stringify(chunk)}\n`)
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    res.write(`${JSON.stringify({ type: EventType.RUN_ERROR, message })}\n`)
+  } finally {
+    res.end()
+  }
+}
+
+/**
+ * Start the in-container harness runner: a `node:http` server with `GET /health`
+ * and `POST /run`. Call this as the container's program; the app supplies only
+ * `resolveAdapter`.
+ */
+export function runInContainerHarness(
+  options: RunInContainerHarnessOptions,
+): ContainerHarnessServer {
+  const port =
+    options.port ?? Number.parseInt(process.env.RUNNER_PORT ?? '8080', 10)
+
+  const server = createServer((req, res) => {
+    if (req.method === 'POST' && req.url === '/run') {
+      handleRun(req, res, options.resolveAdapter).catch((error: unknown) => {
+        // A failure BEFORE we start streaming (e.g. a malformed body) is a 400 —
+        // surfaced, never swallowed.
+        const message = error instanceof Error ? error.message : String(error)
+        if (!res.headersSent) {
+          res.writeHead(400, { 'content-type': 'text/plain' })
+        }
+        res.end(message)
+      })
+      return
+    }
+    if (req.method === 'GET' && req.url === '/health') {
+      res.writeHead(200).end('ok')
+      return
+    }
+    res.writeHead(404).end('not found')
+  })
+
+  server.listen(port, () => {
+    console.log(`[container-runner] listening on :${port}`)
+  })
+
+  return { server, port }
+}

package/src/web-crypto.ts

@@ -0,0 +1,31 @@
+/**
+ * Web Crypto helpers for the Workers runtime, where `node:crypto` is
+ * unavailable. The sandbox layer's `timingSafeBearerEqual` is node-based; this
+ * is the equivalent for a Worker / Durable Object.
+ */
+
+/**
+ * Constant-time check of an `Authorization: Bearer <token>` header against the
+ * expected token. A length mismatch returns false early (token length is not
+ * secret); the equal-length comparison is timing-safe.
+ */
+export function timingSafeBearerEqualWeb(
+  header: string | undefined,
+  token: string,
+): boolean {
+  if (header === undefined) return false
+  const a = new TextEncoder().encode(header)
+  const b = new TextEncoder().encode(`Bearer ${token}`)
+  if (a.length !== b.length) return false
+  let diff = 0
+  for (let i = 0; i < a.length; i += 1) {
+    const ai = a[i]
+    const bi = b[i]
+    // In-bounds by construction (i < a.length === b.length); the guard satisfies
+    // `noUncheckedIndexedAccess` without a non-null assertion and treats any
+    // impossible out-of-bounds read as "not equal".
+    if (ai === undefined || bi === undefined) return false
+    diff |= ai ^ bi
+  }
+  return diff === 0
+}