Replicas Engine (V1)

Replicas Engine is the workspace runtime that powers coding agents.

This version is built around:

• one canonical event stream (GET /events, SSE)
• multi-chat and multi-thread support for Claude and Codex
• multi-repo workspaces (agents operate from workspace root)

Core model

• Event-first runtime: all meaningful state transitions emit typed EngineEvent payloads.
• Snapshot + stream: clients fetch current state endpoints, then subscribe to /events for deltas.
• Chat-centric API: chats are first-class resources; provider sessions are internal details.

Endpoints

System

• GET /health
• GET /status
• GET /token-refresh/health

Stream

• GET /events (SSE)

Chats

• POST /chats
• GET /chats
• GET /chats/:chatId
• GET /chats/:chatId/history
• POST /chats/:chatId/messages
• POST /chats/:chatId/interrupt
• POST /chats/:chatId/reset

Repos and hooks

• GET /repos
• POST /repos/refresh
• GET /hooks/status

SSE usage

1. Fetch current state from resource endpoints (/status, /chats, /repos, /hooks/status, chat history endpoints).
2. Connect to GET /events and apply incoming events as state deltas.
3. On disconnect/reconnect, fetch state again and resubscribe.

SSE payload format:

• id: stable event id
• event: event type (same as EngineEvent.type)
• data: JSON-serialized event envelope

Multi-chat model

• each chat has its own provider session/thread
• chat metadata and provider session ids are persisted in ~/.replicas/engine/chats.json
• chats are independent, so multiple active chats can run in parallel

Multi-repo model

• workspace root defaults to ~/workspaces
• repos are discovered as directories under root
• agents execute from workspace root and can access all repos by default

Local development

yarn build
yarn dev

Environment essentials:

• REPLICAS_ENGINE_SECRET
• WORKSPACE_ID
• MONOLITH_URL

Optional:

• WORKSPACE_HOME, REPLICAS_REPO_NAME, REPLICAS_DEFAULT_BRANCH

Code layout

• src/index.ts: bootstrapping and server wiring
• src/v1-routes.ts: request validation and route handlers
• src/chat-service.ts: chat orchestration and persistence
• src/event-service.ts: event bus and SSE fanout
• src/providers/: provider adapter interface + Claude/Codex adapters
• src/repo-service.ts: repo discovery and workspace root logic
• src/services/replicas-config.ts: start-hook lifecycle state and config loading

Architecture

Flow:

1. HTTP handlers validate requests.
2. Domain services execute behavior.
3. Domain services publish typed EngineEvent entries.
4. Events are persisted to JSONL and broadcast to SSE subscribers.

Module responsibilities:

• src/v1-routes.ts: route definitions, request validation, typed responses
• src/chat-service.ts: chat registry, persistence, turn orchestration, provider-event lifecycle
• src/event-service.ts: append-only event persistence and subscriber fanout
• src/repo-service.ts: workspace root resolution and repo discovery

Event guarantees:

• every persisted event has id, ts, type, and payload
• /events emits canonical runtime deltas only

Persistence:

• ~/.replicas/engine/chats.json
• ~/.replicas/engine/events.jsonl
• provider-specific session files remain provider-specific

Contributor notes

• keep routes thin and move behavior into services
• keep all payloads strongly typed
• add a new EngineEvent variant for every new externally-visible runtime transition
• prefer explicit naming over implicit side-effects

Add a new event type

1. Add the event variant in @replicas/shared (shared/src/engine/v1.ts).
2. Emit the event from the relevant domain service.
3. Ensure payload is strongly typed and stable.
4. Document the new event in this README if client-facing.

Add a new provider

1. Implement provider manager/adapter in src/managers/src/providers.
2. Ensure chat service can construct and persist provider session identity.
3. Emit canonical chat events from provider outputs.
4. Validate with multiple chats running concurrently.

Quality checklist

• no any in new code
• all external payloads typed
• routes stay thin
• build passes (shared, engine, monolith)
• behavior documented in this README