From f1af6caab0a81f2cb92b028c482ce5d477056b11 Mon Sep 17 00:00:00 2001 From: David Hagerty Date: Wed, 11 Feb 2026 14:46:27 -0500 Subject: [PATCH] docs: update project context for V2 Phase 4 web UI Add web/ domain AGENTS.md documenting the Svelte 5 SPA contracts, dependencies, invariants, and routing. Update root AGENTS.md with web UI in project structure, commands, and dependencies sections. Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 27 +++++++++++++++++++++-- web/AGENTS.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++ web/CLAUDE.md | 1 + 3 files changed, 85 insertions(+), 2 deletions(-) create mode 100644 web/AGENTS.md create mode 100644 web/CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md index fbb1593..7c3ac1c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,13 +1,13 @@ # Rustagent -Last verified: 2026-02-09 +Last verified: 2026-02-11 ## Project Overview Rustagent is a Rust-based AI agent framework for autonomous task execution. The architecture has two layers: - **V1 (legacy)**: Planning Agent + Ralph Loop using flat JSON specs -- **V2 (current)**: Graph-based work tracking with typed agent profiles, SQLite persistence, and an agentic runtime loop +- **V2 (current)**: Graph-based work tracking with typed agent profiles, SQLite persistence, an agentic runtime loop, and a Svelte 5 web dashboard V2 is the active development path. V1 modules (`planning/`, `ralph/`, `spec.rs`) remain for backward compatibility. @@ -24,6 +24,14 @@ cargo test # Run specific test by name cargo doc --open # Generate and view documentation ``` +### Web UI Commands +```bash +cd web && bun install # Install frontend dependencies +cd web && bun run dev # Dev server (Vite proxy to daemon:7400) +cd web && bun run build # Production build to web/dist/ +cd web && bun run test # Run vitest tests +``` + ### V2 CLI Commands ```bash cargo run -- project add # Register a project @@ -41,6 +49,13 @@ cargo run -- graph adr # Export decisions as ADR markdown ## Project Structure ``` +web/ # Svelte 5 Web UI (see web/AGENTS.md) +├── src/api/ # HTTP client + WebSocket handler +├── src/stores/ # Reactive stores (projects, graph, agents, search) +├── src/views/ # 8 view components +├── src/components/ # Reusable UI components +├── src/lib/ # Utilities (tree transform, decision graph, date formatting) +└── dist/ # Production build output (embedded via rust-embed) src/ ├── main.rs # CLI entry point (clap), V1 + V2 commands ├── lib.rs # Library exports: all public modules @@ -94,12 +109,20 @@ src/ ## Key Dependencies +### Rust - `rusqlite` (bundled) + `tokio-rusqlite` for async SQLite - `blake3` for content hashing (interchange format) - `clap` (derive) for CLI - `chrono` for timestamps (RFC 3339 everywhere) - `uuid` v4 for ID generation +### Web UI (Bun/npm) +- `svelte` 5 (runes) + `@sveltejs/vite-plugin-svelte` for UI framework +- `vite` 6 for build tooling and dev server +- `cytoscape` + `cytoscape-dagre` for decision graph visualization +- `vitest` for frontend tests +- `typescript` 5 for type safety + ## Conventions ### ID Scheme diff --git a/web/AGENTS.md b/web/AGENTS.md new file mode 100644 index 0000000..18f7bb2 --- /dev/null +++ b/web/AGENTS.md @@ -0,0 +1,59 @@ +# Web UI + +Last verified: 2026-02-11 + +## Purpose +Provides a browser-based dashboard for monitoring and managing Rustagent V2 work graphs. Connects to the daemon HTTP API and WebSocket for real-time updates on agents, tasks, decisions, and sessions. + +## Contracts +- **Exposes**: SPA served from `web/dist/` (production build). 8 views: Dashboard, ProjectList, ProjectDetail, TaskTree, DecisionGraph, AgentMonitor, SessionHistory, GraphSearch +- **Guarantees**: TypeScript types in `types.ts` mirror Rust serde serialization exactly (field names, casing, nullability). WebSocket reconnects automatically with exponential backoff (1s to 30s cap). Stores update reactively via Svelte 5 runes (`$state`). Event feed is capped at 200 items (ring buffer). +- **Expects**: Daemon running on port 7400 (Vite proxies `/api` and `/ws` in dev). All API responses match the types defined in `types.ts`. + +## Dependencies +- **Uses**: Daemon HTTP API (`/api/*`), Daemon WebSocket (`/ws`), Cytoscape.js (graph visualization), cytoscape-dagre (layout) +- **Used by**: End users via browser. Production build embedded in Rust binary via `rust-embed` behind `bundle-ui` feature flag +- **Boundary**: Does NOT import Rust code directly. All communication is via HTTP/WebSocket. No server-side rendering. + +## Key Decisions +- Svelte 5 runes over React: Simpler reactivity model, smaller bundle, native TypeScript support +- Hash-based router over SvelteKit: SPA served from static files, no SSR needed +- Singleton ApiClient: All stores share one instance via `api/index.ts` +- Cytoscape.js for decision graph: Supports dagre layout, node/edge styling by type, interactive selection +- Bun as package manager: Faster installs, compatible lockfile + +## Invariants +- `types.ts` enum values must match Rust `#[serde(rename_all)]` output (e.g., `dependson` not `depends_on`, `leadsto` not `leads_to`) +- WebSocket events use discriminated union on `type` field matching Rust `#[serde(tag = "type", rename_all = "snake_case")]` +- Stores never throw; errors are captured in `error` state fields +- Tree building uses "contains" edges for parent-child, "dependson" edges for dependencies + +## Key Files +- `src/types.ts` - All TypeScript types mirroring Rust API (GraphNode, GraphEdge, WsEvent, etc.) +- `src/api/client.ts` - ApiClient class wrapping fetch() for all daemon endpoints +- `src/api/websocket.ts` - WsConnection with auto-reconnect and event dispatching +- `src/router.svelte.ts` - Hash-based SPA router with parameter extraction +- `src/stores/` - 4 reactive stores: projects, graph, agents, search +- `src/lib/tree.ts` - GoalTree to nested TreeNode transformation +- `src/lib/decision-graph.ts` - GraphNode/Edge to Cytoscape ElementDefinition conversion +- `src/App.svelte` - App shell: sidebar + routed views + WebSocket lifecycle + +## Development +```bash +cd web && bun install # Install dependencies +cd web && bun run dev # Dev server with Vite proxy to daemon:7400 +cd web && bun run build # Production build to dist/ +cd web && bun run test # Run vitest tests +``` + +## Routes +| Hash Path | View | Params | +|-----------|------|--------| +| `/` | Dashboard | - | +| `/projects` | ProjectList | - | +| `/projects/:projectId` | ProjectDetail | projectId | +| `/goals/:goalId/tasks` | TaskTree | goalId | +| `/goals/:goalId/decisions` | DecisionGraph | goalId | +| `/goals/:goalId/agents` | AgentMonitor | goalId | +| `/goals/:goalId/sessions` | SessionHistory | goalId | +| `/search` | GraphSearch | - | diff --git a/web/CLAUDE.md b/web/CLAUDE.md new file mode 100644 index 0000000..f66a6ac --- /dev/null +++ b/web/CLAUDE.md @@ -0,0 +1 @@ +Read @./AGENTS.md and treat its contents as if they were in CLAUDE.md -- 2.51.2