Hosted asynchronous plugin installation

Decision

Use Cloudflare Workflows for long hosted plugin mutations. Keep the local CLI and local server synchronous. Kafka and a separate task database are intentionally excluded: the repository already runs on Cloudflare, Workflows supply durable steps, retries, instance status, and retention, and the existing workspace Sandbox remains the only place that executes npm/plugin code.

Request flow

Studio POST /api/plugins/from-npm
  -> Studio gateway authenticates and checks plugins:install
  -> PLUGIN_INSTALL Workflow instance (taskId)
  -> 202 { taskId, status: "queued" }

Workflow
  -> acquire the existing workspace Sandbox
  -> call the existing POST /api/plugins/from-npm server route
  -> persist package inventory
  -> create the existing workspace backup
  -> write a durable Notification Center record
  -> broadcast notification.created over the existing realtime socket

The Workflow payload contains only bounded install input, workspace/project identifiers, and the requesting user id. It never stores the browser bearer token. Worker-to-worker calls reuse OCTONODE_CLOUD_INTERNAL_TOKEN and recheck that the user still belongs to the workspace.

Cost and capacity

• Keep the existing lite Sandbox and max_instances: 1 while there is no scale.
• Let the Sandbox sleep after five idle minutes instead of one hour.
• Use one Workflow binding; do not add Kafka, Queues, D1 task rows, or another container.
• Keep Studio submission single-flight and the Sandbox count at one. Add durable per-workspace admission control before supporting concurrent installs or raising max_instances.
• The intended production floor remains the Workers Paid plan (about $5/month before excess usage), leaving the current $10 development ceiling for light use.

Failure and idempotency

Workflow step replay is the retry authority. Install work is capped at two retries and ten minutes per attempt. The existing plugin install uses force/convergent file writes; package inventory and notification writes overwrite by stable task id. A completion notification is emitted only after inventory and backup succeed. A failed workflow writes a failure notification with a sanitized error message.

The first slice reuses the existing message notification kind with entity_type=plugin_install, avoiding a SQLite table migration for one task type. Add a first-class task notification kind when a second background job needs the same surface.

For the first slice, the Workflow instance and logs are the operator task monitor. A user-facing task status endpoint and exact npm-version pre-resolution are deferred until concurrent usage makes them useful.

Delivery plan

1. Add the Workflow binding, 202 response contract, secure internal calls, and focused gateway tests.
2. Persist completion/failure notifications and refresh Studio notifications/plugin queries over the existing realtime channel.
3. Run yarn gen, focused tests, Wrangler type generation, React Doctor, build, and the full test suite.
4. Later, if usage grows, add task-status UI, exact version pre-resolution, rate limits, and measured per-workspace concurrency. Kafka remains unnecessary unless tasks must span non-Cloudflare systems at high event volume.