DocsArchitectureArchitecture Overview

Ryvos is a Rust 1.75+ Cargo workspace consisting of 10 crates that compile into a single static binary. The architecture follows a layered dependency graph where higher-level crates compose lower-level ones, and ryvos-core provides the foundation for everything.

Crate Dependency Graph

ryvos (CLI binary, ~88KB main.rs)
 ├── ryvos-tui          Terminal UI (ratatui + crossterm)
 ├── ryvos-gateway       HTTP/WS server + embedded Web UI
 ├── ryvos-agent         Core runtime: ReAct loop, security, guardian, director
 │    ├── ryvos-tools    86+ built-in tools across 18 categories
 │    ├── ryvos-llm      18 LLM provider clients with streaming
 │    ├── ryvos-memory   SQLite persistence, cost tracking, embeddings
 │    ├── ryvos-mcp      Model Context Protocol client (stdio + SSE)
 │    ├── ryvos-skills   Lua/Rhai script runtime, skill registry
 │    └── ryvos-channels Telegram, Discord, Slack, WhatsApp adapters
 └── ryvos-core          Foundation: types, traits, config, events, security

Crate Summaries

ryvos-core

The foundation crate that every other crate depends on. Contains:

  • config.rs — AppConfig root configuration with TOML parsing and $\{VAR\} environment variable expansion. Supports global (~/.ryvos/config.toml) and workspace-level (ryvos.toml) configs.
  • types.rs — Core types: SessionId, Role, ContentBlock, ChatMessage, ToolContext, ToolDefinition, ToolResult, Verdict, CostEvent, StopReason, and the AgentEvent enum (45+ variants for the event bus).
  • traits.rs — The four trait interfaces: LlmClient (streaming chat), Tool (execution), ChannelAdapter (messaging), SessionStore (persistence).
  • security.rs — Security tiers (T0-T4), SecurityPolicy, DangerousPatternMatcher (9 built-in patterns), ApprovalRequest.
  • goal.rs — Goal definitions with weighted success criteria, constraints, and evaluation.
  • event.rs — EventBus (tokio broadcast channel), EventFilter, scoped subscriptions.
  • hooks.rs — Lifecycle hook definitions (on_start, on_message, on_tool_call, etc.).
  • error.rs — RyvosError enum (15+ variants) with thiserror.

ryvos-llm

Multi-provider LLM client layer. Each provider implements the LlmClient trait for streaming responses:

  • Native clients: Anthropic (Messages API), OpenAI (Chat Completions), Gemini, Azure, Cohere, Bedrock
  • Subprocess clients: Claude Code CLI, GitHub Copilot CLI (JSONL)
  • OpenAI-compatible presets: Ollama, Groq, OpenRouter, Together, Fireworks, Cerebras, xAI, Mistral, Perplexity, DeepSeek
  • Streaming: StreamDelta enum, SseParser, SseStream for Server-Sent Events
  • Resilience: RetryingClient with exponential backoff

ryvos-tools

86+ built-in tools organized in 18 categories. Each tool implements the Tool trait with:

  • Name, description, JSON Schema input definition
  • execute() function returning ToolResult
  • Security tier classification
  • Optional timeout and sandbox requirements

The ToolRegistry manages tool registration and lookup by name.

ryvos-agent

The core runtime and the largest crate. Contains:

  • agent_loop.rs — AgentRuntime with run(), run_with_goal(), run_with_director(). Implements the ReAct loop.
  • gate.rs — SecurityGate that intercepts tool calls, bash injection detection.
  • guardian.rs — Watchdog: doom loop detection, stall detection, token/dollar budget enforcement.
  • director.rs — Director orchestration: LLM generates execution graph, evaluates results, evolves plan.
  • graph/ — DAG workflow engine: Node, Edge, GraphExecutor, HandoffContext.
  • judge.rs — 2-level evaluation: Level 0 (deterministic), Level 2 (LLM-based).
  • intelligence.rs — Token estimation (tiktoken), context pruning, summarization, compaction.
  • context.rs — 3-layer prompt composition (Identity, Narrative, Focus).
  • healing.rs — FailureJournal: SQLite failure tracking with reflexion hints.
  • heartbeat.rs — Periodic mini-agent runs with smart suppression.
  • scheduler.rs — Cron scheduler (5-field expressions via cron crate).
  • checkpoint.rs — CheckpointStore: crash-safe session persistence.

ryvos-memory

SQLite-based persistence:

  • store.rs — SqliteStore: message storage, FTS5 full-text search, WAL mode.
  • cost_store.rs — Per-run cost tracking, session/date queries, budget enforcement.
  • pricing.rs — Cost estimation per model (input/output token pricing).
  • embeddings.rs — EmbeddingProvider trait, HTTP client, cosine similarity.
  • session_meta.rs — Session metadata storage and CLI session ID resumption.

ryvos-gateway

Axum HTTP/WebSocket server with embedded Web UI:

  • server.rs — Axum setup with CORS, binds to 127.0.0.1:18789.
  • routes.rs — REST endpoints: /api/chat, /api/sessions, /api/config, /api/hooks/wake. WebSocket at /ws.
  • auth.rs — Role-based API key authentication (Viewer, Operator, Admin).
  • protocol.rs — WebSocket message types (Request, Response, Delta).
  • static_files.rs — Embedded Svelte Web UI via rust-embed.

ryvos-channels

Multi-platform channel adapters:

  • telegram.rs — teloxide 0.13: DM policies, inline approval buttons, 4096 char splitting.
  • discord.rs — serenity 0.12: rich embeds, button components, DM policies.
  • slack.rs — Socket Mode, Block Kit UI, slash commands, dual token auth.
  • whatsapp.rs — Meta Cloud API, webhook verification, E.164 phone numbers.
  • dispatch.rs — ChannelDispatcher: routing, per-channel policies, approval routing.

ryvos-mcp

Model Context Protocol client:

  • client.rs — McpClientManager: connects to MCP servers via stdio and SSE/Streamable HTTP (rmcp 0.16).
  • bridge.rs — McpBridgedTool: wraps MCP tools as native Ryvos tools, mcp__{server}__{tool} naming.
  • handler.rs — Server-side handler for MCP events.
  • resource_tool.rs — Read MCP resources as a tool.
  • Supports .mcp.json for Claude Code compatibility.

ryvos-skills

Drop-in script runtime:

  • manifest.rs — SkillManifest from skill.toml: name, description, command, prerequisites.
  • registry.rs — GitHub-hosted JSON index, SHA-256 verification, CLI install/search/remove.
  • skill_tool.rs — Wraps scripts as Tool, subprocess execution with JSON stdin, 60s timeout.
  • Host functions: read_file, http_get, http_post, env, log.

ryvos-tui

Terminal UI built with ratatui 0.29 + crossterm 0.28:

  • Chat view, input area, tool output panel
  • Adaptive banner with session info
  • Keyboard navigation and event handling

Data Flow

A typical request flows through the system like this:

User Input (CLI/Channel/API/WebSocket)
       │
       ▼
   ┌─────────┐
   │ Gateway  │ ← HTTP/WS/Channel adapter receives message
   └────┬─────┘
        │
        ▼
   ┌──────────┐
   │  Agent   │ ← AgentRuntime.run() starts ReAct loop
   │  Loop    │
   └────┬─────┘
        │
   ┌────┴────────────────────────┐
   │  For each turn:             │
   │  1. Build context (3 layers)│
   │  2. Estimate tokens         │
   │  3. Call LLM (streaming)    │
   │  4. Parse tool calls        │
   │  5. Security gate check     │
   │  6. Execute tools           │
   │  7. Guardian monitoring     │
   │  8. Judge evaluation        │
   └────┬────────────────────────┘
        │
        ▼
   ┌──────────┐
   │ Response │ ← Streamed back to user via same channel
   └──────────┘

Event Bus

The EventBus is a tokio broadcast channel that carries AgentEvent messages throughout the system. Any component can publish or subscribe:

  • Publishers: Agent loop, tools, guardian, scheduler, heartbeat, director
  • Subscribers: Gateway (WebSocket relay), TUI (display), channels (notifications), run logger

Key event categories:

  • Run lifecycle: RunStarted, TurnComplete, RunComplete, RunError
  • Streaming: TextDelta, ToolStart, ToolEnd
  • Guardian: GuardianStall, GuardianDoomLoop, GuardianBudgetAlert, GuardianHint
  • Director: GraphGenerated, NodeComplete, EvolutionTriggered, SemanticFailureCaptured
  • Automation: CronFired, CronJobComplete, HeartbeatFired, HeartbeatOk, HeartbeatAlert

Design Principles

  1. Single binary — Everything compiles into one static executable. No runtime dependencies, no Docker required. The Web UI is embedded via rust-embed.

  2. Trait-based abstraction — Four core traits (LlmClient, Tool, ChannelAdapter, SessionStore) define all extension points. New providers, tools, and channels implement these traits.

  3. Event-driven — The broadcast EventBus decouples components. The agent loop does not know about the TUI or Web UI; it just emits events.

  4. Layered configuration — Global config at ~/.ryvos/config.toml, workspace override at ryvos.toml, environment variable expansion everywhere.

  5. Crash-safe persistence — SQLite in WAL mode with checkpoints after every turn. Sessions can be resumed after crashes.

Build Profile

[profile.release]
opt-level = 3
lto = "thin"
strip = true
  • Binary size: 38-47 MB (platform dependent)
  • Idle memory: under 30 MB RAM
  • Startup time: less than 100ms
  • Tool dispatch: less than 1ms

Next Steps

CLI ReferenceAgent Loop