replicas-engine 0.1.37 → 0.1.39
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +150 -0
- package/dist/src/index.js +2701 -1965
- package/package.json +2 -1
package/README.md
ADDED
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
# Replicas Engine (V1)
|
|
2
|
+
|
|
3
|
+
Replicas Engine is the workspace runtime that powers coding agents.
|
|
4
|
+
|
|
5
|
+
This version is built around:
|
|
6
|
+
|
|
7
|
+
- one canonical event stream (`GET /events`, SSE)
|
|
8
|
+
- multi-chat and multi-thread support for Claude and Codex
|
|
9
|
+
- multi-repo workspaces (agents operate from workspace root)
|
|
10
|
+
|
|
11
|
+
## Core model
|
|
12
|
+
|
|
13
|
+
- **Event-first runtime**: all meaningful state transitions emit typed `EngineEvent` payloads.
|
|
14
|
+
- **Snapshot + stream**: clients fetch current state endpoints, then subscribe to `/events` for deltas.
|
|
15
|
+
- **Chat-centric API**: chats are first-class resources; provider sessions are internal details.
|
|
16
|
+
|
|
17
|
+
## Endpoints
|
|
18
|
+
|
|
19
|
+
### System
|
|
20
|
+
|
|
21
|
+
- `GET /health`
|
|
22
|
+
- `GET /status`
|
|
23
|
+
- `GET /token-refresh/health`
|
|
24
|
+
|
|
25
|
+
### Stream
|
|
26
|
+
|
|
27
|
+
- `GET /events` (SSE)
|
|
28
|
+
|
|
29
|
+
### Chats
|
|
30
|
+
|
|
31
|
+
- `POST /chats`
|
|
32
|
+
- `GET /chats`
|
|
33
|
+
- `GET /chats/:chatId`
|
|
34
|
+
- `GET /chats/:chatId/history`
|
|
35
|
+
- `POST /chats/:chatId/messages`
|
|
36
|
+
- `POST /chats/:chatId/interrupt`
|
|
37
|
+
- `POST /chats/:chatId/reset`
|
|
38
|
+
|
|
39
|
+
### Repos and hooks
|
|
40
|
+
|
|
41
|
+
- `GET /repos`
|
|
42
|
+
- `POST /repos/refresh`
|
|
43
|
+
- `GET /hooks/status`
|
|
44
|
+
|
|
45
|
+
## SSE usage
|
|
46
|
+
|
|
47
|
+
1. Fetch current state from resource endpoints (`/status`, `/chats`, `/repos`, `/hooks/status`, chat history endpoints).
|
|
48
|
+
2. Connect to `GET /events` and apply incoming events as state deltas.
|
|
49
|
+
3. On disconnect/reconnect, fetch state again and resubscribe.
|
|
50
|
+
|
|
51
|
+
SSE payload format:
|
|
52
|
+
|
|
53
|
+
- `id`: stable event id
|
|
54
|
+
- `event`: event type (same as `EngineEvent.type`)
|
|
55
|
+
- `data`: JSON-serialized event envelope
|
|
56
|
+
|
|
57
|
+
## Multi-chat model
|
|
58
|
+
|
|
59
|
+
- each chat has its own provider session/thread
|
|
60
|
+
- chat metadata and provider session ids are persisted in `~/.replicas/engine/chats.json`
|
|
61
|
+
- chats are independent, so multiple active chats can run in parallel
|
|
62
|
+
|
|
63
|
+
## Multi-repo model
|
|
64
|
+
|
|
65
|
+
- workspace root defaults to `~/workspaces`
|
|
66
|
+
- repos are discovered as directories under root
|
|
67
|
+
- agents execute from workspace root and can access all repos by default
|
|
68
|
+
|
|
69
|
+
## Local development
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
yarn build
|
|
73
|
+
yarn dev
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Environment essentials:
|
|
77
|
+
|
|
78
|
+
- `REPLICAS_ENGINE_SECRET`
|
|
79
|
+
- `WORKSPACE_ID`
|
|
80
|
+
- `MONOLITH_URL`
|
|
81
|
+
|
|
82
|
+
Optional:
|
|
83
|
+
|
|
84
|
+
- `WORKSPACE_HOME`, `REPLICAS_REPO_NAME`, `REPLICAS_DEFAULT_BRANCH`
|
|
85
|
+
|
|
86
|
+
## Code layout
|
|
87
|
+
|
|
88
|
+
- `src/index.ts`: bootstrapping and server wiring
|
|
89
|
+
- `src/v1-routes.ts`: request validation and route handlers
|
|
90
|
+
- `src/chat-service.ts`: chat orchestration and persistence
|
|
91
|
+
- `src/event-service.ts`: event bus and SSE fanout
|
|
92
|
+
- `src/providers/`: provider adapter interface + Claude/Codex adapters
|
|
93
|
+
- `src/repo-service.ts`: repo discovery and workspace root logic
|
|
94
|
+
- `src/services/replicas-config.ts`: start-hook lifecycle state and config loading
|
|
95
|
+
|
|
96
|
+
## Architecture
|
|
97
|
+
|
|
98
|
+
Flow:
|
|
99
|
+
|
|
100
|
+
1. HTTP handlers validate requests.
|
|
101
|
+
2. Domain services execute behavior.
|
|
102
|
+
3. Domain services publish typed `EngineEvent` entries.
|
|
103
|
+
4. Events are persisted to JSONL and broadcast to SSE subscribers.
|
|
104
|
+
|
|
105
|
+
Module responsibilities:
|
|
106
|
+
|
|
107
|
+
- `src/v1-routes.ts`: route definitions, request validation, typed responses
|
|
108
|
+
- `src/chat-service.ts`: chat registry, persistence, turn orchestration, provider-event lifecycle
|
|
109
|
+
- `src/event-service.ts`: append-only event persistence and subscriber fanout
|
|
110
|
+
- `src/repo-service.ts`: workspace root resolution and repo discovery
|
|
111
|
+
|
|
112
|
+
Event guarantees:
|
|
113
|
+
|
|
114
|
+
- every persisted event has `id`, `ts`, `type`, and `payload`
|
|
115
|
+
- `/events` emits canonical runtime deltas only
|
|
116
|
+
|
|
117
|
+
Persistence:
|
|
118
|
+
|
|
119
|
+
- `~/.replicas/engine/chats.json`
|
|
120
|
+
- `~/.replicas/engine/events.jsonl`
|
|
121
|
+
- provider-specific session files remain provider-specific
|
|
122
|
+
|
|
123
|
+
## Contributor notes
|
|
124
|
+
|
|
125
|
+
- keep routes thin and move behavior into services
|
|
126
|
+
- keep all payloads strongly typed
|
|
127
|
+
- add a new `EngineEvent` variant for every new externally-visible runtime transition
|
|
128
|
+
- prefer explicit naming over implicit side-effects
|
|
129
|
+
|
|
130
|
+
### Add a new event type
|
|
131
|
+
|
|
132
|
+
1. Add the event variant in `@replicas/shared` (`shared/src/engine/v1.ts`).
|
|
133
|
+
2. Emit the event from the relevant domain service.
|
|
134
|
+
3. Ensure payload is strongly typed and stable.
|
|
135
|
+
4. Document the new event in this README if client-facing.
|
|
136
|
+
|
|
137
|
+
### Add a new provider
|
|
138
|
+
|
|
139
|
+
1. Implement provider manager/adapter in `src/managers`/`src/providers`.
|
|
140
|
+
2. Ensure chat service can construct and persist provider session identity.
|
|
141
|
+
3. Emit canonical chat events from provider outputs.
|
|
142
|
+
4. Validate with multiple chats running concurrently.
|
|
143
|
+
|
|
144
|
+
### Quality checklist
|
|
145
|
+
|
|
146
|
+
- no `any` in new code
|
|
147
|
+
- all external payloads typed
|
|
148
|
+
- routes stay thin
|
|
149
|
+
- build passes (`shared`, `engine`, `monolith`)
|
|
150
|
+
- behavior documented in this README
|