Wardian Architecture Overview

Wardian is built as a High-Performance Hybrid Environment, using Rust (Tauri) for the physical/logical system layer and React (TypeScript) for the high-fidelity user interface.

Design Principles

Wardian is a malleable agent environment. New architecture should preserve these invariants:

• Canonical state has an owner. The backend owns live agent runtime truth; automation files own automation templates; automation run logs own run evidence; library files own reusable prompts, skills, classes, and automation blueprints; watchlist/team records own roster organization until a broader project-scope model exists.
• Surfaces are lenses, not state silos. Agents, Dashboard, Analytics, Graph, Garden, Library, Automations, Inbox, and future workbench contributions resolve and mutate canonical Wardian records through shared commands or file contracts. A surface owns bounded presentation state, not a private copy of domain or runtime truth.
• Artifacts stay inspectable where practical. User-shapable prompts, classes, skills, automations, evidence, and memory-ready context should remain discoverable on disk or through stable CLI/backend queries.
• Scope is explicit. Features should name whether they operate globally, by class, by agent, by team/project, by workspace/folder, or by automation run.
• AI changes remain reviewable. Agent-generated edits to prompts, skills, automations, memory, or project context should preserve provenance and expose a diff or proposal path before mutating durable shared state.

🏛️ System Layers

1. The Physical Layer (Rust Backend)

• Source of Truth: The Rust backend is the definitive authority on all agent sessions, PTY states, and telemetry.
• Shared Core: crates/wardian-core owns shared paths, SQLite migrations, agent DTOs, and identity lookup so the Tauri app and CLI use the same durable state contract.
• PTY Management: Uses portable-pty for cross-platform PTY handles. On Windows, it leverages win32job to ensure child processes are strictly terminated when the agent session ends.
• Terminal Session Broker: One Rust actor per PTY runtime owns canonical terminal geometry, ordered output, bounded snapshots/replay, and the single interactive presentation lease shared by desktop and remote clients. See Terminal Presentation Broker.
• Provider Adapters: Agent CLIs are integrated behind a Rust provider layer so session spawn, headless execution, and telemetry enrichment can support Gemini, Antigravity, Claude, Codex, OpenCode, and Pi without rewriting the rest of the backend. See Provider Runtime Notes for the provider-specific working-root, skill, and session rules that sit behind this abstraction.
• Habitat Projection: For providers that need a neutral per-session habitat, the backend links the real workspace, projects scoped instructions, and exposes provider-native skill layouts without mutating the user repository. Codex uses a habitat-backed CODEX_HOME while executing against the real workspace, Gemini headless runs use the projected workspace, and OpenCode uses the habitat as its command root while receiving the real workspace explicitly. Pi does not create this projected habitat; it runs in the real workspace and receives Wardian instruction and skill roots through provider-native launch flags.
• State Management: AppState holds Mutex-protected maps of active agents, metrics, automation runs, and background tasks.
• Worker Threads:
  • Automation Scheduler: Fires persisted automation schedule invokers.
  • Metrics Push: Pushes system/agent resource usage to the UI via Tauri events.
• Inbox Persistence: Completion triage state is stored under the active Wardian home so agent and automation outcomes survive app restarts; durable agent notifications use the interaction store.

2. The Logical Layer (Automation Engine)

• Deterministic Execution: Detailed in Automation Engine Architecture.
• Shared Registry: A global Handlebars-based registry where agent outputs are stored for cross-agent referencing.
• Automation Candidate Queue: Deterministic execution of automation nodes (loops, triggers, waits, branches, memory, commands, and agent calls) through the engine's internal candidate-node FIFO.
• Injection Logic: Solves CLI input limits by writing prompts to temp files (~\.gemini\tmp\wardian-1) and using < redirection.

2.5 Memory and Knowledge

• Continuity vs Memory: Provider-native resume state is not the same thing as long-term memory. Session IDs, PTY ownership, approval hooks, and provider trust remain runtime concerns.
• Evidence-First Memory: Wardian's memory direction is to preserve raw evidence, index it for retrieval, and build prompt context selectively rather than replaying prior sessions wholesale.
• Promoted Knowledge: Curated atoms remain useful, but as promoted knowledge with provenance back to retrieved evidence rather than as the primary memory substrate.
• The internal evidence-first memory spec records the design history for this direction.

3. The UI Layer (React Frontend)

• Passive Observation: The UI primarily observes and edits the state; it does not manage process lifecycles.
• Workbench Model: WorkbenchDocumentV1 is the canonical central-layout model. A typed registry defines surface lifecycle and state contracts, while NavigationService is the mutation boundary. Dockview is a replaceable rendering adapter and never owns durable state. See Workbench Surfaces.
• Visual Builder: A specialized canvas for designing complex multi-agent automations, featuring the Integrated Variable Assistant.
• Agents: A responsive workbench surface for monitoring multiple terminal presentations in Auto, Grid, or Single mode.
• Inbox Surface: A triage surface for unread agent completions, important updates, approvals, and automation outcomes.

📡 Communication (IPC)

Wardian uses a bidirectional event system, detailed in IPC and Event Governance.

• Events (Push): Rust pushes telemetry (agent-metrics), structured logs (agent-json-event), and PTY readiness notifications (agent-pty-output-ready) to the UI.
• Commands (Pull): The UI invokes Rust functions for high-level actions (spawn_agent, automation_run).
• Terminal Input: Presentation-aware commands carry session, presentation, runtime generation, and lease epoch. Only the broker's active owner may send terminal keystrokes, binary input, or geometry. Structured prompt delivery remains a separate audited control path.
• Terminal Presentation Lifecycle: Each visible representation owns an independent xterm. One desktop session client fans the broker's canonical snapshot/event stream to local presentations; renderer eviction restores from a bounded snapshot instead of moving one module-global terminal between DOM hosts.

Wardian CLI

The crates/wardian-cli binary shares DTOs, paths, migrations, identity filters, and the live control protocol through wardian-core. Wardian remains GUI/app-first; the CLI exists so agents and automation can inspect and control Wardian through a stable textual surface. For read commands it first tries the running desktop app's local control endpoint for the same WARDIAN_HOME and falls back to $WARDIAN_HOME/state.db when the app is not running. Live-control commands cover agent lifecycle, message delivery, watch/wait coordination, worktree assignment, and automation run control. The desktop app stages the binary as a Tauri resource and installs it into the user Wardian bin directory on startup.