rhema-cloudflare-code/specs/rhema-cloudflare-code.md

Handoff: implement rhema-cloudflare-code — the coding agent as a Cloudflare Durable Object

Handoff prompt for an implementation session. Everything needed is in this file; a fresh session will not have the conversation that produced it. Verified facts in §1 were established against this tree by compiling — re-verify only if the tree has moved since (git log, then the §1 checks).

0. Mission

Add a new frontend consumer of rhema-coding-agent (alongside rhema-code and rhema-acp) named rhema-cloudflare-code, under crates/. It runs the coding agent inside a Cloudflare Durable Object, with the agent's bash tool executing inside Cloudflare's Sandbox (https://developers.cloudflare.com/agents/tools/sandbox/ — a Durable Object-on-Container product: exec, file ops, idle sleep, persisted workspace).

Result: a WebSocket/HTTP-addressable coding agent whose sessions checkpoint into DO storage, whose workspace lives in the sandbox container, and which survives DO/container eviction via the engine's existing crash-resume machinery.

Non-goal: porting the terminal UI, the claw daemon, or the local-only provider stack to wasm. Non-goal v1: any provider adapter other than Anthropic.

1. Verified ground truth (already established; do not re-derive)

Verified in this tree with cargo check --target wasm32-unknown-unknown (add the target first: rustup target add wasm32-unknown-unknown; toolchain pinned at 1.98.1 in rust-toolchain.toml):

Compiles to wasm today, unchanged:

• rhema-core (deps: serde, serde_json, thiserror, async-trait only — no tokio, fs, threads, or time)
• rhema-provider (including the transport-agnostic SseDecoder in src/stream.rs, which consumes byte slices)
• rhema-transcript
• rhema-rsd, rhema-autonomous-agent, rhema-memory, rhema-config with --no-default-features (excludes the sqlite feature)

Does not compile to wasm, with exact reasons:

• rhema-agent-tools (and transitively rhema-subagents): crates/rhema-agent-tools/src/shell.rs:137 hardcodes tokio::process::Command::new("bash"), and the crate enables tokio's process/time features; mio does not build on wasm.
• rhema-provider-anthropic, two reqwest-on-wasm issues: (a) connect_timeout does not exist on wasm (provider.rs:70) — fetch has no socket knobs; (b) response.bytes_stream() (provider.rs:357) is backed by JS objects (Rc<RefCell<js_sys::futures::Inner>>) and therefore !Send, while #[async_trait] requires Send futures.

Why Send is non-negotiable: EventSink: Send (rhema-core/src/event.rs:80, reason documented at :78-79) — the sink reference crosses await points inside provider implementations. All JS-backed wasm-bindgen values are !Send by soundness (raw handles into the JS heap); this cannot be "fixed upstream". The fix is always bridging: run the !Send stream in wasm_bindgen_futures::spawn_local and forward plain Vec<u8> chunks over a channel whose receiver is Send on single-threaded wasm (plain data is trivially Send there). The async-compat crate packages exactly this pattern.

Runtime facts (workers): workerd gives wasm no owned event loop, no sockets, no filesystem, no Rust-side timers. All I/O goes through host bindings (fetch, DO storage, sandbox bindings). tokio::time sleeps do not fire inside workerd; use worker::Delay. reqwest-on-wasm has no streaming bodies worth using — do not attempt to keep it. rusqlite technically compiles on wasm but cannot open files in workerd — compile ≠ works.

Relevant existing seams (read these files first):

• rhema-core/src/provider.rs — ModelProvider::complete(&self, ModelRequest, &mut dyn EventSink) -> Result<ModelOutput, ProviderError>. IMPORTANT: ProviderError::is_retryable() parses the "... (HTTP <status>): ..." message shape — any new transport must keep adapters formatting errors that way, and must map transport failures to ProviderError::Other("network error: ...") (that prefix is what makes them retryable).
• rhema-provider/src/retry.rs — Retrying decorator: 3 attempts, 1 s base / 2 s cap, never retries once an event was emitted, retries an empty success. Sleeps via tokio::time (tests use start_paused; see retry.rs:320).
• rhema-agent-tools/src/shell.rs — ShellTools: the ONLY tool is bash ("reading, listing, and editing are shell work, not separate tools"). Output caps: 50 KiB / 2000 lines per stream (BASH_OUTPUT_LIMIT, BASH_OUTPUT_LINES); BASH_TIMEOUT = 120 s; approval consulted per call from pending: Mutex<Option<Arc<dyn Approval>>>; no hook installed = reject. ShellTools::builtin_specs() is the single source of truth for the tool spec, and the system-prompt renderer renders the same specs so the prompt and the request's tools array cannot drift — preserve this invariant.
• rhema-agent-tools/src/approval.rs — trait Approval: Send + Sync (+ AllowAll, DenyAll).
• rhema-coding-agent/src/agent.rs — the driver: owns one ShellTools for the agent lifetime, installs the per-turn approval hook, runs revive_dangling_calls on resume (committed-but-unanswered calls: replay-safe tools re-run, others reported interrupted), stamped_system(base, workspace, extra) assembles the system prompt (discovers skills from the global directory internally; sessions save/load via std::fs at agent.rs:233/238).
• rhema-core/src/session.rs — Session { history, driver_state: Value, cost_usd }: plain serde, checkpoint anywhere.
• rhema-core/src/tool.rs — ToolContext { cwd: PathBuf, run_id, cancelled: Arc<AtomicBool> }; ReplaySafety per tool.
• rhema-rsd/src/store.rs:117 — trait Store { load(key); save(record, expected_revision); keys() } — revision-guarded persistence over any store. A DO is the single writer per key, so the revision check can be maintained in-memory + persisted counter.
• AGENTS.md — conventions; summary in §5 below.

2. Target architecture

browser/editor client
   |  WebSocket (chat, streaming deltas, approval prompts) + HTTPS
   v
CodingAgent DO  (workers-rs, wasm32-unknown-unknown; one instance per session id)
   |- turn loop ........... rhema-coding-agent over rhema-core::run_turn
   |- step cost control ... rhema-transcript (on by default)
   |- provider ............ Anthropic Messages over host fetch (new transport)
   |- session checkpoints . DO SQLite storage (rev-guarded, rhema-rsd Store impl)
   |- approvals ........... DenyAll default; WS round-trip or per-session policy
   |- memory/subagents .... rhema-memory tools; subagents inherit the sandbox
   `- bash tool ........... -> Sandbox DO (same session name) over HTTP
                                `- container: bash -c in the workspace

One DO instance per session (idFromName(sessionId)), binding to the sandbox instance of the same name. Turn driving v1: the turn runs inside the client's live request while its WebSocket is connected (streaming deltas live); checkpoint the session after every step so any eviction resumes via revive_dangling_calls. Alarm-driven step queues are a v2 refinement.

3. Layout: one crate, strict module hygiene

The crate is crates/rhema-cloudflare-code/ (auto-added by the workspace's members = ["crates/*"]). Two families of modules, never mixed:

Platform-neutral modules (no wasm-bindgen, no worker, no fetch deps — host-side cargo test must compile and run them):

• sandbox — trait Sandbox (object-safe, async): exec(ExecRequest) -> streamed stdout/stderr lines + exit code (+ v1: workspace seed — git clone URL or tarball upload; file get/put if the skills flow needs it). ExecRequest carries command, cwd, timeout (echo the 120 s default), cancellation. ShellError maps transport failure so the bash tool result stays an in-band is_error result, never an abort.
• shell — ShellSandbox: the bash tool resolver (or the sandbox-side ShellExecutor impl for Phase 1's seam) exposing the SAME spec as ShellTools::builtin_specs() — reuse it verbatim (its description says "Requires user approval", which must stay true).
• assembly/config types — model id, api key source, approval policy, agent construction.
• Scripted Sandbox impl for offline tests (house pattern: rhema-core's mock feature), so the full turn loop tests host-side with rhema-core's MockProvider.
• Every platform-neutral module carries a module-level #![forbid(unsafe_code)]; the crate carries #![deny(missing_docs)].

The worker module (and ONLY it): the workers-rs glue — the #[durable_object] class CodingAgent, the host-fetch provider transport, the !Send bridge, the worker::Delay sleeper, the DO-storage impls (rhema-rsd::Store, rhema-memory::MemoryStore; prefer a SQLite-backed DO class — KV values cap at 128 KiB and sessions grow; record the workers-rs version you pin and why, it is 0.x and APIs move).

This module is why the crate cannot carry a crate-level #![forbid(unsafe_code)]: the #[durable_object] macro emits unsafe internally and forbid cannot be overridden by allow in inner scopes. Document that exception in src/lib.rs (precedent for sanctioned exceptions: vendor/crossterm is excluded for toolchain reasons).

4. Phased work plan

Phase 1 — shell seam in rhema-agent-tools (unblocks wasm + is the core abstraction)

• Extract the execution half of shell.rs into a seam, e.g. trait ShellExecutor: Send + Sync { async fn run(&self, command: &str, cwd: &Path, timeout: Duration, cancelled: &AtomicBool, progress: callback) -> Result<Executed, ShellError> } where Executed = stdout tail, stderr tail, exit code. ShellTools keeps: the spec, the approval gate, caps, timeout, error-shaping; it delegates execution.
• Local impl = today's tokio::process code verbatim, behind a default-on feature (e.g. local-shell). The crate's tokio process/time features become feature-dependent so the wasm build excludes them.
• Accept: cargo check -p rhema-agent-tools -p rhema-subagents --target wasm32-unknown-unknown --no-default-features is clean; native tests green (cargo test -p rhema-agent-tools); existing ShellTools behavior unchanged (caps, timeout-kill, line-streaming, approval).

Phase 2 — session/skills/prompt inputs in rhema-coding-agent (small)

• Sessions: the cloud crate serializes Session itself; if the fs helpers at agent.rs:233/238 are the only consumers, no seam is needed — confirm and note it.
• Skills/system prompt: stamped_system discovers skills from the filesystem internally. Add an input path that accepts an already-collected skill list (keep the fs discovery as the default used by rhema-code), so the cloud crate can feed skills from DO storage or discovered inside the sandbox. SYSTEM.md base is already a parameter — the cloud crate supplies it from DO storage with the built-in default as fallback.
• Accept: native behavior unchanged; the cloud crate can assemble a full agent with zero filesystem access.

Phase 3 — transport seam in the provider family

• Add a Transport trait to rhema-provider (it is the adapter-family base): request in (method/url/headers/json body) → status + a Send stream of byte chunks out. Contract: JS types must never leak into the trait; on wasm, bridge via spawn_local + channel (or async-compat).
• rhema-provider-anthropic: put reqwest behind a default-on native feature; take Arc<dyn Transport>; move connect_timeout and the "network error: " mapping into the native impl; keep the (HTTP <status>): error shape; the bytes_stream while-loop becomes transport-agnostic over the shared SseDecoder.
• rhema-provider/src/retry.rs: make Retrying's sleep injectable (additive builder, e.g. with_sleeper), default = today's tokio behavior so existing tests stay green. The cloud crate passes a worker::Delay sleeper.
• Accept: cargo check --workspace --all-features green natively; wasm check green for rhema-provider and the anthropic wire module with --no-default-features; no wire-type duplication between native and fetch paths.

Phase 4 — rhema-cloudflare-code itself

• Neutral half first: sandbox trait + scripted mock, ShellSandbox, assembly; host-side e2e (scripted sandbox + MockProvider): full turn with a bash call, approval round-trip, session checkpoint, and a simulated crash mid-command whose resume reports the call interrupted (not re-run).
• Then the worker module: DO class CodingAgent — WS chat surface (stream Events as they arrive; approval requests as WS round-trips with deny-on-timeout default and per-session policy: deny-all / read-only allowlist / allow-all flag), session checkpointing after every step, run_id per turn, ToolContext.cancelled wired to a disconnect/stop message; alarm reserved for v2.
• Approval plumbing note: approval fires inside tool resolution inside the turn task; the WS handler and turn task share workerd's single thread — connect them with channels, never shared-blocking waits.
• Secrets via wrangler secrets (env.secret(...)), never DO storage. Profiles in DO storage; do not use rhema-config's XDG store here.
• Sandbox HTTP client: call the Sandbox DO over its binding (stub.fetch() with JSON commands). If the current Sandbox surface is JS-RPC-only, write a ~30-line JS shim DO/worker that converts plain JSON HTTP → sandbox calls (prefer this over fighting JS RPC from Rust).

Phase 5 — deploy assets + CI

• deploy/cloudflare/: wrangler config (main = build/worker/shim.mjs, new_sqlite_classes migration, DO + sandbox namespace bindings, secrets docs), the optional JS shim, README notes — sibling of docker/ and helm/.
• Add the wasm gate to CI (scope ci): cargo check over the cloud closure with --target wasm32-unknown-unknown (the full crate with the worker feature is the real build; keep it green).
• Accept: a fresh clone with wrangler dev + one secret works.

Phase 6 — docs & conventions debt

• README: a component mention for rhema-cloudflare-code. AGENTS.md: add commit scope cloudflare-code. SPEC.md: the design-decision section (why DO + sandbox; the replay-safety implications of container eviction; the approval model; the turn-driving model).

5. Guardrails (from AGENTS.md and this design — non-negotiable)

• Per commit: cargo fmt --all, cargo clippy --workspace --all-targets --all-features -- -D warnings, cargo test --workspace --all-features green. Conventional commits with component scopes, linear history (rebase, no merge commits).
• Do not weaken #![forbid(unsafe_code)] / #![deny(missing_docs)] anywhere except the sanctioned worker module exception (documented in §3).
• No wasm-bindgen, fetch, or worker dependencies in rhema-core, rhema-coding-agent, rhema-agent-tools; none in the platform-neutral modules of rhema-cloudflare-code. The platform lives at the edges.
• rhema-core keeps exactly its two engine consumers (coding agent, RSD agent) — the cloud crate is a new frontend, not a new engine consumer. Dispatch/lease/persistence belongs in rhema-rsd, never in the engine.
• Keep the single bash spec as the source of truth shared by prompt and tools array; never fork the spec text.
• Do not attempt to make reqwest, tokio::time, or rusqlite work inside workerd. Host bindings or nothing.

6. Open questions to resolve from current Cloudflare docs (verify, don't assume)

1. The Sandbox's exact callable surface today (REST-over-DO-fetch vs JS RPC only) and its auth between your DO and the sandbox binding. If RPC-only, build the JS shim (Phase 4).
2. Sandbox idle-sleep model and workspace persistence guarantees — map onto ReplaySafety explicitly: a command killed by container sleep/eviction is the committed-unanswered-call case; bash is Unsafe to replay, so resume must report it interrupted (existing machinery — verify the wiring reaches it).
3. Current workers-rs DO support level: DurableObject trait shape, WS hibernation, SQLite (SqlStorage) bindings — pin the version accordingly.
4. Current CPU-limit and subrequest-limit numbers (per invocation), and whether the target plan's limits fit a live-request turn (~1 model fetch + 1-2 sandbox calls + approval round-trips per step; a 16-step turn ≈ 30-50 subrequests). If not, implement the alarm-driven step queue (v2) instead of fighting limits.

7. Definition of done

• All three gate commands green: fmt / clippy (-D warnings) / test (--workspace --all-features), plus the wasm check over the cloud closure.
• Offline e2e test (host-side): scripted sandbox + MockProvider → full turn with a bash call, approval round-trip, session checkpoint, and a simulated crash mid-command whose resume reports the call interrupted (not re-run).
• wrangler dev e2e: real Anthropic key, chat drives real bash in the sandbox; DO restart resumes the session; workspace files persist.
• README row, AGENTS.md scope, SPEC.md section landed.
• A short "running it" section in deploy/cloudflare/ (secrets, deploy, limits, pricing caveat for containers).