Developer docs for main, checked against 9849aeb
on 2026-11-16.
Backends and tests
Backend boundary
src/backend/mod.rs defines the Backend trait and registry. Adapter files implement command detection, launch preparation, readiness, delivery, and conversation handling. Start here when adding a backend or changing an agent launch contract.
src/manager/mod.rs combines prompts and MCP launch context with backend launch commands. src/tmux/client.rs supplies tmux operations; src/backend_runner.rs supports managed backend execution.
Delivery follows the transport recorded at launch: managed runner sockets, hook spools, or backend-specific channels such as the Codex app server and opencode HTTP API. Readiness failures can return NotReady for retry before sending. The registry’s delivery code reports channel failures without falling back to typing into the terminal composer.
src/backend/connect.rs and src/backend/connection.rs manage backend connection/setup state. The deterministic stub backend supports tests without a live model.
Where behavior is tested
| Layer | Tests |
|---|---|
| Rust data structures, VM, routes, tool scope, delivery | Inline #[cfg(test)] modules beside implementation |
| CLI and tmux sessions | tests/integration_test.rs |
| Compiler | lang/Tests.lean |
| Runtime contracts and recovery | tests/ci |
| Workflow fixtures | tests/topology |
| Browser protocol, rendering, and end-to-end behavior | web/tests, web/playwright.config.ts |
| Pi adapter JavaScript | src/backend/pi/test |
Integration tests create temporary homes and runtime sessions with dedicated tmux servers. They require tmux. Compiler and workflow tests also need the Lean toolchain; fixtures and test scripts show which compiler path or backend each test expects.
Build and validation entry points
The Rust package declares a minimum Rust version of 1.89 in Cargo.toml. Lean targets and the test driver are in lang/lakefile.lean; the Lean version is pinned in lang/lean-toolchain.
cargo check --all-targets
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test -- --test-threads=1
From lang/, lake build builds the compiler/library and lake test runs the compiler tests. Browser scripts are in web/package.json, including build:spa, test, and test:e2e.
Use CI workflows for the exact toolchain setup and test matrix. Rust tests also check that the generated browser protocol matches the committed TypeScript.