Skip to content

Latest commit

 

History

History
200 lines (164 loc) · 9.47 KB

AGENTS.md

File metadata and controls

200 lines (164 loc) · 9.47 KB

Agent guidelines

Read these first

  • README.md — what this repo is and how the pieces fit together.
  • CONTRIBUTING.md — public contribution paths.
  • COLLABORATORS.md — setup, checks, commit and pull request conventions. The canonical source for the day-to-day workflow.
  • docs/README.md — design specification. Forward- looking; treat as intent, not as a description of main.
  • docs/08_capnweb_interface.md — the RPC contract between the Durable Object and computerd. Required reading before touching packages/rpc or packages/computer.
  • Each package's own README.md — implementation status and package-specific notes.

Skills

In-repo skills live under .agents/skills/. Load the file directly when the trigger applies:

Skill Load when
prose Writing code comments, commit messages, READMEs, or documentation.
pull-requests Writing or editing a pull request description.
test-driven-development Implementing logic, fixing a bug, or changing behavior.
capnweb Touching anything that crosses the RPC boundary: packages/rpc, packages/computer, the computerd client, or the Durable Object server.
cloudflare Index of host-side Cloudflare skills — Workers, Durable Objects, wrangler, sandbox SDK, agents SDK.

Environment setup

A fresh container does not have everything the tests need. The traps below cost real time if you discover them one failure at a time.

Native build tools. packages/computerd depends on a vendored copy of fuse-napi at packages/computerd/vendor/fuse-napi, a native addon compiled from source on install. Building it needs a C toolchain and the libfuse 3 headers. On Debian or Ubuntu:

apt-get install build-essential pkg-config libfuse3-dev fuse3

Any libfuse 3 compiles. Kernel passthrough for local-only paths needs 3.17 or newer (Debian trixie); against an older one the addon builds without it and those paths are served by computerd instead.

If the addon build fails, npm install aborts the whole install, not just that one package. When you only need the rest of the workspace, install with npm install --ignore-scripts. That also skips the root postinstall, so run npm run build:types before building the examples, and build the addon yourself when you need it:

cd packages/computerd/vendor/fuse-napi && npx node-gyp rebuild

The binary build uses Docker. npm run build:bin compiles the addon for linux-x64 inside a node:22-trixie-slim container, so it works the same from an arm64 machine (through emulation, which is slow the first time; the result is cached under packages/computerd/dist/sea). Set COMPUTERD_FUSE_ADDON to a prebuilt fuse.node to skip that step.

remote-exec is Rust. packages/remote-exec builds a static Linux binary with Cargo, which needs Rust with both musl targets and capnp; its tests and @cloudflare/computer's npm run test:remote-exec need Linux. Nothing else in the workspace needs Rust, and the npm package doesn't ship the binary. packages/remote-exec/dev/run.sh runs any command in a Linux container that has everything.

Build before you test. The test scripts don't build the sibling packages first. Several suites need build output that is absent in a clean checkout: packages/computerd imports the sibling @cloudflare/dofs and @cloudflare/computer-rpc packages from their dist/ directories, packages/computerd's src/cli/computerd.test.ts spawns the bundled CLI at dist/cli/computerd.js, and examples/think-compare-runtimes imports @cloudflare/computer/backends/container-legacy, which exists only after the computer package is built. Run npm run build across the npm workspace before npm test on a clean checkout.

Real FUSE needs privilege. packages/computerd's src/cli/computerd.test.ts runs its real-FUSE case only when /dev/fuse is reachable; otherwise it resolves to the shim and skips. The guard is a bare existence check, so a mknod'd /dev/fuse in an unprivileged container defeats the skip and the mount then fails with EPERM, turning a clean skip into a hard failure. Leave the device absent unless the container is privileged (--privileged, or CAP_SYS_ADMIN with device access). The src/exec/runner.fuse.test.ts and src/fuse/passthrough.fuse.test.ts suites are separate: they skip unless both Docker and the prebuilt computerd binary are available, and run computerd inside a privileged container. See the debugging-computerd-fuse skill for the privileged Docker setup.

Checks before you finish

Run from the repo root:

npm run format        # oxfmt (rewrites files)
npm run check         # oxlint + oxfmt --check + sherif

npm run check must exit zero. Fix the underlying issue rather than silencing the rule.

Then run the package-level tests for whatever you touched:

npm test                                                  # whole workspace
npm test --workspace @cloudflare/dofs                     # one package
npm test --workspace @cloudflare/dofs -- src/foo.test.ts  # one file

Full details, including typecheck and build commands, are in COLLABORATORS.md.

Commits and pull requests

Follow COLLABORATORS.md. The short version:

  • One logical change per commit.
  • Imperative subject prefixed with the scope (dofs:, rpc:, computer:, computerd:, examples/think:, docs:, ci:). Multiple scopes joined with commas.
  • Self-contained body wrapped at 72 characters. No references to chat history, agent sessions, sibling commit SHAs, or task identifiers.
  • No emojis. No marketing voice. Prose paragraphs in the body, not bulleted lists.

Full guidance is in .agents/skills/prose/SKILL.md and .agents/skills/pull-requests/SKILL.md.

Changesets

Keep a changeset to one line. Link to the docs when they say more, and put longer upgrade steps there rather than in the changeset.

Scripts

Two top-level directories hold helper scripts. They're outside the npm workspace package set on purpose — they're tooling, not shipped code.

script/ holds maintainance scripts and operator-facing harnesses for computerd and the sync loop. Reach for these when you're chasing a behavior the unit tests don't cover.

  • shell boots a debian-slim container with the linux computerd binary mounted under /usr/local/bin. The starting point for anything that needs a real FUSE mount.
  • computerd-soak.mjs boots one computerd container, takes the host's part of the sync loop from a local store, and reports convergence lag beside container memory. Use it to chase convergence or churn bugs.
  • computerd-stub-soak.mjs soaks the long-lived WebSocket session and reads session.getStats() to detect stub-disposal drift. Run it for changes around the capnweb lifecycle.
  • computerd-fuse-flush.mjs end-to-end checks that the FUSE driver spills its in-memory write buffer into the backing VFS, so a capnweb-side pullOnce actually sees the bytes.
  • fs-tests.sh / run-fs-tests.sh run the filesystem conformance harness against the FUSE mount.
  • fs-bench.sh / run-fs-bench.sh benchmark common development tasks against the mount with a tmpfs baseline for comparison.
  • exec-tests boots computerd in docker with FUSE disabled and exercises a few shell.exec scenarios.
  • lib/cloudflare-workers-stub.mjs is a node --import hook that stubs the cloudflare:workers module, so a host-side script can import @cloudflare/computer's main entry outside workerd. Not runnable on its own; exec-tests uses it.
  • npm-bench.sh / run-npm-bench.sh benchmark npm package installs on native disk vs the FUSE mount. run-npm-bench.sh is the user-facing entry point that boots a privileged Docker container; run-npm-bench-inner.sh is the in-container entrypoint that installs dependencies, starts computerd, and invokes npm-bench.sh, which runs the actual benchmark. Set SCENARIOS, REPS, WARMUP, and OUTPUT_JSON to control what runs and where results land.

When you add a script, drop a one-line description at the top of the file and add it to the list above.

Project-specific patterns

  • RPC. The wire contract is capnweb. Read docs/08_capnweb_interface.md and the capnweb skill before changing anything that crosses the Durable Object ↔ computerd boundary. Stubs are object-capabilities; dispose them. Leaks are tracked by the harness in packages/rpc.
  • Storage. packages/dofs is the authoritative SQLite layer. Filesystem primitives operate on a Database handle; the sync protocol building blocks share the same handle. The package README enumerates the exported surface.
  • FUSE shim. packages/computerd runs in the sandbox container. FUSE- backed tests only run on Linux and are skipped elsewhere automatically.
  • Examples are real consumers. examples/think, examples/container-legacy, and examples/worker-shell exercise the public surface. If you change a public API, update them in the same change.