replicas-engine 0.1.41 → 0.1.42

package/README.md

@@ -2,149 +2,131 @@
 
 Replicas Engine is the workspace runtime that powers coding agents.
 
-This version is built around:
+**Authorization Header**: `X-Replicas-Engine-Secret: <REPLICAS_ENGINE_SECRET>`
 
-- 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 Flow**: 
+1. Fetch snapshots (`/status`, `/chats`, `/repos`, `/hooks/status`).
+2. Open `GET /events` for deltas.
+3. Send messages via `POST /chats/:chatId/messages`.
 
-## Core model
+## Engine API surface (v1)
 
-- **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
+System:
 
 - `GET /health`
 - `GET /status`
 - `GET /token-refresh/health`
 
-### Stream
+Stream:
 
 - `GET /events` (SSE)
 
-### Chats
+Chats:
 
 - `POST /chats`
 - `GET /chats`
 - `GET /chats/:chatId`
+- `DELETE /chats/:chatId`
 - `GET /chats/:chatId/history`
 - `POST /chats/:chatId/messages`
 - `POST /chats/:chatId/interrupt`
-- `POST /chats/:chatId/reset`
 
-### Repos and hooks
+Plans:
 
-- `GET /repos`
-- `POST /repos/refresh`
-- `GET /hooks/status`
+- `GET /plans`
+- `GET /plans/:filename`
 
-## SSE usage
+Repos and hooks:
 
-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.
+- `GET /repos`
+- `GET /repos?includeDiffs=true` (includes `gitDiff.fullDiff`)
+- `GET /hooks/status`
 
-SSE payload format:
+SSE envelope:
 
 - `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
-
-```bash
-yarn build
-yarn dev
-```
-
-Environment essentials:
-
-- `REPLICAS_ENGINE_SECRET`
-- `WORKSPACE_ID`
-- `MONOLITH_URL`
+- `event`: engine event type
+- `data`: JSON-serialized `EngineEvent`
+
+## VM/runtime contract
+
+The engine is expected to run in a VM/sandbox with:
+
+- OS user with writable home (default `/home/ubuntu`)
+- Workspace root at `~/workspaces`
+- Git available in PATH
+- `gh` CLI available in PATH (for PR URL discovery)
+- Claude and Codex CLIs installed/configurable
+
+### Provisioning contract (what monolith injects before engine start)
+
+From `monolith/src/lib/daytona.ts` + `monolith/src/lib/workspaces.ts`, the VM is expected to be prepped with:
+
+- Git identity (optional but expected for commits):
+  - `git config --global user.name <bot-or-user-name>`
+  - `git config --global user.email <bot-or-user-email>`
+- Git credential helper setup when GitHub token is available:
+  - `git config --global credential.helper store`
+  - `~/.git-credentials` with `https://x-access-token:<token>@github.com`
+- Repository materialization:
+  - clone repositories into `/home/ubuntu/workspaces/<repo-name>`
+  - if no repository URL is provided, create empty `/home/ubuntu/workspaces/<repo-name>`
+- Claude credentials (optional):
+  - file: `~/.claude/.credentials.json`
+  - source: OAuth credential object provisioned by monolith
+- Bedrock credentials (optional):
+  - file: `~/.claude/.bedrock-credentials.json`
+  - env: `CLAUDE_CODE_USE_BEDROCK=1`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`
+- Codex credentials (optional):
+  - file: `~/.codex/auth.json`
+  - format includes `tokens.id_token`, `tokens.access_token`, `tokens.refresh_token`, `tokens.account_id`
+
+Token refresh managers may later overwrite credential files in place:
+
+- `~/.git-credentials`
+- `~/.claude/.credentials.json`
+- `~/.codex/auth.json`
+
+Engine persistence locations:
 
-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:
+- `~/.replicas/engine/chats.json`
+- `~/.replicas/engine/events.jsonl`
+- `~/.replicas/engine-state.json`
+- `~/.replicas/startHooks.log`
+- Plan read locations (for `/plans` endpoints):
+  - `~/.claude/plans`
+  - `~/.replicas/plans`
+- Health endpoint readiness signal file:
+  - `/var/log/cloud-init-output.log` (if missing, `/health` reports `initializing`)
 
-- every persisted event has `id`, `ts`, `type`, and `payload`
-- `/events` emits canonical runtime deltas only
+## Environment contract
 
-Persistence:
+`src/engine-env.ts` is the source of truth for engine runtime environment variables.
 
-- `~/.replicas/engine/chats.json`
-- `~/.replicas/engine/events.jsonl`
-- provider-specific session files remain provider-specific
+Use that file to understand:
+- required vars (boot-time validated)
+- optional vars used by engine code
+- ambient/runtime vars captured for SDK/CLI/agent compatibility
 
-## Contributor notes
+Engine env vars are injected by monolith when the engine is started inside sandboxes.
 
-- 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
+Credential files expected/used by provider CLIs:
 
-### Add a new event type
+- `~/.git-credentials` (git/gh auth)
+- `~/.claude/.credentials.json` (Claude OAuth auth)
+- `~/.claude/.bedrock-credentials.json` (Claude Bedrock config)
+- `~/.codex/auth.json` (Codex auth)
 
-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.
+## What the engine sends upstream
 
-### Add a new provider
+The engine calls monolith with:
 
-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.
+- `Authorization: Bearer <REPLICAS_ENGINE_SECRET>`
+- `X-Workspace-Id: <WORKSPACE_ID>`
 
-### Quality checklist
+Outgoing endpoints:
 
-- no `any` in new code
-- all external payloads typed
-- routes stay thin
-- build passes (`shared`, `engine`, `monolith`)
-- behavior documented in this README
+- `POST /v1/engine/webhook`
+- `POST /v1/engine/github/refresh-token`
+- `POST /v1/engine/claude/refresh-credentials`
+- `POST /v1/engine/codex/refresh-credentials`