Unify the execution backends

[aron-cf]

The Workspace runtime routed an execution down one of two internal paths. Command backends — the just-bash worker-shell and the Cloudflare Container — went through a host shell facade that returned a ReadableStream handle with a result() method and bracketed every spawn with the sync push and pull frames. The JavaScript backend went through a separate module path that returned an event envelope. The runtime kept a set of command-backend ids and forked on it in four places — exec, getExec, killExec, disposeExec — to pick which path an execution took.

The split had outlived its reason. Both paths carried the same lifecycle: start an execution, stream its output, reattach, kill, dispose. What actually differed between backends was narrow — whether a backend accepts a structured input and returns a structured value, and whether it syncs against its own remote store. Neither needs two handle shapes or a routing fork. This change collapses everything onto one path.

flowchart TB
  subgraph Before
    R1[runtime.exec] -->|commandBackendIds fork| S[shell facade → ExecHandle]
    R1 -->|else| M[module handle → envelope]
    S --> W1[wrapCommandHandle]
    M --> W2[wrapModuleHandle]
  end
  subgraph After
    R2[runtime.exec] --> B[backendHandle id]
    B --> E[one envelope: id, events, sync]
    E --> W3[wrapModuleHandle]
  end

Loading

The work lands as five changes, each self-contained.

The first consolidates the terminal event. The JavaScript path used to emit a module's return value as its own result event, separate from the exit event that reported the code. A consumer had to collect both and correlate them to learn the outcome of one run, even though the runner produces the value and the code together and only on a zero exit. The value now rides the exit event as an optional field, and the standalone event is gone:

type ExecEvent =
  | { id: string; seq: number; name: "stdout"; value: Uint8Array }
  | { id: string; seq: number; name: "stderr"; value: Uint8Array }
  | { id: string; seq: number; name: "exit"; value: number; result?: unknown };

The second removes the waitUntil hook. DurableObjectState.waitUntil() has no effect on a durable object's lifetime — it exists for Workers-runtime API compatibility and does not extend how long the object stays resident. The JavaScript backend was the only consumer, and it used the hook to attach a detached execution's completion promise to the object lifetime, which did nothing. What actually keeps a run alive is ordinary pending work: the in-flight call into the Dynamic Worker and a consumer draining the event stream. The hook, the backend flag that required it, the connect-time guard, and the constructor guard all come out, and the workspace constructor no longer takes the option.

The third reshapes the wire. The shell RPC took a command field while the module path took a source field for the same argument — the program to run. Unifying the two behind one interface needs one name, so ShellRPC.exec now takes source and an optional input, and its event stream carries the consolidated exit:

exec(input: {
  source: string;        // shell command line, or module source for a callable backend
  cwd?: string;
  id?: string;
  input?: unknown;       // structured value for a callable backend; command backends ignore it
  env?: Record<string, string>;
  stdin?: Uint8Array;
}): Promise<{ id: string; events: ReadableStream<ExecEvent> }>;

With the wire reshaped, the fourth change collapses the runtime. Every backend is now presented to the runtime as one WorkspaceModuleBackendHandle: module backends return their native handle, and command backends are adapted from their executor. The sync bracket rides the envelope — the pre-exec push count is known when the envelope is built, and the post-drain pull outcome settles once the event stream ends — so the runtime's single result drain reports the pushed and pulled counts for every backend, and a sync: "none" backend simply reports zeroes.

interface ModuleExecutionEnvelope {
  id: string;
  events: ReadableStream<WorkspaceRuntimeEvent>;
  sync?: {
    pushed: number;
    outcome: Promise<{ applied: number; skipped: SkippedEntry[]; sync: ExecSyncResult }>;
  };
}

The four runtime forks become one path per method, wrapModuleHandle becomes the single wrapper for every backend, and the commandBackendIds set, the command handle wrapper, and the shell router are deleted. Transport-failure invalidation moves onto the adapter, which classifies a failed exec dispatch and a mid-stream event error the same way the router did.

The fifth change finishes the cleanup. Once every backend routed through the unified path, nothing in production called the shell facade's exec()/get() surface — the runtime consumes the envelope and drains the result itself. That surface, its handle wrapper, its per-stream utf8 transform, its result drain, and the ExecHandle and ExecResult types survived only because their tests kept them alive, and those tests covered code the runtime no longer runs. The class is reduced to a CommandExecutor whose exec/get return the raw event envelope plus the sync stats and whose kill/dispose forward to the wire. The executor tests move onto that envelope surface, and the encoding, result-accumulation, and cancellation-code coverage moves onto the runtime, where that logic now lives.

To verify the change end to end, boot the linux-x64 computerd binary and drive the reshaped wire and the sync bracket:

npm run build:bin --workspace @cloudflare/computerd
COMPUTERD_HARNESS_PORT=18080 bash packages/computer/test-harness/run-computerd.sh

Against that container, a push → exec → pull cycle stages a host file, runs a command that reads it and writes a new one, and pulls the container's write back — exercising the relocated sync bracket through the unified handle. The command's source drives the run and the exit code round-trips, confirming the wire reshape against the real binary.

The change was verified on three levels. The package unit suites cover the executor envelope surface, the runtime's encoding and result accumulation, and transport-failure invalidation. The stub soak harness confirms no disposal drift — the capnweb session settles to its baseline import and export counts after every phase, so the executor collapse leaks no stubs. The container harness confirms the wire and the sync bracket against a real FUSE-backed computerd.

Documentation moves with the code: the capnweb wire contract, the runtime lifecycle and worker backend notes, the isolate JavaScript guide, the runtime migration table, and the package and example READMEs all reflect the source field, the consolidated exit event, the removed hook, and the CommandExecutor.

One deviation from a pure interface merge is worth calling out for reviewers. The sync bracket stays inside the CommandExecutor and is adapted into the unified handle at the workspace, rather than being lifted into a separate workspace-level wrapper. The bracket and its push/pull accounting are convergence-critical and covered by the soak harness; reusing the executor's tested bracket keeps that behavior intact instead of rewriting it. The observable result is the same — one execution path, sync stats reported uniformly — but the bracket's home is the executor.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@cloudflare/computer@45

commit: 14774d4