Conversation
…itecture
Phase 1: Lieutenant service (services/lieutenant/)
- SQLite-backed persistent agent session management
- 8 tools: create, send, read, status, pause, resume, destroy, discover
- Local mode (subprocess) and remote mode (VM-based) support
- RPC process management with event-driven state updates
- HTML dashboard and widget contribution
Phase 2: Registry service (services/registry/)
- Promoted from examples/ to core with SQLite backing
- VM lineage tracking (parent-child relationships)
- Reef config per VM ("DNA" — organs + capabilities)
- Config diff between VMs
- Heartbeat-based liveness, discovery by role
Phase 3: VM Tree service (services/vm-tree/)
- SQLite lineage tree: roof reef → lieutenants → swarm/agent VMs
- Full tree queries (ancestors, descendants, subtrees)
- Category filtering (lieutenant, swarm_vm, agent_vm, infra_vm)
- Organ/capability search across all VMs
- Hourly snapshots via cron (retain last 24)
- Visual tree dashboard
Phase 4: Vers Config service (services/vers-config/)
- Centralized config resolution (env → store → file fallback)
- Replaces ~/.vers/keys.json, config.json, agent-services.json
- API for viewing and setting config overrides
Phase 5: Bootloader service (services/bootloader/)
- VM type profiles: full, swarm, lightweight, infra
- Boot script generation with selective module loading
- VM DNA configuration and tree registration
- Polymorphic VM provisioning
https://claude.ai/code/session_01Y4T4TrePAqaoEwb3UPPa4r
This was referenced Mar 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Migrates the lieutenants service and its supporting infrastructure from the pi-vers monorepo into reef. This lays the groundwork for reef's VM tree architecture — persistent, long-lived agent sessions that can run locally or on Vers VMs.
What's included
Lieutenant service (services/lieutenant/) — persistent conversational agent sessions with tools for creating, messaging, pausing/resuming, and destroying lieutenants. Includes SQLite-backed state, an RPC layer for VM communication, and a runtime that manages lieutenant lifecycles.
Registry service (services/registry/) — tracks running Vers VMs and their capabilities. Provides tools to list, inspect, and manage registered VMs, plus a behaviors system for automatic VM lifecycle rules.
VM tree service (services/vm-tree/) — hierarchical VM management. Models parent-child relationships between VMs, supports tree-wide operations (pause/resume/destroy subtrees), and persists the tree structure in SQLite.
Bootloader service (services/bootloader/) — provisions new Vers VMs by generating cloud-init configs, injecting SSH keys, and bootstrapping fleet agent installation.
Vers config service (services/vers-config/) — manages Vers API configuration, authentication, and VM spec defaults (region, size, image).
Context
These services were previously in pi-vers but belong in reef as core infrastructure for multi-VM agent orchestration. The migration brings them over with the reef service module pattern (tools, routes, store, events) while removing pi-vers-specific coupling.