Skip to content

Latest commit

 

History

History
172 lines (141 loc) · 8.63 KB

architecture.md

File metadata and controls

172 lines (141 loc) · 8.63 KB

Runtime and workspace architecture

This repository is a Rust workspace with a root application crate and small domain crates. The extracted crates keep frequently edited functionality from forcing unrelated heavyweight dependencies to rebuild. The product is the orchestrator app in apps/desktop; the TUI in rustcode/tui is a second front end over the same engine.

Repository layout

rustcode/
├── core/       Domain libraries. No terminal UI, no frontend assumptions.
│   ├── rustcode-core/         stable shared types and path helpers
│   ├── rustcode-session/      session persistence primitives
│   ├── rustcode-tool-protocol/ tool-call protocol envelopes
│   ├── rustcode-tools/        filesystem tool implementations
│   ├── rustcode-command/      cross-platform command execution
│   ├── rustcode-lifecycle/    turn lifecycle and stop-state types
│   ├── rustcode-tasks/        background task state and event delivery
│   └── rustcode-loop-detect/  semantic loop and progress guards
├── client/     `rustcode-client`, the machine client: saved machines, pairing
│               and the WebSocket to another machine's gateway.
├── engine/     Sources of the root `rustcode` crate (library only): agent
│               loop (the built-in harness), tools, config, session state, ACP,
│               daemon, controller.
└── tui/        `rustcode-tui`, the terminal frontend. Owns the `rustcode`
                binary (TUI + headless/ACP/daemon CLI modes); depends on the
                root library, never the reverse.

The desktop app in apps/desktop (Tauri + React, see desktop) runs the engine over ACP. The SwiftUI macOS app it replaced was removed; macOS app architecture maps it for history.

The root Cargo.toml is both the workspace manifest and the rustcode package manifest; the engine lives in rustcode/engine/src and is declared with [lib] path. There are no Cargo features left: the terminal stack (ratatui, crossterm, syntect, pulldown-cmark) lives only in rustcode/tui. Nothing under rustcode/core or rustcode/engine may reference it; cargo tree -p rustcode -i ratatui must match nothing. See docs/frontends.md for the frontend contract and docs/mobile.md for the remote-only mobile decision.

Workspace crates

Crate Responsibility
rustcode-core Stable shared domain types and executable-path helpers
rustcode-session Session persistence primitives
rustcode-tool-protocol Tool-call protocol parsing and envelopes
rustcode-tools Filesystem-oriented tool implementations
rustcode-command Cross-platform command execution and bounded output
rustcode-lifecycle Turn lifecycle and stop-state types
rustcode-tasks Session-aware background task state and event delivery
rustcode-loop-detect Semantic loop, failure, progress, and reasoning guards
rustcode-client The machine client: saved machines and routes, ask-to-connect pairing, the device-token store, the WebSocket transport and ACP over another machine's gateway. Used by rustcode machines and, later, the desktop app's Rust shell

The root rustcode crate owns integration concerns: model/network turns, ACP, configuration, the terminal UI state, and adapters between the smaller crates.

Command and task flow

model tool call
    -> tool protocol envelope
    -> network tool execution
    -> root tool dispatcher
    -> rustcode-command (foreground)
       or rustcode-tasks + rustcode-command (background)
    -> session-scoped event consumer
    -> history + UI/headless/ACP continuation

The task manager is process-scoped, but all listing, status, cancellation, and event routing enforce session ownership. Consumers subscribe before work can spawn so fast commands cannot complete before an observer exists.

Interactive, headless, and ACP consumers have separate adapters:

  • The interactive runtime preserves inactive-session subscriptions until their terminal events have been drained.
  • Headless execution tracks only tasks created by its current turn.
  • ACP uses a server-owned router with bounded per-session delivery, durable persistence, provider call-ID correlation, and ordered terminal updates.

Concurrency rules

  • OS process termination is performed outside the task-state mutex.
  • A Terminating state retains a racing process completion until cancellation commits its outcome.
  • Terminal transitions are idempotent and publish once.
  • Terminal IDs are retained in a bounded ledger for race classification.
  • Event publication is synchronized with quiescence checks so a consumer cannot prune a subscription while its terminal event is still in flight.
  • Slow task subscribers are disconnected rather than allowed to block workers.

TUI transcript scrolling

The viewport projects committed history and the current live assistant/tool cell into one sequence of wrapped rows. The live cell is measured before the combined viewport is sliced, so its older rows remain reachable while output grows. Only the history suffix needed for the viewport and scroll offset is rendered; committed blocks and the live assistant cell reuse their presentation caches.

A zero scroll offset follows the newest row. Manual scrolling records the committed tail and live row counts at the current width; subsequent frames adjust the offset by rows added below the reader, including the handoff from live output to completed or cancelled history. Height changes preserve the top reading row. Width changes rewrap the semantic cells and establish a new reading anchor. The existing return-to-bottom control resumes following and clears unseen activity. Mouse selections continue to project their immutable snapshot, including live text, so streaming cannot change selected or copied rows.

Build and CI boundaries

Desktop shell and shared client changes run blocking Linux/Windows cargo check --all-targets jobs in Desktop CI, alongside the macOS shell checks; UI-only changes skip them.

Changes under rustcode/ and CI helper scripts trigger the required Linux test and lint jobs, plus advisory macOS/Windows portability checks. The required test and lint jobs run in parallel so merges do not wait for their combined compile time. Release artifacts are built for:

  • Linux x86_64
  • macOS Apple Silicon (ARM64)
  • Windows x86_64

Intel macOS is intentionally not part of the release matrix.

The Build workflow runs for version tags and manual dispatches only. A push to main does not rebuild all release targets; the tag build is the single source of published artifacts. Use manual dispatch on a branch when a release binary needs validation without creating a release.

The release script performs a lightweight local preflight, opens a release PR, waits only for required PR checks, and then tags the merged commit. Use --full-verify when a complete local test run is desired before opening the release PR.

Use scripts/bench-build-boundaries.md to measure clean, warm, and focused-edit Cargo rebuild costs without cleaning a shared target directory.

Thread index

~/.config/rustcode/index.sqlite (engine/src/thread_index.rs) indexes the thread folders: a threads table (title, folder, message count, folder mtime) and an FTS5 trigram index over user and assistant messages (each capped at 6,000 characters). The folders stay the source of truth: the engine refreshes the index from them at start, in the background, and before each search, reading only folders whose mtime moved; a missing or unreadable index is deleted and rebuilt. Migrations are numbered and recorded with their names, and a name mismatch refuses to open instead of skipping a step. _rustcode/threads/search { query, limit? } answers { results: [{ session_id, title, snippet, updated_at }] }.

Local data store

~/.config/rustcode/data.sqlite (engine/src/data_store.rs) keeps the metadata the folders cannot answer cheaply: threads, turns (tokens, cost, outcome, tool-call count) and tool calls, plus a daily_usage view by day, harness and model. It is not a cache like the thread index: per-turn token deltas of an external harness cannot be rebuilt, so the file is kept. Metadata only — no message text, tool arguments or output. The engine writes it beside track_usage for its own turns and when an external harness's prompt returns (reading Claude Code's and Pi's own session logs for the token counts their usage_update omits), backfills existing folders once in the background, and exposes reads through rustcode usage and rustcode data query. See data store.