@tanstack/ai-sandbox-cloudflare 0.2.3 → 0.3.0

package/dist/esm/factory.js

@@ -1,69 +1,108 @@
-import { defineSandbox, defineWorkspace } from "@tanstack/ai-sandbox";
-import { Sandbox } from "@cloudflare/sandbox";
 import { cloudflareSandbox } from "./provider.js";
+import { resolvePreviewHost } from "./public-host.js";
+import "./coordinator.js";
 import { ChatSandboxCoordinator } from "./chat-coordinator.js";
 import { ContainerSandboxCoordinator } from "./container-coordinator.js";
 import { createSandboxAgentWorker } from "./worker.js";
-import "cloudflare:workers";
-import "@tanstack/ai";
-import { resolvePreviewHost } from "./public-host.js";
+import { Sandbox } from "@cloudflare/sandbox";
+import { defineSandbox, defineWorkspace } from "@tanstack/ai-sandbox";
+//#region src/factory.ts
+/**
+* `createCloudflareSandboxAgent` — the headline DX: one configured function call
+* returns the Durable Object coordinator, the Sandbox DO, and the Worker fetch
+* handler, so a Cloudflare app's whole `worker.ts` is just export wiring:
+*
+* ```ts
+* const agent = createCloudflareSandboxAgent({
+*   adapter: () => claudeCodeText('sonnet'),
+* })
+* export const RunCoordinator = agent.Coordinator
+* export const Sandbox = agent.Sandbox
+* export default agent.worker
+* ```
+*
+* Two modes, switched by `config.mode`:
+*  - `'do-drives'` (default) → a {@link ChatSandboxCoordinator}: the DO runs
+*    `chat()` itself and hosts the MCP tool-bridge.
+*  - `'colocated'` → a {@link ContainerSandboxCoordinator}: an in-container
+*    runner runs `chat()`; the DO is a thin coordinator that executes host tools.
+*
+* Env bindings (set in `wrangler.jsonc`):
+*  - `RUN_COORDINATOR` — this coordinator DO's own namespace (so the Worker can
+*    address it by `threadId`). Class name: whatever you export `Coordinator` as.
+*  - `Sandbox` — the `@cloudflare/sandbox` Sandbox DO namespace (the container
+*    hosts). Bind the exported `Sandbox` class.
+*  - `PUBLIC_HOSTNAME` — OPTIONAL. Hostname the CONTAINER uses to reach the Worker's
+*    tool-bridge / tool-exec endpoint. Unset → request-derived (local dev →
+*    `host.docker.internal`). See `resolveBridgeOrigin`.
+*  - `PREVIEW_HOSTNAME` — OPTIONAL. Custom domain (with a `*.<domain>` route) for
+*    browser-facing `exposePort` preview URLs. Unset → request-derived (local dev →
+*    `localhost`); REQUIRED on a `*.workers.dev` deploy, which has no wildcard
+*    subdomains. See `resolvePreviewHost`.
+*  - The harness's API key (`ANTHROPIC_API_KEY` for Claude Code, `CODEX_API_KEY` for
+*    codex, …) — supplied by YOUR app, never by the package. Declare it as a secret
+*    on the run's workspace (via a `sandbox`/`workspace` resolver) and add the field
+*    to your own env type; the coordinator injects each declared secret into the
+*    sandbox env by name. The package itself is harness-agnostic and binds no key.
+*
+* NOTE: Workers-runtime code — compiles against the real Cloudflare + TanStack
+* AI types; not runtime-verified in this repo (no Workers runtime here).
+*/
+/** Build the default per-thread Cloudflare sandbox for the DO-drives mode. */
 function defaultSandbox(env, input, workspace) {
-  return defineSandbox({
-    id: "cf-edge-agent",
-    provider: cloudflareSandbox({
-      binding: env.Sandbox,
-      // Browser-facing preview host: `PREVIEW_HOSTNAME` if set, else derived from
-      // the trigger request (local dev → `localhost`; deployed → a custom domain,
-      // since `*.workers.dev` has no wildcard). See `resolvePreviewHost`.
-      previewHostname: resolvePreviewHost(env, input)
-    }),
-    workspace: workspace ?? // The container image ships the harness CLI; no source to clone, and NO auth
-    // secrets — the package is harness-agnostic, so it can't know which key the
-    // CLI needs. Supply the harness's API key via a `workspace` with `secrets`
-    // (or a custom `sandbox` resolver), e.g.:
-    //   workspace: defineWorkspace({
-    //     source: { type: 'none' },
-    //     secrets: createSecrets({ ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY }),
-    //   })
-    defineWorkspace({ source: { type: "none" } }),
-    // One sandbox per thread, so a follow-up run resumes the same workspace.
-    lifecycle: { reuse: "thread" }
-  });
+	return defineSandbox({
+		id: "cf-edge-agent",
+		provider: cloudflareSandbox({
+			binding: env.Sandbox,
+			previewHostname: resolvePreviewHost(env, input)
+		}),
+		workspace: workspace ?? defineWorkspace({ source: { type: "none" } }),
+		lifecycle: { reuse: "thread" }
+	});
 }
+/** Resolve the coordinator DO that owns a thread's runs (`RUN_COORDINATOR`). */
 function resolveCoordinator(env, threadId) {
-  return env.RUN_COORDINATOR.get(env.RUN_COORDINATOR.idFromName(threadId));
+	return env.RUN_COORDINATOR.get(env.RUN_COORDINATOR.idFromName(threadId));
 }
 function createCloudflareSandboxAgent(config) {
-  const worker = createSandboxAgentWorker(resolveCoordinator);
-  if (config.mode === "colocated") {
-    const colocated = config;
-    class ConfiguredContainerCoordinator extends ContainerSandboxCoordinator {
-      config(input) {
-        return {
-          hostTools: colocated.tools?.(input, this.env) ?? [],
-          workspace: colocated.workspace,
-          harness: colocated.harness,
-          model: colocated.model
-        };
-      }
-    }
-    return { Coordinator: ConfiguredContainerCoordinator, Sandbox, worker };
-  }
-  const doDrives = config;
-  class ConfiguredChatCoordinator extends ChatSandboxCoordinator {
-    config(input) {
-      const tools = doDrives.tools?.(input, this.env);
-      return {
-        adapter: doDrives.adapter(input, this.env),
-        sandbox: doDrives.sandbox?.(input, this.env) ?? defaultSandbox(this.env, input, doDrives.workspace),
-        ...tools !== void 0 ? { tools } : {},
-        ...doDrives.systemPrompts !== void 0 ? { systemPrompts: doDrives.systemPrompts } : {}
-      };
-    }
-  }
-  return { Coordinator: ConfiguredChatCoordinator, Sandbox, worker };
+	const worker = createSandboxAgentWorker(resolveCoordinator);
+	if (config.mode === "colocated") {
+		const colocated = config;
+		class ConfiguredContainerCoordinator extends ContainerSandboxCoordinator {
+			config(input) {
+				return {
+					hostTools: colocated.tools?.(input, this.env) ?? [],
+					workspace: colocated.workspace,
+					harness: colocated.harness,
+					model: colocated.model
+				};
+			}
+		}
+		return {
+			Coordinator: ConfiguredContainerCoordinator,
+			Sandbox,
+			worker
+		};
+	}
+	const doDrives = config;
+	class ConfiguredChatCoordinator extends ChatSandboxCoordinator {
+		config(input) {
+			const tools = doDrives.tools?.(input, this.env);
+			return {
+				adapter: doDrives.adapter(input, this.env),
+				sandbox: doDrives.sandbox?.(input, this.env) ?? defaultSandbox(this.env, input, doDrives.workspace),
+				...tools !== void 0 ? { tools } : {},
+				...doDrives.systemPrompts !== void 0 ? { systemPrompts: doDrives.systemPrompts } : {}
+			};
+		}
+	}
+	return {
+		Coordinator: ConfiguredChatCoordinator,
+		Sandbox,
+		worker
+	};
 }
-export {
-  createCloudflareSandboxAgent
-};
-//# sourceMappingURL=factory.js.map
+//#endregion
+export { createCloudflareSandboxAgent };
+
+//# sourceMappingURL=factory.js.map

package/dist/esm/factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"factory.js","sources":["../../src/factory.ts"],"sourcesContent":["/**\n * `createCloudflareSandboxAgent` — the headline DX: one configured function call\n * returns the Durable Object coordinator, the Sandbox DO, and the Worker fetch\n * handler, so a Cloudflare app's whole `worker.ts` is just export wiring:\n *\n * ```ts\n * const agent = createCloudflareSandboxAgent({\n *   adapter: () => claudeCodeText('sonnet'),\n * })\n * export const RunCoordinator = agent.Coordinator\n * export const Sandbox = agent.Sandbox\n * export default agent.worker\n * ```\n *\n * Two modes, switched by `config.mode`:\n *  - `'do-drives'` (default) → a {@link ChatSandboxCoordinator}: the DO runs\n *    `chat()` itself and hosts the MCP tool-bridge.\n *  - `'colocated'` → a {@link ContainerSandboxCoordinator}: an in-container\n *    runner runs `chat()`; the DO is a thin coordinator that executes host tools.\n *\n * Env bindings (set in `wrangler.jsonc`):\n *  - `RUN_COORDINATOR` — this coordinator DO's own namespace (so the Worker can\n *    address it by `threadId`). Class name: whatever you export `Coordinator` as.\n *  - `Sandbox` — the `@cloudflare/sandbox` Sandbox DO namespace (the container\n *    hosts). Bind the exported `Sandbox` class.\n *  - `PUBLIC_HOSTNAME` — OPTIONAL. Hostname the CONTAINER uses to reach the Worker's\n *    tool-bridge / tool-exec endpoint. Unset → request-derived (local dev →\n *    `host.docker.internal`). See `resolveBridgeOrigin`.\n *  - `PREVIEW_HOSTNAME` — OPTIONAL. Custom domain (with a `*.<domain>` route) for\n *    browser-facing `exposePort` preview URLs. Unset → request-derived (local dev →\n *    `localhost`); REQUIRED on a `*.workers.dev` deploy, which has no wildcard\n *    subdomains. See `resolvePreviewHost`.\n *  - The harness's API key (`ANTHROPIC_API_KEY` for Claude Code, `CODEX_API_KEY` for\n *    codex, …) — supplied by YOUR app, never by the package. Declare it as a secret\n *    on the run's workspace (via a `sandbox`/`workspace` resolver) and add the field\n *    to your own env type; the coordinator injects each declared secret into the\n *    sandbox env by name. The package itself is harness-agnostic and binds no key.\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 { defineSandbox, defineWorkspace } from '@tanstack/ai-sandbox'\nimport { Sandbox } from '@cloudflare/sandbox'\nimport { cloudflareSandbox } from './provider'\nimport { ChatSandboxCoordinator } from './chat-coordinator'\nimport { ContainerSandboxCoordinator } from './container-coordinator'\nimport { createSandboxAgentWorker } from './worker'\nimport { resolvePreviewHost } from './coordinator'\nimport type { ChatCoordinatorEnv, ChatRunConfig } from './chat-coordinator'\nimport type {\n  ContainerCoordinatorEnv,\n  ContainerRunConfig,\n} from './container-coordinator'\nimport type { HarnessId } from './protocol'\nimport type { SandboxCoordinator, StartRunInput } from './coordinator'\nimport type { AnyTextAdapter, AnyTool, SystemPrompt } from '@tanstack/ai'\nimport type {\n  SandboxDefinition,\n  WorkspaceDefinition,\n} from '@tanstack/ai-sandbox'\n\n/**\n * The base Env every generated app binds: the coordinator's own namespace, the\n * Sandbox namespace, the OPTIONAL bridge/preview hostnames (request-derived when\n * unset), and the Anthropic key. The two modes extend this with exactly the\n * coordinator base each one requires.\n */\nexport interface SandboxAgentEnv\n  extends ChatCoordinatorEnv, ContainerCoordinatorEnv {\n  /** This coordinator DO's own namespace (so the Worker can address it). */\n  RUN_COORDINATOR: DurableObjectNamespace<SandboxCoordinator<SandboxAgentEnv>>\n  /**\n   * Custom domain (with a `*.<domain>` route) for browser-facing `exposePort`\n   * preview URLs. Optional: unset → request-derived (local dev → `localhost`).\n   * REQUIRED on a `*.workers.dev` deploy (no wildcard subdomains). Distinct from\n   * `PUBLIC_HOSTNAME`, which is the CONTAINER→Worker bridge host. See\n   * {@link resolvePreviewHost}.\n   */\n  PREVIEW_HOSTNAME?: string\n}\n\n/** Shared config across both modes. */\ninterface BaseAgentConfig<TEnv extends SandboxAgentEnv> {\n  /** chat()-provided server tools, resolved per run (DO-drives: bridged over MCP). */\n  tools?: (input: StartRunInput, env: TEnv) => Array<AnyTool>\n}\n\n/** DO-drives config: the DO runs `chat()` with the given adapter. */\nexport interface DoDrivesAgentConfig<\n  TEnv extends SandboxAgentEnv,\n> extends BaseAgentConfig<TEnv> {\n  mode?: 'do-drives'\n  /** The harness/text adapter `chat()` runs, resolved per run. */\n  adapter: (input: StartRunInput, env: TEnv) => AnyTextAdapter\n  /**\n   * Base system prompts prepended to every run's `chat()` (DO-drives only — the DO\n   * runs `chat()` itself). The natural home for transport-level guidance the agent\n   * needs regardless of what it builds — e.g. `systemPrompts: [PREVIEW_GUIDANCE]`\n   * so previews don't reload-loop. See {@link PREVIEW_GUIDANCE}.\n   */\n  systemPrompts?: Array<SystemPrompt>\n  /**\n   * The sandbox the agent runs in, resolved per run. When omitted, a default\n   * Cloudflare sandbox (one per thread, no source clone, NO auth secrets) is built\n   * from the `Sandbox` binding and the resolved preview host, optionally\n   * bootstrapping `workspace`. Supply the harness's API key either here (a custom\n   * `sandbox` resolver whose workspace declares the secret) or via `workspace`\n   * below — the package binds no key of its own.\n   */\n  sandbox?: (input: StartRunInput, env: TEnv) => SandboxDefinition\n  /**\n   * Workspace for the default sandbox (ignored when `sandbox` is provided). This is\n   * where a default-sandbox app declares its harness auth, e.g.\n   * `defineWorkspace({ source: { type: 'none' }, secrets: createSecrets({ ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY }) })`.\n   */\n  workspace?: WorkspaceDefinition\n}\n\n/** Co-located config: an in-container runner runs `chat()`. */\nexport interface ColocatedAgentConfig<\n  TEnv extends SandboxAgentEnv,\n> extends BaseAgentConfig<TEnv> {\n  mode: 'colocated'\n  /** Which in-sandbox harness the runner spawns. */\n  harness: HarnessId\n  /** Model id passed to that harness. */\n  model: string\n  /** Workspace the in-container runner bootstraps for the agent. */\n  workspace: WorkspaceDefinition\n}\n\nexport type CloudflareSandboxAgentConfig<TEnv extends SandboxAgentEnv> =\n  | DoDrivesAgentConfig<TEnv>\n  | ColocatedAgentConfig<TEnv>\n\n/** What {@link createCloudflareSandboxAgent} returns: the app's whole worker. */\nexport interface CloudflareSandboxAgent<TEnv extends SandboxAgentEnv> {\n  /** The coordinator Durable Object class — export as your `RUN_COORDINATOR` binding. */\n  Coordinator: new (\n    ctx: DurableObjectState,\n    env: TEnv,\n  ) => SandboxCoordinator<TEnv>\n  /** The `@cloudflare/sandbox` Sandbox DO class — export for the `Sandbox` binding. */\n  Sandbox: typeof Sandbox\n  /** The Worker fetch handler — `export default` it. */\n  worker: ExportedHandler<TEnv>\n}\n\n/** Build the default per-thread Cloudflare sandbox for the DO-drives mode. */\nfunction defaultSandbox<TEnv extends SandboxAgentEnv>(\n  env: TEnv,\n  input: StartRunInput,\n  workspace: WorkspaceDefinition | undefined,\n): SandboxDefinition {\n  return defineSandbox({\n    id: 'cf-edge-agent',\n    provider: cloudflareSandbox({\n      binding: env.Sandbox,\n      // Browser-facing preview host: `PREVIEW_HOSTNAME` if set, else derived from\n      // the trigger request (local dev → `localhost`; deployed → a custom domain,\n      // since `*.workers.dev` has no wildcard). See `resolvePreviewHost`.\n      previewHostname: resolvePreviewHost(env, input),\n    }),\n    workspace:\n      workspace ??\n      // The container image ships the harness CLI; no source to clone, and NO auth\n      // secrets — the package is harness-agnostic, so it can't know which key the\n      // CLI needs. Supply the harness's API key via a `workspace` with `secrets`\n      // (or a custom `sandbox` resolver), e.g.:\n      //   workspace: defineWorkspace({\n      //     source: { type: 'none' },\n      //     secrets: createSecrets({ ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY }),\n      //   })\n      defineWorkspace({ source: { type: 'none' } }),\n    // One sandbox per thread, so a follow-up run resumes the same workspace.\n    lifecycle: { reuse: 'thread' },\n  })\n}\n\n/** Resolve the coordinator DO that owns a thread's runs (`RUN_COORDINATOR`). */\nfunction resolveCoordinator<TEnv extends SandboxAgentEnv>(\n  env: TEnv,\n  threadId: string,\n): DurableObjectStub<SandboxCoordinator<TEnv>> {\n  return env.RUN_COORDINATOR.get(env.RUN_COORDINATOR.idFromName(threadId))\n}\n\nexport function createCloudflareSandboxAgent<\n  TEnv extends SandboxAgentEnv = SandboxAgentEnv,\n>(config: CloudflareSandboxAgentConfig<TEnv>): CloudflareSandboxAgent<TEnv> {\n  const worker = createSandboxAgentWorker<TEnv>(resolveCoordinator)\n\n  if (config.mode === 'colocated') {\n    const colocated = config\n    class ConfiguredContainerCoordinator extends ContainerSandboxCoordinator<TEnv> {\n      protected override config(input: StartRunInput): ContainerRunConfig {\n        return {\n          hostTools: colocated.tools?.(input, this.env) ?? [],\n          workspace: colocated.workspace,\n          harness: colocated.harness,\n          model: colocated.model,\n        }\n      }\n    }\n    return { Coordinator: ConfiguredContainerCoordinator, Sandbox, worker }\n  }\n\n  const doDrives = config\n  class ConfiguredChatCoordinator extends ChatSandboxCoordinator<TEnv> {\n    protected override config(input: StartRunInput): ChatRunConfig {\n      const tools = doDrives.tools?.(input, this.env)\n      return {\n        adapter: doDrives.adapter(input, this.env),\n        sandbox:\n          doDrives.sandbox?.(input, this.env) ??\n          defaultSandbox(this.env, input, doDrives.workspace),\n        ...(tools !== undefined ? { tools } : {}),\n        ...(doDrives.systemPrompts !== undefined\n          ? { systemPrompts: doDrives.systemPrompts }\n          : {}),\n      }\n    }\n  }\n  return { Coordinator: ConfiguredChatCoordinator, Sandbox, worker }\n}\n"],"names":[],"mappings":";;;;;;;;;AAqJA,SAAS,eACP,KACA,OACA,WACmB;AACnB,SAAO,cAAc;AAAA,IACnB,IAAI;AAAA,IACJ,UAAU,kBAAkB;AAAA,MAC1B,SAAS,IAAI;AAAA;AAAA;AAAA;AAAA,MAIb,iBAAiB,mBAAmB,KAAK,KAAK;AAAA,IAAA,CAC/C;AAAA,IACD,WACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IASA,gBAAgB,EAAE,QAAQ,EAAE,MAAM,OAAA,GAAU;AAAA;AAAA,IAE9C,WAAW,EAAE,OAAO,SAAA;AAAA,EAAS,CAC9B;AACH;AAGA,SAAS,mBACP,KACA,UAC6C;AAC7C,SAAO,IAAI,gBAAgB,IAAI,IAAI,gBAAgB,WAAW,QAAQ,CAAC;AACzE;AAEO,SAAS,6BAEd,QAA0E;AAC1E,QAAM,SAAS,yBAA+B,kBAAkB;AAEhE,MAAI,OAAO,SAAS,aAAa;AAC/B,UAAM,YAAY;AAAA,IAClB,MAAM,uCAAuC,4BAAkC;AAAA,MAC1D,OAAO,OAA0C;AAClE,eAAO;AAAA,UACL,WAAW,UAAU,QAAQ,OAAO,KAAK,GAAG,KAAK,CAAA;AAAA,UACjD,WAAW,UAAU;AAAA,UACrB,SAAS,UAAU;AAAA,UACnB,OAAO,UAAU;AAAA,QAAA;AAAA,MAErB;AAAA,IAAA;AAEF,WAAO,EAAE,aAAa,gCAAgC,SAAS,OAAA;AAAA,EACjE;AAEA,QAAM,WAAW;AAAA,EACjB,MAAM,kCAAkC,uBAA6B;AAAA,IAChD,OAAO,OAAqC;AAC7D,YAAM,QAAQ,SAAS,QAAQ,OAAO,KAAK,GAAG;AAC9C,aAAO;AAAA,QACL,SAAS,SAAS,QAAQ,OAAO,KAAK,GAAG;AAAA,QACzC,SACE,SAAS,UAAU,OAAO,KAAK,GAAG,KAClC,eAAe,KAAK,KAAK,OAAO,SAAS,SAAS;AAAA,QACpD,GAAI,UAAU,SAAY,EAAE,MAAA,IAAU,CAAA;AAAA,QACtC,GAAI,SAAS,kBAAkB,SAC3B,EAAE,eAAe,SAAS,kBAC1B,CAAA;AAAA,MAAC;AAAA,IAET;AAAA,EAAA;AAEF,SAAO,EAAE,aAAa,2BAA2B,SAAS,OAAA;AAC5D;"}
+{"version":3,"file":"factory.js","names":[],"sources":["../../src/factory.ts"],"sourcesContent":["/**\n * `createCloudflareSandboxAgent` — the headline DX: one configured function call\n * returns the Durable Object coordinator, the Sandbox DO, and the Worker fetch\n * handler, so a Cloudflare app's whole `worker.ts` is just export wiring:\n *\n * ```ts\n * const agent = createCloudflareSandboxAgent({\n *   adapter: () => claudeCodeText('sonnet'),\n * })\n * export const RunCoordinator = agent.Coordinator\n * export const Sandbox = agent.Sandbox\n * export default agent.worker\n * ```\n *\n * Two modes, switched by `config.mode`:\n *  - `'do-drives'` (default) → a {@link ChatSandboxCoordinator}: the DO runs\n *    `chat()` itself and hosts the MCP tool-bridge.\n *  - `'colocated'` → a {@link ContainerSandboxCoordinator}: an in-container\n *    runner runs `chat()`; the DO is a thin coordinator that executes host tools.\n *\n * Env bindings (set in `wrangler.jsonc`):\n *  - `RUN_COORDINATOR` — this coordinator DO's own namespace (so the Worker can\n *    address it by `threadId`). Class name: whatever you export `Coordinator` as.\n *  - `Sandbox` — the `@cloudflare/sandbox` Sandbox DO namespace (the container\n *    hosts). Bind the exported `Sandbox` class.\n *  - `PUBLIC_HOSTNAME` — OPTIONAL. Hostname the CONTAINER uses to reach the Worker's\n *    tool-bridge / tool-exec endpoint. Unset → request-derived (local dev →\n *    `host.docker.internal`). See `resolveBridgeOrigin`.\n *  - `PREVIEW_HOSTNAME` — OPTIONAL. Custom domain (with a `*.<domain>` route) for\n *    browser-facing `exposePort` preview URLs. Unset → request-derived (local dev →\n *    `localhost`); REQUIRED on a `*.workers.dev` deploy, which has no wildcard\n *    subdomains. See `resolvePreviewHost`.\n *  - The harness's API key (`ANTHROPIC_API_KEY` for Claude Code, `CODEX_API_KEY` for\n *    codex, …) — supplied by YOUR app, never by the package. Declare it as a secret\n *    on the run's workspace (via a `sandbox`/`workspace` resolver) and add the field\n *    to your own env type; the coordinator injects each declared secret into the\n *    sandbox env by name. The package itself is harness-agnostic and binds no key.\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 { defineSandbox, defineWorkspace } from '@tanstack/ai-sandbox'\nimport { Sandbox } from '@cloudflare/sandbox'\nimport { cloudflareSandbox } from './provider'\nimport { ChatSandboxCoordinator } from './chat-coordinator'\nimport { ContainerSandboxCoordinator } from './container-coordinator'\nimport { createSandboxAgentWorker } from './worker'\nimport { resolvePreviewHost } from './coordinator'\nimport type { ChatCoordinatorEnv, ChatRunConfig } from './chat-coordinator'\nimport type {\n  ContainerCoordinatorEnv,\n  ContainerRunConfig,\n} from './container-coordinator'\nimport type { HarnessId } from './protocol'\nimport type { SandboxCoordinator, StartRunInput } from './coordinator'\nimport type { AnyTextAdapter, AnyTool, SystemPrompt } from '@tanstack/ai'\nimport type {\n  SandboxDefinition,\n  WorkspaceDefinition,\n} from '@tanstack/ai-sandbox'\n\n/**\n * The base Env every generated app binds: the coordinator's own namespace, the\n * Sandbox namespace, the OPTIONAL bridge/preview hostnames (request-derived when\n * unset), and the Anthropic key. The two modes extend this with exactly the\n * coordinator base each one requires.\n */\nexport interface SandboxAgentEnv\n  extends ChatCoordinatorEnv, ContainerCoordinatorEnv {\n  /** This coordinator DO's own namespace (so the Worker can address it). */\n  RUN_COORDINATOR: DurableObjectNamespace<SandboxCoordinator<SandboxAgentEnv>>\n  /**\n   * Custom domain (with a `*.<domain>` route) for browser-facing `exposePort`\n   * preview URLs. Optional: unset → request-derived (local dev → `localhost`).\n   * REQUIRED on a `*.workers.dev` deploy (no wildcard subdomains). Distinct from\n   * `PUBLIC_HOSTNAME`, which is the CONTAINER→Worker bridge host. See\n   * {@link resolvePreviewHost}.\n   */\n  PREVIEW_HOSTNAME?: string\n}\n\n/** Shared config across both modes. */\ninterface BaseAgentConfig<TEnv extends SandboxAgentEnv> {\n  /** chat()-provided server tools, resolved per run (DO-drives: bridged over MCP). */\n  tools?: (input: StartRunInput, env: TEnv) => Array<AnyTool>\n}\n\n/** DO-drives config: the DO runs `chat()` with the given adapter. */\nexport interface DoDrivesAgentConfig<\n  TEnv extends SandboxAgentEnv,\n> extends BaseAgentConfig<TEnv> {\n  mode?: 'do-drives'\n  /** The harness/text adapter `chat()` runs, resolved per run. */\n  adapter: (input: StartRunInput, env: TEnv) => AnyTextAdapter\n  /**\n   * Base system prompts prepended to every run's `chat()` (DO-drives only — the DO\n   * runs `chat()` itself). The natural home for transport-level guidance the agent\n   * needs regardless of what it builds — e.g. `systemPrompts: [PREVIEW_GUIDANCE]`\n   * so previews don't reload-loop. See {@link PREVIEW_GUIDANCE}.\n   */\n  systemPrompts?: Array<SystemPrompt>\n  /**\n   * The sandbox the agent runs in, resolved per run. When omitted, a default\n   * Cloudflare sandbox (one per thread, no source clone, NO auth secrets) is built\n   * from the `Sandbox` binding and the resolved preview host, optionally\n   * bootstrapping `workspace`. Supply the harness's API key either here (a custom\n   * `sandbox` resolver whose workspace declares the secret) or via `workspace`\n   * below — the package binds no key of its own.\n   */\n  sandbox?: (input: StartRunInput, env: TEnv) => SandboxDefinition\n  /**\n   * Workspace for the default sandbox (ignored when `sandbox` is provided). This is\n   * where a default-sandbox app declares its harness auth, e.g.\n   * `defineWorkspace({ source: { type: 'none' }, secrets: createSecrets({ ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY }) })`.\n   */\n  workspace?: WorkspaceDefinition\n}\n\n/** Co-located config: an in-container runner runs `chat()`. */\nexport interface ColocatedAgentConfig<\n  TEnv extends SandboxAgentEnv,\n> extends BaseAgentConfig<TEnv> {\n  mode: 'colocated'\n  /** Which in-sandbox harness the runner spawns. */\n  harness: HarnessId\n  /** Model id passed to that harness. */\n  model: string\n  /** Workspace the in-container runner bootstraps for the agent. */\n  workspace: WorkspaceDefinition\n}\n\nexport type CloudflareSandboxAgentConfig<TEnv extends SandboxAgentEnv> =\n  | DoDrivesAgentConfig<TEnv>\n  | ColocatedAgentConfig<TEnv>\n\n/** What {@link createCloudflareSandboxAgent} returns: the app's whole worker. */\nexport interface CloudflareSandboxAgent<TEnv extends SandboxAgentEnv> {\n  /** The coordinator Durable Object class — export as your `RUN_COORDINATOR` binding. */\n  Coordinator: new (\n    ctx: DurableObjectState,\n    env: TEnv,\n  ) => SandboxCoordinator<TEnv>\n  /** The `@cloudflare/sandbox` Sandbox DO class — export for the `Sandbox` binding. */\n  Sandbox: typeof Sandbox\n  /** The Worker fetch handler — `export default` it. */\n  worker: ExportedHandler<TEnv>\n}\n\n/** Build the default per-thread Cloudflare sandbox for the DO-drives mode. */\nfunction defaultSandbox<TEnv extends SandboxAgentEnv>(\n  env: TEnv,\n  input: StartRunInput,\n  workspace: WorkspaceDefinition | undefined,\n): SandboxDefinition {\n  return defineSandbox({\n    id: 'cf-edge-agent',\n    provider: cloudflareSandbox({\n      binding: env.Sandbox,\n      // Browser-facing preview host: `PREVIEW_HOSTNAME` if set, else derived from\n      // the trigger request (local dev → `localhost`; deployed → a custom domain,\n      // since `*.workers.dev` has no wildcard). See `resolvePreviewHost`.\n      previewHostname: resolvePreviewHost(env, input),\n    }),\n    workspace:\n      workspace ??\n      // The container image ships the harness CLI; no source to clone, and NO auth\n      // secrets — the package is harness-agnostic, so it can't know which key the\n      // CLI needs. Supply the harness's API key via a `workspace` with `secrets`\n      // (or a custom `sandbox` resolver), e.g.:\n      //   workspace: defineWorkspace({\n      //     source: { type: 'none' },\n      //     secrets: createSecrets({ ANTHROPIC_API_KEY: env.ANTHROPIC_API_KEY }),\n      //   })\n      defineWorkspace({ source: { type: 'none' } }),\n    // One sandbox per thread, so a follow-up run resumes the same workspace.\n    lifecycle: { reuse: 'thread' },\n  })\n}\n\n/** Resolve the coordinator DO that owns a thread's runs (`RUN_COORDINATOR`). */\nfunction resolveCoordinator<TEnv extends SandboxAgentEnv>(\n  env: TEnv,\n  threadId: string,\n): DurableObjectStub<SandboxCoordinator<TEnv>> {\n  return env.RUN_COORDINATOR.get(env.RUN_COORDINATOR.idFromName(threadId))\n}\n\nexport function createCloudflareSandboxAgent<\n  TEnv extends SandboxAgentEnv = SandboxAgentEnv,\n>(config: CloudflareSandboxAgentConfig<TEnv>): CloudflareSandboxAgent<TEnv> {\n  const worker = createSandboxAgentWorker<TEnv>(resolveCoordinator)\n\n  if (config.mode === 'colocated') {\n    const colocated = config\n    class ConfiguredContainerCoordinator extends ContainerSandboxCoordinator<TEnv> {\n      protected override config(input: StartRunInput): ContainerRunConfig {\n        return {\n          hostTools: colocated.tools?.(input, this.env) ?? [],\n          workspace: colocated.workspace,\n          harness: colocated.harness,\n          model: colocated.model,\n        }\n      }\n    }\n    return { Coordinator: ConfiguredContainerCoordinator, Sandbox, worker }\n  }\n\n  const doDrives = config\n  class ConfiguredChatCoordinator extends ChatSandboxCoordinator<TEnv> {\n    protected override config(input: StartRunInput): ChatRunConfig {\n      const tools = doDrives.tools?.(input, this.env)\n      return {\n        adapter: doDrives.adapter(input, this.env),\n        sandbox:\n          doDrives.sandbox?.(input, this.env) ??\n          defaultSandbox(this.env, input, doDrives.workspace),\n        ...(tools !== undefined ? { tools } : {}),\n        ...(doDrives.systemPrompts !== undefined\n          ? { systemPrompts: doDrives.systemPrompts }\n          : {}),\n      }\n    }\n  }\n  return { Coordinator: ConfiguredChatCoordinator, Sandbox, worker }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAqJA,SAAS,eACP,KACA,OACA,WACmB;CACnB,OAAO,cAAc;EACnB,IAAI;EACJ,UAAU,kBAAkB;GAC1B,SAAS,IAAI;GAIb,iBAAiB,mBAAmB,KAAK,KAAK;EAChD,CAAC;EACD,WACE,aASA,gBAAgB,EAAE,QAAQ,EAAE,MAAM,OAAO,EAAE,CAAC;EAE9C,WAAW,EAAE,OAAO,SAAS;CAC/B,CAAC;AACH;;AAGA,SAAS,mBACP,KACA,UAC6C;CAC7C,OAAO,IAAI,gBAAgB,IAAI,IAAI,gBAAgB,WAAW,QAAQ,CAAC;AACzE;AAEA,SAAgB,6BAEd,QAA0E;CAC1E,MAAM,SAAS,yBAA+B,kBAAkB;CAEhE,IAAI,OAAO,SAAS,aAAa;EAC/B,MAAM,YAAY;EAClB,MAAM,uCAAuC,4BAAkC;GAC7E,OAA0B,OAA0C;IAClE,OAAO;KACL,WAAW,UAAU,QAAQ,OAAO,KAAK,GAAG,KAAK,CAAC;KAClD,WAAW,UAAU;KACrB,SAAS,UAAU;KACnB,OAAO,UAAU;IACnB;GACF;EACF;EACA,OAAO;GAAE,aAAa;GAAgC;GAAS;EAAO;CACxE;CAEA,MAAM,WAAW;CACjB,MAAM,kCAAkC,uBAA6B;EACnE,OAA0B,OAAqC;GAC7D,MAAM,QAAQ,SAAS,QAAQ,OAAO,KAAK,GAAG;GAC9C,OAAO;IACL,SAAS,SAAS,QAAQ,OAAO,KAAK,GAAG;IACzC,SACE,SAAS,UAAU,OAAO,KAAK,GAAG,KAClC,eAAe,KAAK,KAAK,OAAO,SAAS,SAAS;IACpD,GAAI,UAAU,KAAA,IAAY,EAAE,MAAM,IAAI,CAAC;IACvC,GAAI,SAAS,kBAAkB,KAAA,IAC3B,EAAE,eAAe,SAAS,cAAc,IACxC,CAAC;GACP;EACF;CACF;CACA,OAAO;EAAE,aAAa;EAA2B;EAAS;CAAO;AACnE"}

package/dist/esm/handle.js

@@ -1,208 +1,210 @@
 import { createExecBackedGit } from "@tanstack/ai-sandbox";
-const CLOUDFLARE_CAPS = {
-  fs: true,
-  exec: true,
-  env: true,
-  ports: true,
-  backgroundProcesses: true,
-  // No writable host→process stdin; stdin-fed harnesses use file-redirection.
-  writableStdin: false,
-  snapshots: false,
-  networkPolicy: false,
-  durableFilesystem: false,
-  fork: false
+//#region src/handle.ts
+/**
+* SandboxHandle backed by a Cloudflare Sandbox (Containers + Durable Objects),
+* via `@cloudflare/sandbox`. Runs at the edge inside a Worker.
+*
+* fs is implemented over `exec` with base64 piping (binary-safe), matching the
+* Docker provider. The container disk is EPHEMERAL (wiped to the image on
+* restart) and snapshots are not yet GA, so `capabilities.snapshots` and
+* `durableFilesystem` are false — `withSandbox` re-bootstraps under the same
+* identity across cold starts.
+*
+* LIMITATION: Cloudflare background processes do not expose a writable host→
+* process stdin, so `spawn().stdin.write` throws. This is advertised via
+* `capabilities.writableStdin: false`; harness adapters that feed a prompt over
+* stdin (e.g. the Claude Code adapter) detect this and instead deliver the
+* prompt via a file + shell stdin-redirection (`claude -p … < file`), which the
+* in-container shell handles with no host-side stdin write. `exec` (one-shot)
+* and streamed stdout from `spawn` both work fully.
+*
+* NOTE: not runtime-verified in this repo (requires a Workers runtime); it
+* compiles against the real `@cloudflare/sandbox` types and follows the proven
+* provider contract.
+*/
+var CLOUDFLARE_CAPS = {
+	fs: true,
+	exec: true,
+	env: true,
+	ports: true,
+	backgroundProcesses: true,
+	writableStdin: false,
+	killableProcesses: false,
+	snapshots: false,
+	networkPolicy: false,
+	durableFilesystem: false,
+	fork: false
 };
+/** POSIX single-quote escape for embedding paths in `sh -c`. */
 function q(value) {
-  return `'${value.replace(/'/g, `'\\''`)}'`;
+	return `'${value.replace(/'/g, `'\\''`)}'`;
 }
-class OutputQueue {
-  buffer = [];
-  waiters = [];
-  ended = false;
-  push(value) {
-    const waiter = this.waiters.shift();
-    if (waiter) waiter({ value, done: false });
-    else this.buffer.push(value);
-  }
-  end() {
-    this.ended = true;
-    let waiter = this.waiters.shift();
-    while (waiter) {
-      waiter({ value: void 0, done: true });
-      waiter = this.waiters.shift();
-    }
-  }
-  async *[Symbol.asyncIterator]() {
-    while (!this.ended || this.buffer.length > 0) {
-      if (this.buffer.length > 0) {
-        yield this.buffer.shift();
-        continue;
-      }
-      const next = await new Promise(
-        (resolve) => this.waiters.push(resolve)
-      );
-      if (next.done) return;
-      yield next.value;
-    }
-  }
-}
-class CloudflareHandle {
-  id;
-  provider = "cloudflare";
-  workspaceRoot;
-  capabilities = CLOUDFLARE_CAPS;
-  fs;
-  git;
-  process;
-  ports;
-  env;
-  sandbox;
-  workdir;
-  previewHostname;
-  constructor(id, sandbox, workdir, previewHostname) {
-    this.id = id;
-    this.sandbox = sandbox;
-    this.workdir = workdir;
-    this.workspaceRoot = workdir;
-    this.previewHostname = previewHostname;
-    this.process = {
-      exec: (command, opts) => this.exec(command, opts),
-      spawn: (command, opts) => this.spawnProcess(command, opts)
-    };
-    this.fs = {
-      read: async (p) => {
-        const r = await this.exec(`base64 ${q(this.abs(p))}`);
-        if (r.exitCode !== 0) throw new Error(`read failed: ${r.stderr.trim()}`);
-        return Buffer.from(r.stdout, "base64").toString("utf8");
-      },
-      readBytes: async (p) => {
-        const r = await this.exec(`base64 ${q(this.abs(p))}`);
-        if (r.exitCode !== 0) throw new Error(`read failed: ${r.stderr.trim()}`);
-        return new Uint8Array(Buffer.from(r.stdout, "base64"));
-      },
-      write: async (p, data) => {
-        const abs = this.abs(p);
-        const b64 = Buffer.from(
-          typeof data === "string" ? Buffer.from(data, "utf8") : data
-        ).toString("base64");
-        const dir = abs.replace(/\/[^/]*$/, "") || "/";
-        const r = await this.exec(
-          `mkdir -p ${q(dir)} && printf %s ${q(b64)} | base64 -d > ${q(abs)}`
-        );
-        if (r.exitCode !== 0)
-          throw new Error(`write failed: ${r.stderr.trim()}`);
-      },
-      list: async (p) => {
-        const r = await this.exec(`ls -1Ap ${q(this.abs(p))}`);
-        if (r.exitCode !== 0) throw new Error(`list failed: ${r.stderr.trim()}`);
-        return r.stdout.split("\n").filter((line) => line.trim() !== "").map((entry) => {
-          const isDir = entry.endsWith("/");
-          const name = isDir ? entry.slice(0, -1) : entry;
-          return {
-            name,
-            path: `${p.replace(/\/$/, "")}/${name}`,
-            type: isDir ? "dir" : "file"
-          };
-        });
-      },
-      mkdir: async (p) => {
-        await this.exec(`mkdir -p ${q(this.abs(p))}`);
-      },
-      remove: async (p) => {
-        await this.exec(`rm -rf ${q(this.abs(p))}`);
-      },
-      rename: async (from, to) => {
-        await this.exec(`mv ${q(this.abs(from))} ${q(this.abs(to))}`);
-      },
-      exists: async (p) => {
-        const r = await this.exec(`test -e ${q(this.abs(p))}`);
-        return r.exitCode === 0;
-      }
-    };
-    this.git = createExecBackedGit(this.process, this.workdir);
-    this.ports = {
-      connect: (port) => this.connectPort(port)
-    };
-    this.env = {
-      set: (vars) => this.sandbox.setEnvVars(vars)
-    };
-  }
-  abs(p) {
-    if (this.workdir === "/workspace") return p;
-    if (p === "/workspace") return this.workdir;
-    if (p.startsWith("/workspace/")) {
-      return `${this.workdir}/${p.slice("/workspace/".length)}`;
-    }
-    return p;
-  }
-  async exec(command, opts) {
-    const result = await this.sandbox.exec(command, {
-      ...opts?.cwd ? { cwd: this.abs(opts.cwd) } : { cwd: this.workdir },
-      ...opts?.env ? { env: opts.env } : {}
-    });
-    return {
-      stdout: result.stdout,
-      stderr: result.stderr,
-      exitCode: result.exitCode
-    };
-  }
-  spawnProcess(command, opts) {
-    const stdout = new OutputQueue();
-    const stderr = new OutputQueue();
-    const settled = this.sandbox.exec(command, {
-      ...opts?.cwd ? { cwd: this.abs(opts.cwd) } : { cwd: this.workdir },
-      ...opts?.env ? { env: opts.env } : {},
-      stream: true,
-      onOutput: (stream, data) => {
-        if (stream === "stdout") stdout.push(data);
-        else stderr.push(data);
-      }
-    });
-    const exitPromise = settled.then(
-      (result) => {
-        stdout.end();
-        stderr.end();
-        return result.exitCode;
-      },
-      (error) => {
-        stdout.end();
-        stderr.end();
-        throw error;
-      }
-    );
-    return Promise.resolve({
-      pid: -1,
-      stdout,
-      stderr,
-      stdin: {
-        write: () => Promise.reject(
-          new Error(
-            "cloudflare: background processes do not expose stdin. Use exec(), or a stdin-capable provider (local-process / docker) for stdin-fed harnesses."
-          )
-        ),
-        end: () => Promise.resolve()
-      },
-      wait: () => exitPromise,
-      kill: () => Promise.resolve()
-    });
-  }
-  async connectPort(port) {
-    if (this.previewHostname === void 0) {
-      throw new Error(
-        "cloudflare: ports.connect requires a previewHostname. Pass previewHostname (your Worker request hostname) to cloudflareSandbox(...)."
-      );
-    }
-    const { url } = await this.sandbox.exposePort(port, {
-      hostname: this.previewHostname
-    });
-    return { url };
-  }
-  async destroy() {
-    await this.sandbox.destroy();
-  }
-}
-export {
-  CLOUDFLARE_CAPS,
-  CloudflareHandle
+/** A push-driven async string queue used to adapt CF's onOutput callback. */
+var OutputQueue = class {
+	buffer = [];
+	waiters = [];
+	ended = false;
+	push(value) {
+		const waiter = this.waiters.shift();
+		if (waiter) waiter({
+			value,
+			done: false
+		});
+		else this.buffer.push(value);
+	}
+	end() {
+		this.ended = true;
+		let waiter = this.waiters.shift();
+		while (waiter) {
+			waiter({
+				value: void 0,
+				done: true
+			});
+			waiter = this.waiters.shift();
+		}
+	}
+	async *[Symbol.asyncIterator]() {
+		while (!this.ended || this.buffer.length > 0) {
+			if (this.buffer.length > 0) {
+				yield this.buffer.shift();
+				continue;
+			}
+			const next = await new Promise((resolve) => this.waiters.push(resolve));
+			if (next.done) return;
+			yield next.value;
+		}
+	}
+};
+var CloudflareHandle = class {
+	id;
+	provider = "cloudflare";
+	workspaceRoot;
+	capabilities = CLOUDFLARE_CAPS;
+	fs;
+	git;
+	process;
+	ports;
+	env;
+	sandbox;
+	workdir;
+	previewHostname;
+	constructor(id, sandbox, workdir, previewHostname) {
+		this.id = id;
+		this.sandbox = sandbox;
+		this.workdir = workdir;
+		this.workspaceRoot = workdir;
+		this.previewHostname = previewHostname;
+		this.process = {
+			exec: (command, opts) => this.exec(command, opts),
+			spawn: (command, opts) => this.spawnProcess(command, opts)
+		};
+		this.fs = {
+			read: async (p) => {
+				const r = await this.exec(`base64 ${q(this.abs(p))}`);
+				if (r.exitCode !== 0) throw new Error(`read failed: ${r.stderr.trim()}`);
+				return Buffer.from(r.stdout, "base64").toString("utf8");
+			},
+			readBytes: async (p) => {
+				const r = await this.exec(`base64 ${q(this.abs(p))}`);
+				if (r.exitCode !== 0) throw new Error(`read failed: ${r.stderr.trim()}`);
+				return new Uint8Array(Buffer.from(r.stdout, "base64"));
+			},
+			write: async (p, data) => {
+				const abs = this.abs(p);
+				const b64 = Buffer.from(typeof data === "string" ? Buffer.from(data, "utf8") : data).toString("base64");
+				const dir = abs.replace(/\/[^/]*$/, "") || "/";
+				const r = await this.exec(`mkdir -p ${q(dir)} && printf %s ${q(b64)} | base64 -d > ${q(abs)}`);
+				if (r.exitCode !== 0) throw new Error(`write failed: ${r.stderr.trim()}`);
+			},
+			list: async (p) => {
+				const r = await this.exec(`ls -1Ap ${q(this.abs(p))}`);
+				if (r.exitCode !== 0) throw new Error(`list failed: ${r.stderr.trim()}`);
+				return r.stdout.split("\n").filter((line) => line.trim() !== "").map((entry) => {
+					const isDir = entry.endsWith("/");
+					const name = isDir ? entry.slice(0, -1) : entry;
+					return {
+						name,
+						path: `${p.replace(/\/$/, "")}/${name}`,
+						type: isDir ? "dir" : "file"
+					};
+				});
+			},
+			mkdir: async (p) => {
+				await this.exec(`mkdir -p ${q(this.abs(p))}`);
+			},
+			remove: async (p) => {
+				await this.exec(`rm -rf ${q(this.abs(p))}`);
+			},
+			rename: async (from, to) => {
+				await this.exec(`mv ${q(this.abs(from))} ${q(this.abs(to))}`);
+			},
+			exists: async (p) => {
+				return (await this.exec(`test -e ${q(this.abs(p))}`)).exitCode === 0;
+			}
+		};
+		this.git = createExecBackedGit(this.process, this.workdir);
+		this.ports = { connect: (port) => this.connectPort(port) };
+		this.env = { set: (vars) => this.sandbox.setEnvVars(vars) };
+	}
+	abs(p) {
+		if (this.workdir === "/workspace") return p;
+		if (p === "/workspace") return this.workdir;
+		if (p.startsWith("/workspace/")) return `${this.workdir}/${p.slice(11)}`;
+		return p;
+	}
+	async exec(command, opts) {
+		const result = await this.sandbox.exec(command, {
+			...opts?.cwd ? { cwd: this.abs(opts.cwd) } : { cwd: this.workdir },
+			...opts?.env ? { env: opts.env } : {}
+		});
+		return {
+			stdout: result.stdout,
+			stderr: result.stderr,
+			exitCode: result.exitCode
+		};
+	}
+	spawnProcess(command, opts) {
+		const stdout = new OutputQueue();
+		const stderr = new OutputQueue();
+		const exitPromise = this.sandbox.exec(command, {
+			...opts?.cwd ? { cwd: this.abs(opts.cwd) } : { cwd: this.workdir },
+			...opts?.env ? { env: opts.env } : {},
+			stream: true,
+			onOutput: (stream, data) => {
+				if (stream === "stdout") stdout.push(data);
+				else stderr.push(data);
+			}
+		}).then((result) => {
+			stdout.end();
+			stderr.end();
+			return result.exitCode;
+		}, (error) => {
+			stdout.end();
+			stderr.end();
+			throw error;
+		});
+		return Promise.resolve({
+			pid: -1,
+			stdout,
+			stderr,
+			stdin: {
+				write: () => Promise.reject(/* @__PURE__ */ new Error("cloudflare: background processes do not expose stdin. Use exec(), or a stdin-capable provider (local-process / docker) for stdin-fed harnesses.")),
+				end: () => Promise.resolve()
+			},
+			wait: () => exitPromise,
+			kill: () => Promise.resolve()
+		});
+	}
+	async connectPort(port) {
+		if (this.previewHostname === void 0) throw new Error("cloudflare: ports.connect requires a previewHostname. Pass previewHostname (your Worker request hostname) to cloudflareSandbox(...).");
+		const { url } = await this.sandbox.exposePort(port, { hostname: this.previewHostname });
+		return { url };
+	}
+	async destroy() {
+		await this.sandbox.destroy();
+	}
 };
-//# sourceMappingURL=handle.js.map
+//#endregion
+export { CLOUDFLARE_CAPS, CloudflareHandle };
+
+//# sourceMappingURL=handle.js.map