Background Jobs

Background Jobs

Not implemented. Upstream's job lifecycle registry has no server-side provider in Edge.

Upstream reference: Background Jobs

What Upstream Provides

The jobs subsystem manages long-running producer work through ctx.jobs (JobRegistry). Producers own execution resources; the runtime owns identity, access control, and lifecycle state.

• JobRegistry (ctx.jobs) — abstract service with start(), list(), get(), read(), kill(), wait(). LocalJobRegistry is the process-local implementation.
• Producer contract — producers declare kind (bash, subagent), provide cancel() + done promise + optional readOutput() for streaming.
• Consumer view — JobSnapshot projections with status lifecycle: running → stopping → completed/killed/failed.
• Session integration — the apiproxy subscribes to onJobsChanged and broadcasts session/jobs frames over the mux channel.

Current Edge Status

Not implemented No dsh-jobs packages in dependencies. ctx.jobs is not available. No server-side job management exists.

The client-side UI plugin dsh-client-ui-jobs is included in the 33-plugin bundle — it renders job status panels and controls. But without a server-side JobRegistry, it has nothing to display.

Cloudflare Enablers

Cloudflare Product	What It Enables	Plan Requirement
DO alarms	Scheduled wake-ups for deferred work. Edge already uses these for WebSocket downlink expiry. Could schedule periodic job status checks or timeout enforcement.	Free plan
DO in-process execution	Short-lived jobs could run inside the DO's isolate directly — same approach as the current just-bash execution. Limited by Workers CPU time (30s free, 30min paid).	Free (30s) / Paid (30min)
Cloudflare Containers	Long-running jobs needing real processes (native builds, test suites, large file operations). A Container can run alongside the DO, coordinated via fetch. Full Linux environment.	Enterprise / Workers Paid (beta)

Architecture Gap

The gap is the JobRegistry provider, not the concept. Upstream's LocalJobRegistry manages in-memory state with process-scoped cleanup. Edge would need a DurableObjectJobRegistry that:

• Tracks job state in DO memory (same lifecycle as the DO activation)
• Persists job metadata to DO KV for cold-session recovery
• Delegates execution to the current shell backend (just-bash) for simple jobs, or Containers for heavy work
• Broadcasts session/jobs frames through the existing WebSocket downlink

The just-bash shell already runs commands synchronously in the DO. A job is essentially "a command that runs asynchronously with lifecycle tracking" — the execution engine exists, the lifecycle wrapper doesn't.

TODO

Evaluate JobRegistry with DO-backed state. The upstream JobRegistry is abstract — a DO-specific subclass could track jobs in DO memory with KV persistence for recovery. Short jobs use the existing just-bash engine; long jobs could use Containers (paid plan) when available. Start with DO-only jobs (free plan compatible) and add Container delegation as an upgrade path.