Add Cloudflare sandbox provider plugin (#5687)

> _Stacked on top of #5685 → #5686. Diff against master includes commits
from earlier PRs in the stack — review focuses on the two new commits
(`Extend sandbox callback bridge for Worker-hosted plugins` + `Add
Cloudflare sandbox provider plugin`)._

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies
> - Each agent runs in a sandbox environment, and operators choose which
provider backs that sandbox — today E2B and Daytona are bundled with the
platform
> - Cloudflare Workers + Durable Objects + the Sandbox SDK offer a
credible new option: globally distributed, cheap idle, and
operator-deployable as a single Worker
> - To plug it in, Paperclip needs (a) a provider plugin that speaks the
`PaperclipPluginManifestV1` lifecycle and (b) a small operator-deployed
Worker — the **bridge** — that adapts Paperclip's runtime RPCs to the
Cloudflare Sandbox SDK
> - The plugin extends the existing sandbox-callback-bridge with a
`bridge.transport: "worker"` discriminator so the platform routes
runtime RPCs through the Worker bridge instead of the in-process runner
> - This pull request adds the plugin, the bridge Worker template, and
the supporting adapter-utils + server hooks the new transport needs
> - The benefit is that operators can run sandboxes on Cloudflare's edge
with no new platform code beyond installing the plugin and deploying the
Worker

## What Changed

**Shared support (`Extend sandbox callback bridge for Worker-hosted
plugins`):**

- `packages/adapter-utils/src/sandbox-callback-bridge.{ts,test.ts}`:
expose `expectedHostHeader` so plugin-side bridge clients can verify the
canonical request envelope before forwarding.
- `packages/adapter-utils/src/command-managed-runtime.{ts,test.ts}`:
relax the always-fresh runner construction so callers can re-use a
runner across exec calls (Worker-hosted bridges hold the runner inside a
Durable Object).
- `server/src/services/environment-runtime.ts` +
`environment-runtime.test.ts`: route Worker-hosted bridges through the
same env-shaping path as E2B and pin the `requestEnv` contract.
- `server/src/services/plugin-environment-driver.ts`: thread an optional
`issueId` through the runtime descriptor so bridges can scope leases to
the originating issue (used by Cloudflare to map a sandbox to the
issue/workflow for billing and audit).
- `packages/plugins/sdk/src/protocol.ts`: add `issueId?` to
`PluginEnvironmentDriverBaseParams` and the new `bridge.transport:
"worker"` discriminator that the new plugin declares.
- `server/__tests__/heartbeat-plugin-environment.test.ts`: pin the
heartbeat path against the new runtime descriptor.

**The Cloudflare plugin itself (`Add Cloudflare sandbox provider
plugin`):**

- `packages/plugins/sandbox-providers/cloudflare/`: plugin entry,
manifest, plugin runtime (lifecycle + bridge client), config parsing,
and Vitest coverage. Manifest declares `bridge.transport: "worker"` so
the platform routes runtime RPCs through the bridge client.
- `bridge-template/`: a Worker template the operator deploys with
`wrangler`. Owns Durable Object-backed sessions (`sessions.ts`),
exec/stream routes (`exec.ts`, `routes.ts`), and an HMAC auth layer
(`auth.ts`) that pins the `Host` header surface. Includes the
SDK-contract-correct exec implementation, lease recovery, and chunked
stdout/stderr streaming.
- Tests cover lease/session handoff (`bridge-template/src/exec.test.ts`,
`routes.test.ts`), bridge client request shaping
(`src/bridge-client.test.ts`), and end-to-end plugin behavior
(`src/plugin.test.ts`) including streamed exec output. 27 tests in
total.
- `README.md` walks the operator through deploying the bridge Worker,
registering the plugin, and configuring the runtime.

## Verification

- `pnpm typecheck`
- `pnpm exec vitest run --no-coverage
packages/adapter-utils/src/sandbox-callback-bridge.test.ts
packages/adapter-utils/src/command-managed-runtime.test.ts
server/src/__tests__/environment-runtime.test.ts
server/src/__tests__/heartbeat-plugin-environment.test.ts`
- `(cd packages/plugins/sandbox-providers/cloudflare && pnpm test)` — 27
passing

For an operator-side smoke test:

1. Deploy the bridge: `cd
packages/plugins/sandbox-providers/cloudflare/bridge-template &&
wrangler deploy`
2. Register the plugin in your Paperclip instance, point its bridge URL
at the deployed Worker, set the HMAC shared secret.
3. Create a sandbox environment whose provider is `cloudflare`, then run
a Codex or Claude job against it.

## Risks

- Adds a new `bridge.transport: "worker"` code path, but the existing
E2B / Daytona transports go through the same shaped helpers and have
explicit test coverage that pins their behavior unchanged.
- The Worker bridge stores session state in a Durable Object; operator
instances must be aware of the corresponding Cloudflare costs (DO
requests, storage). Documented in the README.
- The `issueId` plumbing is optional throughout — existing plugins that
don't supply it continue to work.

## Model Used

- Provider: Anthropic
- Model: Claude Opus 4.7 (1M context)
- Capabilities used: extended reasoning, tool use (Read/Edit/Bash/Grep)

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] If this change affects the UI, I have included before/after
screenshots — N/A, no UI change
- [x] I have updated relevant documentation to reflect my changes
(plugin README, bridge-template README)
- [x] I have considered and documented any risks above
- [x] I will address all Greptile and reviewer comments before
requesting merge

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>

packages/plugins/sandbox-providers/cloudflare/src/config.ts

@@ -0,0 +1,84 @@
+import type { CloudflareDriverConfig } from "./types.js";
+
+const DEFAULT_REQUESTED_CWD = "/workspace/paperclip";
+const DEFAULT_SLEEP_AFTER = "10m";
+const DEFAULT_TIMEOUT_MS = 300_000;
+const DEFAULT_BRIDGE_REQUEST_TIMEOUT_MS = 30_000;
+const LOCALHOST_HOSTNAMES = new Set(["localhost", "127.0.0.1", "::1"]);
+
+function readTrimmedString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function readBoolean(value: unknown, fallback: boolean): boolean {
+  return value === undefined ? fallback : value === true;
+}
+
+function readInteger(value: unknown, fallback: number): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? Math.trunc(parsed) : fallback;
+}
+
+function isLocalBridgeHost(url: URL): boolean {
+  return LOCALHOST_HOSTNAMES.has(url.hostname);
+}
+
+export function parseCloudflareDriverConfig(raw: Record<string, unknown>): CloudflareDriverConfig {
+  return {
+    bridgeBaseUrl: readTrimmedString(raw.bridgeBaseUrl) ?? "",
+    bridgeAuthToken: readTrimmedString(raw.bridgeAuthToken) ?? "",
+    reuseLease: readBoolean(raw.reuseLease, false),
+    keepAlive: readBoolean(raw.keepAlive, false),
+    sleepAfter: readTrimmedString(raw.sleepAfter) ?? DEFAULT_SLEEP_AFTER,
+    normalizeId: readBoolean(raw.normalizeId, true),
+    requestedCwd: readTrimmedString(raw.requestedCwd) ?? DEFAULT_REQUESTED_CWD,
+    sessionStrategy: raw.sessionStrategy === "default" ? "default" : "named",
+    sessionId: readTrimmedString(raw.sessionId) ?? "paperclip",
+    timeoutMs: readInteger(raw.timeoutMs, DEFAULT_TIMEOUT_MS),
+    bridgeRequestTimeoutMs: readInteger(raw.bridgeRequestTimeoutMs, DEFAULT_BRIDGE_REQUEST_TIMEOUT_MS),
+    previewHostname: readTrimmedString(raw.previewHostname),
+  };
+}
+
+export function validateCloudflareDriverConfig(config: CloudflareDriverConfig): string[] {
+  const errors: string[] = [];
+
+  if (!config.bridgeBaseUrl) {
+    errors.push("Cloudflare sandbox environments require bridgeBaseUrl.");
+  } else {
+    try {
+      const url = new URL(config.bridgeBaseUrl);
+      if (url.protocol !== "https:" && !(url.protocol === "http:" && isLocalBridgeHost(url))) {
+        errors.push("bridgeBaseUrl must use HTTPS unless it points at localhost.");
+      }
+    } catch {
+      errors.push("bridgeBaseUrl must be a valid URL.");
+    }
+  }
+
+  if (!config.bridgeAuthToken) {
+    errors.push("Cloudflare sandbox environments require bridgeAuthToken.");
+  }
+
+  if (config.reuseLease && !config.keepAlive) {
+    errors.push("reuseLease requires keepAlive for Cloudflare sandboxes.");
+  }
+
+  if (config.timeoutMs < 1 || config.timeoutMs > 86_400_000) {
+    errors.push("timeoutMs must be between 1 and 86400000.");
+  }
+
+  if (config.bridgeRequestTimeoutMs < 1 || config.bridgeRequestTimeoutMs > 86_400_000) {
+    errors.push("bridgeRequestTimeoutMs must be between 1 and 86400000.");
+  }
+
+  if (!config.requestedCwd.startsWith("/")) {
+    errors.push("requestedCwd must be an absolute POSIX path.");
+  }
+
+  if (config.sessionStrategy === "named" && config.sessionId.trim().length === 0) {
+    errors.push("sessionId is required when sessionStrategy is named.");
+  }
+
+  return errors;
+}