Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
234 lines (194 loc) · 8.27 KB

ARCHITECTURE.md

File metadata and controls

234 lines (194 loc) · 8.27 KB
Raw
title Coven runtime architecture
summary How Coven's Rust daemon, CLI, TUI, comux cockpit, and OpenClaw plugin compose around the local socket API, PTY adapters, and the event store.
read_when
Understanding Coven's runtime topology
Designing a client around the local socket API
description Coven runtime topology: the Rust daemon, CLI, TUI, comux, and OpenClaw composed around the local socket API, PTY adapters, and the event store.

Coven Architecture

The canonical public overview is Architecture. This file remains beside the code for crate ownership, dependency direction, and source-adjacent authority details.

Coven is a local-first harness substrate. The Rust CLI/daemon is the authority layer; clients such as the CLI TUI, comux, and the optional OpenClaw plugin are presentation/integration layers.

The versioned local socket API contract lives in docs/API-CONTRACT.md. Clients should use GET /api/v1/health and its named apiVersion plus the required capabilities fields before depending on session or event response shapes. Capabilities advertise availability and never grant permission. The legacy GET /api/v1/api-version route reports literal v1 route-family values, not proof of coven.daemon.v1 support.

Runtime topology

flowchart LR
  subgraph Clients["Client layer"]
    User[Developer]
    CLI["coven run CLI"]
    SocketClients["TUI / socket clients"]
    Comux["comux cockpit"]
    OpenClaw[OpenClaw]
    Plugin["OpenClaw bridge plugin"]
  end

  subgraph DaemonCore["Daemon core"]
    Daemon[Coven daemon]
    Control["Control plane\n(capability discovery + action routing)"]
    Policy["Policy + permission hints"]
    AdapterBus["Adapter / event bus"]
    Boundary["Project-root + cwd guard"]
    HarnessRouter["Harness adapter router"]
  end

  subgraph Adapters["Harness adapters"]
    Bundled["Bundled compatibility defaults\nCodex / Claude Code / GitHub Copilot CLI"]
    Trusted["Trusted opt-in recipes\nHermes 1.0.3 / OpenCode 0.1.1"]
    Experimental["Experimental opt-in recipe\nGrok Build 1.0.0"]
    Future["Future direction\nAider / Gemini / Cline / custom"]
    DesktopUse["desktop-use adapters"]
  end

  subgraph Storage["Persistent storage"]
    Store[(SQLite session ledger)]
    Events[(append-only event log)]
  end

  User --> CLI
  CLI -->|direct commands| Rust["Coven Rust CLI"]
  Rust --> Boundary
  Rust --> Store
  Rust --> Events

  User --> SocketClients
  SocketClients -->|"HTTP over same-user local IPC"| Daemon
  Comux -->|"HTTP over same-user local IPC"| Daemon
  OpenClaw --> Plugin
  Plugin -->|"HTTP over same-user local IPC"| Daemon

  Daemon --> Control
  Control --> Policy
  Control --> AdapterBus
  AdapterBus -.->|desktop.automation| DesktopUse

  Daemon --> Boundary
  Boundary --> HarnessRouter
  HarnessRouter --> Bundled
  HarnessRouter -.->|opt-in recipe| Trusted
  HarnessRouter -.->|experimental recipe| Experimental
  HarnessRouter -.->|future direction| Future

  Daemon --> Store
  Daemon --> Events
  Bundled --> Events
  Trusted --> Events
  Experimental --> Events
Loading

Session lifecycle

sequenceDiagram
  participant U as User
  participant C as coven Rust CLI
  participant X as Socket client
  participant D as Rust daemon
  participant S as SQLite store
  participant H as Harness PTY

  U->>C: coven run codex "fix tests"
  activate C
  C->>C: canonicalize root/cwd; validate harness
  C->>S: insert new row (status=created)
  C->>S: transition row to running
  C->>H: launch validated argv directly
  activate H
  H-->>S: output / exit events
  deactivate C

  X->>D: POST /api/v1/sessions
  activate D
  D->>D: canonicalize root/cwd; validate harness
  D->>S: insert new row (status=running)
  D->>H: launch validated argv in PTY
  alt launch fails
    D->>S: transition new row to failed
    D-->>X: 500 launch_failed
  else launch succeeds
    D-->>X: 201 SessionRecord
  end
  deactivate D

  Note over U,C: Browse and manage sessions

  U->>C: coven sessions
  activate C
  C->>S: list active sessions, or all with --all flag
  C-->>U: interactive session browser
  deactivate C

  U->>C: Rejoin / View Log / Summon / Archive / Sacrifice
  activate C
  C->>D: attach / input / kill (when session is live)
  C->>S: archive / summon / sacrifice (non-live session rituals)
  deactivate C
  deactivate H
Loading

Authority boundary

flowchart TD
  Client["CLI / TUI / comux / OpenClaw plugin"]
  Request["Launch / input / kill / list request"]
  Rust["Rank 0 authority: Rust daemon"]
  RootCheck{"projectRoot\nexplicit?"}
  CwdCheck{"cwd canonicalized\ninside root?"}
  HarnessCheck{"harness\nallowlisted?"}
  RejectRoot["❌ Reject"]
  RejectCwd["❌ Reject"]
  RejectHarness["❌ Reject with install hint"]
  Spawn["Spawn harness with argv APIs"]
  Ledger["Persist session + events"]

  Client --> Request
  Request --> Rust
  Rust --> RootCheck
  RootCheck -->|no| RejectRoot
  RootCheck -->|yes| CwdCheck
  CwdCheck -->|no| RejectCwd
  CwdCheck -->|yes| HarnessCheck
  HarnessCheck -->|no| RejectHarness
  HarnessCheck -->|yes| Spawn
  Spawn --> Ledger

  style RejectRoot  fill:#fca5a5,stroke:#dc2626,color:#000
  style RejectCwd   fill:#fca5a5,stroke:#dc2626,color:#000
  style RejectHarness fill:#fca5a5,stroke:#dc2626,color:#000
  style Spawn       fill:#86efac,stroke:#16a34a,color:#000
  style Ledger      fill:#86efac,stroke:#16a34a,color:#000
Loading

Intake / automation boundary

The chat/intake client should remain a chat UI, local echo/optimistic rendering surface, intent-capture layer, and tiny fast-path host for ultra-simple local actions. It should not become the automation engine.

Coven is the canonical shared local runtime for reusable automation because it centralizes:

  • daemon/process ownership
  • policy and permission decisions
  • config/profile storage
  • capability discovery
  • action routing and event emission
  • adapter ownership for Accessibility, AppleScript, keyboard/mouse, window, filesystem, clipboard, and app-specific bridges

The intended flow is:

user -> chat/intake client -> Coven -> adapters -> desktop/apps
desktop/apps -> Coven -> chat/intake client UI updates

GET /api/v1/capabilities lets the chat/intake client and other clients discover what Coven can route. POST /api/v1/actions gives clients a stable intent envelope without coupling them directly to brittle OS automation APIs.

Current user-facing surface

  • coven, coven chat, and coven tui open the managed interactive UI powered by coven-code. The first interactive run offers to install the pinned engine if it is missing.
  • COVEN_LEGACY_TUI=1 explicitly enables the deprecated, temporary in-process TUI compatibility fallback. It will be removed.
  • coven doctor checks store/project/harness readiness and prints next steps.
  • coven daemon start/status/restart/stop manages the local daemon.
  • coven run codex|claude|copilot <prompt> launches a project-scoped PTY session.
  • coven sessions opens the human session browser in a terminal; --plain keeps scriptable output.
  • Session browser actions surface readable choices: Rejoin, View Log, Summon, Archive, and Sacrifice.
  • coven attach|summon|archive|sacrifice <session-id> remain explicit lower-level verbs for scripts and copy/paste workflows.

Managed engine

Coven drives coven-code as a separately-installed engine process — it is never linked or imported as a library. The process boundary is also the license boundary (coven: MIT; coven-code: GPL-3.0). The exact CLI flags, environment variables, stream-json events, and exit codes that constitute the integration surface are specified in docs/ENGINE-CONTRACT.md; any breaking change to that surface requires a coordinated version bump in both repositories.

Distribution snapshot

The npm wrapper packages are live for early adopters:

  • @opencoven/cli
  • @opencoven/cli-macos
  • @opencoven/cli-macos-x64
  • @opencoven/cli-linux-x64
  • @opencoven/cli-windows (published Windows x64 platform package)

Source supports native Windows, including owner-only named-pipe daemon transport. The wrapper installs the platform package version declared by that wrapper release. Publication of @opencoven/cli-windows therefore does not establish that every direct CLI operation is portable on Windows.