computer: Add ws:container and pick exec backends with one option

[mattzcarey]

Stacked on #171. #181 and #182 were reviewed separately and merged into this branch.

An agent that wants both isolated JavaScript and a full Linux container has needed two exec backends, and the model had to choose one for every command. With this PR, JavaScript can be the only backend the model sees, and the container becomes a module JavaScript imports:

import { ContainerBackend, withWorkspaceContainer } from "@cloudflare/computer/backends/container";
import { createContainerModule } from "@cloudflare/computer/modules/container";
import { createAITools } from "@cloudflare/computer/tools/ai-sdk";

class Agent extends withWorkspaceContainer(class extends DurableObject<Env> {}) {
  workspace = new Workspace({
    storage: this.ctx.storage,
    backends: [
      new WorkerJavaScriptBackend({
        loader: this.env.LOADER,
        modules: { "ws:container": createContainerModule() },
      }),
      new ContainerBackend({
        container: () => this,
        workspace: { binding: "Agent", id: this.ctx.id.toString() },
        egress: { mode: "direct" },
      }),
    ],
  });

  getTools() {
    // Offer only JavaScript; the container is reached through ws:container.
    return createAITools({ workspace: this.workspace, exec: { "worker-javascript": {} } });
  }
}

import { exec } from "ws:container";

export default async function () {
  const { exitCode, stdout, stderr } = await exec("npm test", { cwd: "/workspace/app" });
  return { passed: exitCode === 0, stdout, stderr };
}

sequenceDiagram
  participant Model
  participant JS as worker-javascript isolate
  participant Mod as ws:container (host)
  participant RT as workspace.runtime
  participant C as ContainerBackend
  Model->>JS: exec tool, module source
  JS->>Mod: exec("npm test", { cwd })
  Mod->>RT: exec(command, { backend: "container-shell" })
  RT->>C: push Workspace changes, run command
  C-->>RT: output, exit code, pull changes
  RT-->>Mod: result
  Mod-->>JS: { exitCode, stdout, stderr }

Loading

ws:container. createContainerModule() is a host module factory (#170). It takes host.runtime when the JavaScript backend connects, and fails there if the Workspace has no such backend, or that backend's protocol is module, which would run shell text as JavaScript. runtime.backends() reports protocol for this, because callable only describes structured input. exec is a host call. Output arrives when the command finishes. Each stream keeps its last 2000 lines or maxOutputBytes (64 KiB by default); the runtime (#204) saves the rest to a Workspace file and exec returns truncated with its path, so a noisy command never sits whole in the Durable Object's memory. The timeout is capped at the host call deadline. Cancelling the JavaScript execution kills the command, arguments are parsed strictly, and exec refuses to run on a read-only backend.

The exec tool (#181). createAITools moves to @cloudflare/computer/tools/ai-sdk and takes exec, the backends the model can use keyed by id. Leaving exec out offers every backend. With several backends the model must name one on every call; there is no default. WorkerJavaScriptBackend describes its modules, and WorkerShellBackend and ContainerBackend describe themselves, so {} is enough per backend. shell stays as a deprecated alias. createPiTools and createTanStackTools (#191) take the same exec option.

This breaks import { createAITools } from "@cloudflare/computer/tools", released in 0.4.1: @cloudflare/computer/tools keeps the individual AI SDK create*Tool functions, and ExecBackendDescription becomes ExecBackendOptions.

Workspace clients (#182). A WorkspaceClient from getWorkspace() answers runtime.backends() from a frozen snapshot taken when the client is created, locally and over RPC. Tools built from the withWorkspace mixin, or from another Worker, then get the same exec tool as tools built from a Workspace the Durable Object owns.

On top of the new container runtime. #161 and #162 renamed the platform-scheduled backend to LegacyContainerBackend and added ContainerBackend, where the Durable Object schedules the container. This branch targets the new one:

• The container's self-description moves to ContainerBackend, with its network line following egress: direct, through a gateway, or none. LegacyContainerBackend is unchanged from main.
• ws:container no longer promises network access. In this setup the model only reads the module's text, and network access depends on the container backend's egress.
• examples/think and examples/mcp move from LegacyContainerBackend to ContainerBackend. Their containers blocks use scheduling_policy: "durable_object" with images.app, and the backend asks for standard-2 at launch, the size the old blocks requested. think now needs nothing beyond createAITools({ workspace: this.workspace }).
• docs/09_tool_interface.md, docs/17_isolate_javascript.md, and the changesets name ContainerBackend.

Unit tests cover the container module's argument parsing, timeout cap, kill on abort, read-only refusal, the connect-time backend check, and UTF-8 truncation, plus ContainerBackend's description for each egress mode. The script runner suite runs import { exec } from "ws:container" in a real Dynamic Worker against a real Workspace. The client tests send structured input through local and remote clients.

[changeset-bot]

🦋 Changeset detected

Latest commit: f153332

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@cloudflare/computer	Minor
@cloudflare/dofs	Minor
@cloudflare/computer-rpc	Minor
@cloudflare/computerd	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

Thanks for your interest in Cloudflare Computer.

This repository does not accept unsolicited pull requests. Please use one of the accepted contribution paths instead:

• Bug reports, regressions, and fix proposals: https://github.com/cloudflare/computer/issues/new/choose
• Feature requests, enhancements, and design proposals: https://github.com/cloudflare/computer/discussions

If a maintainer asked you to open this pull request, they can add the allow-pr label and reopen it.

[pkg-pr-new]

Open in StackBlitz

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

commit: f153332

[aron-cf]

@mattzcarey can you stack this on top of the trustedModules -> modules change. I can merge those now, would like to properly review this one.