mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-17 19:20:39 +09:00
486fb88a15
> _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>
97 lines
3.3 KiB
TypeScript
97 lines
3.3 KiB
TypeScript
import type { PaperclipPluginManifestV1 } from "@paperclipai/plugin-sdk";
|
|
|
|
const PLUGIN_ID = "paperclip.cloudflare-sandbox-provider";
|
|
const PLUGIN_VERSION = "0.1.0";
|
|
|
|
const manifest: PaperclipPluginManifestV1 = {
|
|
id: PLUGIN_ID,
|
|
apiVersion: 1,
|
|
version: PLUGIN_VERSION,
|
|
displayName: "Cloudflare Sandbox Provider",
|
|
description:
|
|
"First-party sandbox provider plugin that provisions Cloudflare sandboxes through an operator-deployed Worker bridge.",
|
|
author: "Paperclip",
|
|
categories: ["automation"],
|
|
capabilities: ["environment.drivers.register"],
|
|
entrypoints: {
|
|
worker: "./dist/worker.js",
|
|
},
|
|
environmentDrivers: [
|
|
{
|
|
driverKey: "cloudflare",
|
|
kind: "sandbox_provider",
|
|
displayName: "Cloudflare Sandbox",
|
|
description:
|
|
"Runs Paperclip sandbox environments through a Cloudflare Worker bridge backed by the Sandbox SDK and Durable Objects.",
|
|
configSchema: {
|
|
type: "object",
|
|
properties: {
|
|
bridgeBaseUrl: {
|
|
type: "string",
|
|
format: "uri",
|
|
description: "Base URL of the operator-deployed Cloudflare Worker bridge.",
|
|
},
|
|
bridgeAuthToken: {
|
|
type: "string",
|
|
format: "secret-ref",
|
|
description:
|
|
"Bearer token used by the provider plugin when calling the Cloudflare bridge. Pasted values are stored as company secrets.",
|
|
},
|
|
reuseLease: {
|
|
type: "boolean",
|
|
default: false,
|
|
description: "Reuse a sandbox by environment ID instead of creating one per run.",
|
|
},
|
|
keepAlive: {
|
|
type: "boolean",
|
|
default: false,
|
|
description: "Prevent Cloudflare from idling the container between requests.",
|
|
},
|
|
sleepAfter: {
|
|
type: "string",
|
|
default: "10m",
|
|
description: "Idle timeout passed to getSandbox(). Ignored when keepAlive is true.",
|
|
},
|
|
normalizeId: {
|
|
type: "boolean",
|
|
default: true,
|
|
description: "Lowercase and normalize sandbox IDs for operator-friendly naming.",
|
|
},
|
|
requestedCwd: {
|
|
type: "string",
|
|
default: "/workspace/paperclip",
|
|
description: "Workspace directory to create inside the sandbox lease.",
|
|
},
|
|
sessionStrategy: {
|
|
type: "string",
|
|
enum: ["named", "default"],
|
|
default: "named",
|
|
description: "Whether to run commands in a stable named session or the default session.",
|
|
},
|
|
sessionId: {
|
|
type: "string",
|
|
default: "paperclip",
|
|
description: "Named Cloudflare session ID used when sessionStrategy is named.",
|
|
},
|
|
timeoutMs: {
|
|
type: "number",
|
|
default: 300000,
|
|
description: "Default per-command timeout passed through to the bridge.",
|
|
},
|
|
bridgeRequestTimeoutMs: {
|
|
type: "number",
|
|
default: 30000,
|
|
description: "HTTP timeout for plugin-to-bridge requests.",
|
|
},
|
|
previewHostname: {
|
|
type: "string",
|
|
description: "Optional hostname reserved for future preview URL support.",
|
|
},
|
|
},
|
|
required: ["bridgeBaseUrl", "bridgeAuthToken"],
|
|
},
|
|
},
|
|
],
|
|
};
|
|
|
|
export default manifest;
|