Engineering Specification

Runtime Architecture & Dataflow

Kyro is structured as a native desktop application with a clear separation of concerns between its React 19 presentation layer and multi-threaded Rust execution core (`libkyro`).

Subsystem Inventory

Frontend Shell (`kyroui/`)

React 19 + TypeScript + Vite. Hosts dual-experience shells, floating HUD panels (`hud/HudPanel.tsx`), screen region snippers, timeline drawers, interactive xterm.js terminals, and modal tools.

Agent Loop Engine (`agent/loop_engine.rs`)

Manages multi-turn reasoning steps, dynamic tool registration, scoped cancellation tokens, context window budgeting, and step timeline events.

Central Authorization (`governance/auth.rs`)

Unified security boundary that evaluates every tool invocation against active policies, parses shell tokens, enforces filesystem boundaries, and manages approval lifecycles.

Local Storage & Vault (`storage/`)

SQLite database in WAL mode handling v1-v5 schema migrations. Vault service handles OS Keyring integration with authenticated AES-256-GCM encrypted fallback.

Tauri v2 IPC Bridge

The frontend interacts with Rust backend modules across 75 strictly-typed Tauri commands registered in libkyro/src/main.rs. Real-time updates (timeline steps, terminal output, dev server logs, approval requests) are dispatched as unidirectional Tauri events.

libkyro/src/main.rs (IPC Handler Sample)

tauri::Builder::default()
    .manage(state)
    .invoke_handler(tauri::generate_handler![
        list_conversations,
        run_agent_turn,
        check_command_permission,
        resolve_approval,
        discover_projects,
        start_dev_server,
        create_code_checkpoint,
        diagnose_build_failure,
        explain_screen_capture,
        preview_file_organization,
        export_routine,
        // ... 75 registered commands
    ])

Run Cancellation & Subprocess Trees

Every agent execution turn is assigned a unique run_id and linked to a CancellationToken. When a user clicks Cancel or interrupts a task:

• HTTP model inference requests are aborted immediately.
• Child process groups (PGID) spawned by shell commands are signaled with SIGKILL.
• Ongoing browser automation sessions and PTY sessions are cleanly closed.
• The task state in SQLite transitions to interrupted.