opencode-orchestrator 1.3.4 → 1.3.6
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 +76 -370
- package/dist/agents/prompts/02_discovery/agents/discovery_commander.d.ts +1 -5
- package/dist/agents/prompts/02_discovery/agents/discovery_planner.d.ts +1 -5
- package/dist/agents/prompts/03_planning/agents/planning_commander.d.ts +1 -5
- package/dist/agents/prompts/04_execution/agents/execution_commander.d.ts +1 -5
- package/dist/agents/prompts/04_execution/agents/execution_worker.d.ts +1 -5
- package/dist/agents/prompts/04_execution/execution_error_handling.d.ts +1 -5
- package/dist/agents/prompts/05_verification/agents/verification_commander.d.ts +1 -5
- package/dist/agents/prompts/05_verification/verification_build.d.ts +1 -5
- package/dist/agents/prompts/05_verification/verification_test.d.ts +1 -5
- package/dist/agents/prompts/06_mission/agents/mission_commander.d.ts +1 -5
- package/dist/agents/prompts/06_mission/mission_lifecycle.d.ts +1 -5
- package/dist/agents/prompts/07_agents/commander/commander_mandate.d.ts +1 -5
- package/dist/agents/prompts/07_agents/planner/planner_mandate.d.ts +1 -5
- package/dist/agents/prompts/07_agents/reviewer/reviewer_mandate.d.ts +1 -5
- package/dist/agents/prompts/07_agents/worker/worker_mandate.d.ts +1 -5
- package/dist/agents/prompts/08_tools/tools_code_editing.d.ts +1 -5
- package/dist/agents/prompts/08_tools/tools_testing.d.ts +1 -5
- package/dist/core/orchestrator/state.d.ts +1 -1
- package/dist/hooks/features/mission-loop.d.ts +1 -0
- package/dist/index.js +151 -41
- package/dist/plugin-handlers/interfaces/session-state.d.ts +3 -0
- package/dist/scripts/postinstall.js +21 -10
- package/dist/scripts/preuninstall.js +20 -11
- package/dist/shared/core/constants/limits.d.ts +1 -1
- package/dist/shared/loop/constants/loop.d.ts +1 -1
- package/dist/shared/loop/constants/mission-control.d.ts +2 -2
- package/dist/shared/loop/interfaces/mission-loop.d.ts +1 -1
- package/dist/shared/session/constants/events/index.d.ts +2 -0
- package/dist/shared/session/constants/events/session-events.d.ts +3 -0
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,59 +1,44 @@
|
|
|
1
|
-
|
|
2
|
-
---
|
|
3
|
-
|
|
4
1
|
<div align="center">
|
|
5
|
-
<img src="assets/logo.png" alt="logo" width="
|
|
2
|
+
<img src="assets/logo.png" alt="OpenCode Orchestrator logo" width="160" />
|
|
6
3
|
<h1>OpenCode Orchestrator</h1>
|
|
7
|
-
<p>
|
|
4
|
+
<p>Multi-agent mission control for OpenCode.</p>
|
|
8
5
|
|
|
9
6
|
[](LICENSE)
|
|
10
7
|
[](https://www.npmjs.com/package/opencode-orchestrator)
|
|
11
8
|
<!-- VERSION:START -->
|
|
12
|
-
**Version:** `1.3.
|
|
9
|
+
**Version:** `1.3.6`
|
|
13
10
|
<!-- VERSION:END -->
|
|
14
11
|
</div>
|
|
15
12
|
|
|
16
|
-
|
|
17
13
|
---
|
|
18
14
|
|
|
19
|
-
##
|
|
15
|
+
## 1. Install
|
|
20
16
|
|
|
21
17
|
```bash
|
|
22
18
|
npm install -g opencode-orchestrator
|
|
23
19
|
```
|
|
24
20
|
|
|
25
|
-
|
|
21
|
+
The install hook merges OpenCode config instead of replacing it, prefers `opencode.jsonc` when present, preserves existing plugin tuple options, and skips automatic config mutation in CI.
|
|
26
22
|
|
|
27
|
-
To remove the plugin
|
|
23
|
+
To remove the plugin from OpenCode config:
|
|
28
24
|
|
|
29
25
|
```bash
|
|
30
26
|
npm explore -g opencode-orchestrator -- npm run cleanup:plugin
|
|
31
27
|
npm uninstall -g opencode-orchestrator
|
|
32
28
|
```
|
|
33
29
|
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
### Model, Permissions, and Concurrency
|
|
30
|
+
Manual fallback: remove `"opencode-orchestrator"` or `["opencode-orchestrator", {...}]` from the `plugin` array in `opencode.json` or `opencode.jsonc`.
|
|
37
31
|
|
|
38
|
-
|
|
32
|
+
## 2. Configure
|
|
39
33
|
|
|
40
|
-
|
|
34
|
+
OpenCode supports plugin options as `["plugin-name", {...}]` tuples. Use that form for orchestrator-specific settings:
|
|
41
35
|
|
|
42
36
|
```jsonc
|
|
43
37
|
{
|
|
44
38
|
"$schema": "https://opencode.ai/config.json",
|
|
45
|
-
"model": "opencode/gpt-5.1-codex",
|
|
46
39
|
"permission": {
|
|
47
40
|
"question": "allow"
|
|
48
41
|
},
|
|
49
|
-
"agent": {
|
|
50
|
-
"commander": {
|
|
51
|
-
"model": "opencode/gpt-5.1-codex"
|
|
52
|
-
},
|
|
53
|
-
"worker": {
|
|
54
|
-
"model": "anthropic/claude-opus-4-5-20251101"
|
|
55
|
-
}
|
|
56
|
-
},
|
|
57
42
|
"plugin": [
|
|
58
43
|
[
|
|
59
44
|
"opencode-orchestrator",
|
|
@@ -75,371 +60,92 @@ Recommended `opencode.jsonc` configuration:
|
|
|
75
60
|
}
|
|
76
61
|
```
|
|
77
62
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
Inside an OpenCode environment:
|
|
81
|
-
```bash
|
|
82
|
-
/task "Implement a new authentication module with JWT and audit logs"
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
---
|
|
87
|
-
|
|
88
|
-
## 🚀 Engine Workflow
|
|
89
|
-
|
|
90
|
-
**Hub-and-Spoke Architecture** with Work-Stealing Queues for parallel, context-isolated task execution.
|
|
91
|
-
```
|
|
92
|
-
╔══════════════════════════════════════════════════════════════════════════════╗
|
|
93
|
-
║ USER INPUT /task "..." ║
|
|
94
|
-
╚══════════════════════════════════════════════════════════════════════════════╝
|
|
95
|
-
│
|
|
96
|
-
▼
|
|
97
|
-
╔══════════════════════════════════════════════════════════════════════════════╗
|
|
98
|
-
║ ┌─────────────────────────────────────────────────────────────────────────┐ ║
|
|
99
|
-
║ │ C O M M A N D E R │ ║
|
|
100
|
-
║ │ [ Mission Analysis & Delegation ] │ ║
|
|
101
|
-
║ │ │ ║
|
|
102
|
-
║ │ • Interprets user intent • Coordinates multi-agent workflow │ ║
|
|
103
|
-
║ │ • Monitors progress • Manages work-stealing queues │ ║
|
|
104
|
-
║ └─────────────────────────────────────────────────────────────────────────┘ ║
|
|
105
|
-
╚══════════════════════════════════════════════════════════════════════════════╝
|
|
106
|
-
│
|
|
107
|
-
┌───────────────┼───────────────┐
|
|
108
|
-
▼ ▼ ▼
|
|
109
|
-
╔═════════════════╗ ╔═════════════════╗ ╔═════════════════╗
|
|
110
|
-
║ P L A N N E R ║ ║ W O R K E R ║ ║ W O R K E R ║
|
|
111
|
-
║ [Architect] ║ ║ [Implementer] ║ ║ [Implementer] ║
|
|
112
|
-
║ ║ ║ ║ ║ ║
|
|
113
|
-
║ • Dependency ║ ║ • File coding ║ ║ • File coding ║
|
|
114
|
-
║ analysis ║ ║ • TDD workflow ║ ║ • TDD workflow ║
|
|
115
|
-
║ • Roadmap gen ║ ║ • Documentation║ ║ • Documentation║
|
|
116
|
-
║ • TODO.md ║ ║ ║ ║ ║
|
|
117
|
-
╚═════════════════╝ ╚═════════════════╝ ╚═════════════════╝
|
|
118
|
-
│ │ │
|
|
119
|
-
│ ┌──────────────┼─────────────────────┘
|
|
120
|
-
│ │ │
|
|
121
|
-
▼ ▼ ▼
|
|
122
|
-
╔══════════════════════════════════════╗
|
|
123
|
-
║ SESSION POOL (MVCC Sync) ║
|
|
124
|
-
║ ┌─────────────────────────────────┐ ║
|
|
125
|
-
║ │ Object Pool │ Buffer Pool │ ║
|
|
126
|
-
║ │ String Pool │ Connection Pool │ ║
|
|
127
|
-
║ └─────────────────────────────────┘ ║
|
|
128
|
-
╚══════════════════════════════════════╝
|
|
129
|
-
│
|
|
130
|
-
▼
|
|
131
|
-
╔══════════════════════════════════════╗
|
|
132
|
-
║ MSVP MONITOR / REVIEWER ║
|
|
133
|
-
║ ┌─────────────────────────────────┐ ║
|
|
134
|
-
║ │ • Adaptive polling (500ms-5s) │ ║
|
|
135
|
-
║ │ • Stability detection │ ║
|
|
136
|
-
║ │ • Unit test verification │ ║
|
|
137
|
-
║ └─────────────────────────────────┘ ║
|
|
138
|
-
╚══════════════════════════════════════╝
|
|
139
|
-
│
|
|
140
|
-
▼
|
|
141
|
-
┌────────────────┐
|
|
142
|
-
│ ✨ COMPLETED │
|
|
143
|
-
└────────────────┘
|
|
144
|
-
```
|
|
145
|
-
|
|
146
|
-
---
|
|
147
|
-
|
|
148
|
-
## 🏗️ Architecture Layers
|
|
63
|
+
Optional model routing stays in normal OpenCode config. The plugin does not force a model:
|
|
149
64
|
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
│ │ │ Commander │ │ Planner │ │ Worker │ │ Reviewer │ │ │
|
|
163
|
-
│ │ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │ │
|
|
164
|
-
│ │ └────────────┘ └────────────┘ └────────────┘ └────────────────┘ │ │
|
|
165
|
-
│ └───────────────────────────────────────────────────────────────────────┘ │
|
|
166
|
-
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────────┐│
|
|
167
|
-
│ │ Concurrency │ │ Task Store │ │ Hook System ││
|
|
168
|
-
│ │ Controller │ │ (In-Memory) │ │ [Early/Normal/Late Phases] ││
|
|
169
|
-
│ └─────────────────┘ └─────────────────┘ └─────────────────────────────┘│
|
|
170
|
-
├─────────────────────────────────────────────────────────────────────────────┤
|
|
171
|
-
│ INFRASTRUCTURE LAYER │
|
|
172
|
-
│ ┌────────────────┐ ┌────────────────┐ ┌────────────────────────────┐ │
|
|
173
|
-
│ │ Session Pool │ │ Work-Stealing │ │ Memory Pools │ │
|
|
174
|
-
│ │ [5 per agent] │ │ [Chase-Lev] │ │ ┌──────┐ ┌──────┐ ┌─────┐│ │
|
|
175
|
-
│ │ [10 reuse max] │ │ [LIFO/FIFO] │ │ │Object│ │String│ │Buffer││ │
|
|
176
|
-
│ └────────────────┘ └────────────────┘ │ │ 200 │ │ intern│ │ 4KB ││ │
|
|
177
|
-
│ │ └──────┘ └──────┘ └─────┘│ │
|
|
178
|
-
│ ┌────────────────┐ ┌────────────────┐ └────────────────────────────┘ │
|
|
179
|
-
│ │ MVCC State │ │ Circuit Breaker │ ┌────────────────────────────┐ │
|
|
180
|
-
│ │ [Atomic Sync] │ │ [5 failures→open│ │ Rust Connection Pool │ │
|
|
181
|
-
│ │ │ │ [2 success→close│ │ [4 processes, 30s idle] │ │
|
|
182
|
-
│ └────────────────┘ └────────────────┘ └────────────────────────────┘ │
|
|
183
|
-
├─────────────────────────────────────────────────────────────────────────────┤
|
|
184
|
-
│ SAFETY LAYER │
|
|
185
|
-
│ ┌────────────────┐ ┌────────────────┐ ┌─────────────────────────────┐ │
|
|
186
|
-
│ │ RAII Pattern │ │ Shutdown │ │ Auto-Recovery │ │
|
|
187
|
-
│ │ [Zero Leaks] │ │ Manager │ │ [Exponential Backoff] │ │
|
|
188
|
-
│ │ │ │ [5s timeout] │ │ [Rate limit handling] │ │
|
|
189
|
-
│ └────────────────┘ └────────────────┘ └─────────────────────────────┘ │
|
|
190
|
-
└─────────────────────────────────────────────────────────────────────────────┘
|
|
65
|
+
```jsonc
|
|
66
|
+
{
|
|
67
|
+
"model": "provider/model-id",
|
|
68
|
+
"agent": {
|
|
69
|
+
"commander": {
|
|
70
|
+
"model": "provider/model-id"
|
|
71
|
+
},
|
|
72
|
+
"worker": {
|
|
73
|
+
"model": "provider/stronger-model-id"
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
191
77
|
```
|
|
192
78
|
|
|
193
|
-
|
|
79
|
+
Generated Commander, Planner, Worker, and Reviewer agents inherit global permissions. Same-name user agent config can still override specific model or permission keys.
|
|
194
80
|
|
|
195
|
-
##
|
|
81
|
+
## 3. Run
|
|
196
82
|
|
|
197
|
-
|
|
83
|
+
Inside OpenCode:
|
|
198
84
|
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
├── fixture.ts Disposable tmpdir utilities
|
|
202
|
-
│ ├── tmpdir() async disposable with cleanup
|
|
203
|
-
│ ├── tmpdirSync() sync disposable with cleanup
|
|
204
|
-
│ ├── createMockFs() In-memory fs mock
|
|
205
|
-
│ └── waitFor() Async condition waiter
|
|
206
|
-
│
|
|
207
|
-
├── builders.ts Factory functions for test objects
|
|
208
|
-
│ ├── createParallelTask() Build ParallelTask instances
|
|
209
|
-
│ ├── createBackgroundTask() Build BackgroundTask instances
|
|
210
|
-
│ └── createTodo() Build Todo instances
|
|
211
|
-
│
|
|
212
|
-
├── mocks.ts Mock utilities
|
|
213
|
-
│ ├── mockConsole() Spy on console.log/error
|
|
214
|
-
│ ├── mockProcessExit() Mock process.exit
|
|
215
|
-
│ ├── useFakeTimers() Time manipulation
|
|
216
|
-
│ └── createMockEmitter() EventEmitter spy
|
|
217
|
-
│
|
|
218
|
-
└── index.ts Unified exports
|
|
85
|
+
```bash
|
|
86
|
+
/task "Implement the requested change and verify it"
|
|
219
87
|
```
|
|
220
88
|
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
expect(task.status).toBe("pending");
|
|
242
|
-
});
|
|
243
|
-
});
|
|
89
|
+
Mission controls:
|
|
90
|
+
|
|
91
|
+
1. `/task ...` starts a persisted mission loop under `.opencode/`.
|
|
92
|
+
2. `Esc`/OpenCode interrupt is respected by idle guards so the plugin does not immediately re-continue an interrupted turn.
|
|
93
|
+
3. `/cancel` and `/stop` deactivate the current mission loop.
|
|
94
|
+
4. The default mission iteration ceiling is `1,000,000,000`.
|
|
95
|
+
|
|
96
|
+
## 4. How It Works
|
|
97
|
+
|
|
98
|
+
```mermaid
|
|
99
|
+
flowchart LR
|
|
100
|
+
U["/task input"] --> C["Commander"]
|
|
101
|
+
C --> P["Planner"]
|
|
102
|
+
C --> W["Worker pool"]
|
|
103
|
+
W --> R["Reviewer"]
|
|
104
|
+
P --> S["Mission state"]
|
|
105
|
+
W --> S
|
|
106
|
+
R --> V{"Verified?"}
|
|
107
|
+
V -- "no" --> C
|
|
108
|
+
V -- "yes" --> D["Done"]
|
|
244
109
|
```
|
|
245
110
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
|
251
|
-
|
|
252
|
-
| **Commander** | Mission Hub | Task decomposition, agent coordination, work-stealing orchestration, final mission seal |
|
|
253
|
-
| **Planner** | Architect | Dependency analysis, roadmap generation, TODO.md creation via MVCC, file-level planning |
|
|
254
|
-
| **Worker** | Implementer | High-throughput coding, TDD workflow, documentation, isolated file execution |
|
|
255
|
-
| **Reviewer** | Auditor | Unit test verification, LSP/Lint validation, integration testing, quality gate |
|
|
256
|
-
---
|
|
257
|
-
|
|
258
|
-
## 🛠️ Core Capabilities
|
|
259
|
-
|
|
260
|
-
### 🔒 Atomic MVCC State Synchronization
|
|
261
|
-
Solves the "Concurrent TODO Update" problem using **MVCC + Mutex**. Agents safely mark tasks complete in parallel without data loss or race conditions. Every state change is cryptographically hashed and logged.
|
|
111
|
+
| Agent | Purpose |
|
|
112
|
+
| --- | --- |
|
|
113
|
+
| Commander | Interprets the mission, coordinates agents, and keeps the loop aligned. |
|
|
114
|
+
| Planner | Breaks work into ordered steps and tracks dependencies. |
|
|
115
|
+
| Worker | Implements scoped file changes with isolated context. |
|
|
116
|
+
| Reviewer | Checks completion evidence, tests, and integration risk. |
|
|
262
117
|
|
|
263
|
-
|
|
264
|
-
Execution flows governed by a **Priority-Phase Hook Registry**. Hooks are grouped into phases (`early`, `normal`, `late`) and executed via **Topological Sort** for predictable, dependency-aware ordering.
|
|
118
|
+
Runtime evidence is written only when enabled:
|
|
265
119
|
|
|
266
|
-
|
|
267
|
-
|
|
120
|
+
| Artifact | Purpose |
|
|
121
|
+
| --- | --- |
|
|
122
|
+
| `.opencode/mission-ledger.jsonl` | Bounded event trail for mission decisions. |
|
|
123
|
+
| `.opencode/docs/brain/scratchpad.md` | Generated Markdown memory surface for active missions. |
|
|
124
|
+
| `.opencode/docs/brain/knowledge-map.canvas` | Obsidian-compatible visual map of objective, evidence, and verification nodes. |
|
|
268
125
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
### 🛡️ Autonomous Recovery
|
|
272
|
-
- **Self-healing loops** with adaptive stagnation detection
|
|
273
|
-
- **Proactive Agency**: Smart monitoring that audits logs and plans ahead during background tasks
|
|
274
|
-
- **Auto-retry with backoff**: Exponential backoff for transient failures
|
|
275
|
-
|
|
276
|
-
### 🎯 State-Level Session Isolation
|
|
277
|
-
Reused sessions in the **SessionPool** are explicitly reset via server-side compaction, ensuring previous task context never leaks into new tasks.
|
|
278
|
-
|
|
279
|
-
### 🚀 Zero-Payload Turbo Mode
|
|
280
|
-
Leverages `system.transform` to unshift agent instruction sets server-side, reducing initial message payloads by **90%+** and preventing context fragmentation.
|
|
281
|
-
|
|
282
|
-
### 🧠 Hierarchical Memory System
|
|
283
|
-
Maintains focus across thousands of conversation turns using a 4-tier memory structure with **EMA-based Context Gating** to preserve architectural truth while pruning noise.
|
|
284
|
-
|
|
285
|
-
### 🔄 Adaptive Intelligence Loop
|
|
286
|
-
- **Stagnation Detection**: Senses when no progress is made across iterations
|
|
287
|
-
- **Diagnostic Intervention**: Forces "Diagnostic Mode" mandating log audits and strategy pivots
|
|
288
|
-
- **Proactive Agency**: Mandates Speculative Planning during background task execution
|
|
289
|
-
|
|
290
|
-
### 🧬 Knowledge Graph RAG (Second Brain)
|
|
291
|
-
An autonomous **Obsidian-style evolutionary memory system** that gives agents persistent, searchable knowledge across sessions.
|
|
292
|
-
|
|
293
|
-
Runtime context injection is active for orchestrated sessions through `experimental.chat.system.transform`, indexing `docs/**/*.md` and `.opencode/docs/**/*.md` with BM25/tag/graph fusion before prompt injection.
|
|
294
|
-
|
|
295
|
-
During active missions, generated runtime memory is available at `.opencode/docs/brain/scratchpad.md`; `.opencode/docs/brain/knowledge-map.canvas` provides an Obsidian-compatible visual map of objective, runtime, verification, and recent evidence nodes.
|
|
296
|
-
|
|
297
|
-
```
|
|
298
|
-
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
299
|
-
│ 📝 Ingest │────▶│ 🔍 Search │────▶│ 🧠 Recall │
|
|
300
|
-
│ ────────── │ │ ────────── │ │ ────────── │
|
|
301
|
-
│ YAML Parser │ │ BM25 Lexical│ │ RRF-Ranked │
|
|
302
|
-
│ Tag HashMap │ │ Tag Index │ │ Top-K Notes │
|
|
303
|
-
│ Wiki-Links │ │ 2-Hop Graph │ │ → Context │
|
|
304
|
-
└──────┬───────┘ └──────────────┘ └──────────────┘
|
|
305
|
-
│
|
|
306
|
-
▼
|
|
307
|
-
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
308
|
-
│ 🔄 Evolve │────▶│ 🛡️ Guard │────▶│ 📦 Archive │
|
|
309
|
-
│ ────────── │ │ ────────── │ │ ────────── │
|
|
310
|
-
│ Fission │ │ Cycle DFS │ │ Orphan GC │
|
|
311
|
-
│ Fusion │ │ Write FIFO │ │ MOC Hubs │
|
|
312
|
-
│ (Auto-Split │ │ Keep-Pin │ │ MD Export │
|
|
313
|
-
│ & Merge) │ │ Shield │ │ │
|
|
314
|
-
└──────────────┘ └──────────────┘ └──────────────┘
|
|
315
|
-
```
|
|
316
|
-
|
|
317
|
-
**Six integrated modules** power the knowledge pipeline:
|
|
318
|
-
|
|
319
|
-
| Module | Purpose |
|
|
320
|
-
|:-------|:--------|
|
|
321
|
-
| **TagIndexer** | O(1) YAML frontmatter parsing → tag-to-file HashMap |
|
|
322
|
-
| **GraphParser** | `[[wiki-link]]` extraction, bi-directional adjacency graph |
|
|
323
|
-
| **HybridSearch** | BM25 + Tag + 2-Hop Graph → **Reciprocal Rank Fusion** (k=60) |
|
|
324
|
-
| **Scratchpad** | LRU register cache (64 slots, 4KB max) with markdown persistence |
|
|
325
|
-
| **SafetyGuards** | Circular link DFS, async FIFO write queue, keep-pin shield |
|
|
326
|
-
| **MemoryConsolidation** | Fission/Fusion/GC/MOC — pure functional analysis |
|
|
327
|
-
|
|
328
|
-
---
|
|
329
|
-
|
|
330
|
-
## ⚙️ Performance Benchmarks
|
|
331
|
-
|
|
332
|
-
| Metric | Improvement |
|
|
333
|
-
|:-------|:------------|
|
|
334
|
-
| CPU Utilization | 90%+ (up from 50-70%) |
|
|
335
|
-
| Tool Call Speed | 10x faster (5-10ms vs 50-100ms) via Rust pool |
|
|
336
|
-
| Session Creation | 90% faster (50ms vs 500ms) via session pooling |
|
|
337
|
-
| Memory Usage | 60% reduction via object/string/buffer pooling |
|
|
338
|
-
| GC Pressure | 80% reduction |
|
|
339
|
-
| Token Efficiency | 40% reduction via Incremental State & System Transform |
|
|
340
|
-
| Sync Accuracy | 99.95% via MVCC+Mutex |
|
|
341
|
-
| Parallel Efficiency | 80% improvement (50% → 90%+) |
|
|
342
|
-
|
|
343
|
-
---
|
|
344
|
-
|
|
345
|
-
## 🏗️ Infrastructure & Reliability
|
|
346
|
-
|
|
347
|
-
### Resource Safety
|
|
348
|
-
- **RAII Pattern**: Guaranteed resource cleanup with zero leaks
|
|
349
|
-
- **ShutdownManager**: Priority-based graceful shutdown (5s timeout per handler)
|
|
350
|
-
- **Atomic File Operations**: Temp file + rename for corruption-proof writes
|
|
351
|
-
- **Automatic Backups**: Timestamped config backups with rollback support
|
|
352
|
-
|
|
353
|
-
### Safety Features
|
|
354
|
-
- **Circuit Breaker**: Auto-recovery from API failures (5 failures → open)
|
|
355
|
-
- **Resource Pressure Detection**: Rejects low-priority tasks when memory > 80%
|
|
356
|
-
- **Terminal Node Guard**: Prevents infinite recursion via depth limit
|
|
357
|
-
- **Auto-Scaling**: Concurrency slots adjust based on success/failure rate
|
|
358
|
-
|
|
359
|
-
### Technical Stack
|
|
360
|
-
- **Runtime**: Node.js 24+ (TypeScript)
|
|
361
|
-
- **Tools**: Rust-based CLI tools (grep, glob, ast) via connection pool
|
|
362
|
-
- **Concurrency**: Chase-Lev work-stealing deque + priority queues
|
|
363
|
-
- **Memory**: Object pooling + string interning + buffer pooling
|
|
364
|
-
- **State Management**: MVCC + Mutex
|
|
365
|
-
- **Safety**: RAII + circuit breaker + resource pressure detection
|
|
366
|
-
- **Knowledge**: In-memory graph RAG with BM25/Tag/Graph search fusion
|
|
367
|
-
|
|
368
|
-
---
|
|
369
|
-
|
|
370
|
-
## 🔧 Installation & Configuration
|
|
371
|
-
|
|
372
|
-
### Safe Installation
|
|
373
|
-
The installation process is **production-safe** with multiple protection layers:
|
|
374
|
-
|
|
375
|
-
1. ✅ **Never overwrites** — always merges with existing config
|
|
376
|
-
2. ✅ **Automatic backups** — timestamped, last 5 kept
|
|
377
|
-
3. ✅ **Atomic writes** — temp file + rename (OS-level atomic)
|
|
378
|
-
4. ✅ **Automatic rollback** — restores from backup on any failure
|
|
379
|
-
5. ✅ **Cross-platform** — Windows (native, Git Bash, WSL2), macOS, Linux
|
|
380
|
-
6. ✅ **CI-aware** — skips non-essential operations in CI environments
|
|
381
|
-
7. ✅ **Timeout protection** — 30s timeout prevents hanging
|
|
382
|
-
8. ✅ **Graceful degradation** — exits 0 on non-critical failures
|
|
383
|
-
|
|
384
|
-
### Safe Removal
|
|
385
|
-
OpenCode config cleanup is provided as an explicit command because global package uninstall does not invoke dependency uninstall hooks in the npm flow validated for this package.
|
|
126
|
+
## 5. Developer Notes
|
|
386
127
|
|
|
387
128
|
```bash
|
|
388
|
-
npm
|
|
389
|
-
|
|
129
|
+
npm run build
|
|
130
|
+
npx tsc --noEmit
|
|
131
|
+
npm test
|
|
132
|
+
cargo test --workspace --all-targets
|
|
390
133
|
```
|
|
391
134
|
|
|
392
|
-
|
|
393
|
-
- Open `~/.config/opencode/opencode.json` or `opencode.jsonc`
|
|
394
|
-
- Remove `"opencode-orchestrator"` from the `plugin` array
|
|
395
|
-
|
|
396
|
-
### Configuration Logs
|
|
397
|
-
- Unix: `/tmp/opencode-orchestrator.log`
|
|
398
|
-
- Windows: `%TEMP%\opencode-orchestrator.log`
|
|
135
|
+
Useful references:
|
|
399
136
|
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
### Test Utilities
|
|
405
|
-
Reusable helpers under `tests/harness/` provide:
|
|
406
|
-
- **Disposable tmpdir**: Automatic cleanup with `Symbol.asyncDispose` / `Symbol.dispose`
|
|
407
|
-
- **Test builders**: Factory functions for `ParallelTask`, `BackgroundTask`, `Todo`
|
|
408
|
-
- **Mock utilities**: Console, process, timers, file system, event emitter mocks
|
|
137
|
+
1. OpenCode plugins: https://opencode.ai/docs/plugins/
|
|
138
|
+
2. OpenCode config: https://opencode.ai/docs/config/
|
|
139
|
+
3. OpenCode keybinds: https://opencode.ai/docs/keybinds/
|
|
140
|
+
4. Project issues: https://github.com/agnusdei1207/opencode-orchestrator/issues
|
|
409
141
|
|
|
410
|
-
|
|
411
|
-
import { tmpdir, createParallelTask, mockConsole } from "@/tests/harness";
|
|
142
|
+
Config logs:
|
|
412
143
|
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
### TUI Stability
|
|
418
|
-
- **Cleanup guarantees**: `initToastClient()` returns a cleanup function
|
|
419
|
-
- **Timeout protection**: AbortController-based 2-10s timeout for async toast operations
|
|
420
|
-
- **Error isolation**: Try/catch around all toast operations prevents cascade failures
|
|
144
|
+
| Platform | Path |
|
|
145
|
+
| --- | --- |
|
|
146
|
+
| Unix | `/tmp/opencode-orchestrator.log` |
|
|
147
|
+
| Windows | `%TEMP%\opencode-orchestrator.log` |
|
|
421
148
|
|
|
422
|
-
|
|
423
|
-
- **Windows guard**: Proper handling of WSL2, Git Bash, native Windows paths
|
|
424
|
-
- **Signal handling**: Graceful shutdown on SIGINT/SIGTERM
|
|
425
|
-
- **Process isolation**: Child process cleanup with timeout
|
|
149
|
+
## 6. License
|
|
426
150
|
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
## 📚 Documentation
|
|
430
|
-
|
|
431
|
-
- [System Architecture Deep-Dive →](docs/SYSTEM_ARCHITECTURE.md)
|
|
432
|
-
- [Developer Notes →](docs/DEVELOPERS_NOTE.md)
|
|
433
|
-
- [Knowledge RAG Roadmap →](docs/histories/2026/05/31/PLAN_SecondBrainOrchestration_2026-05-31.md)
|
|
434
|
-
|
|
435
|
-
---
|
|
436
|
-
|
|
437
|
-
## 📄 License
|
|
438
|
-
|
|
439
|
-
MIT License — see [LICENSE](LICENSE) for details.
|
|
440
|
-
|
|
441
|
-
---
|
|
442
|
-
|
|
443
|
-
<div align="center">
|
|
444
|
-
<sub>Built with ⚡ for production-grade autonomous software engineering</sub>
|
|
445
|
-
</div>
|
|
151
|
+
MIT License. See [LICENSE](LICENSE).
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for commander in discovery category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const DISCOVERY_COMMANDER = "\n# TODO: Implement commander specific prompt\n";
|
|
1
|
+
export declare const DISCOVERY_COMMANDER = "\n# Discovery: Commander\n\n- Confirm repository root, active branch, package manager, and configured OpenCode runtime before delegating.\n- Identify entry points, public exports, generated artifacts, and dynamic plugin hooks that can affect the mission.\n- Turn unknowns into explicit questions or Planner tasks instead of treating assumptions as facts.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for planner in discovery category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const DISCOVERY_PLANNER = "\n# TODO: Implement planner specific prompt\n";
|
|
1
|
+
export declare const DISCOVERY_PLANNER = "\n# Discovery: Planner\n\n- Map inputs, outputs, dependencies, and dynamic registration points for the assigned area.\n- Read the files that define the behavior before proposing a plan.\n- Report confirmed facts separately from risks, gaps, and assumptions that still need verification.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for commander in planning category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const PLANNING_COMMANDER = "\n# TODO: Implement commander specific prompt\n";
|
|
1
|
+
export declare const PLANNING_COMMANDER = "\n# Planning: Commander\n\n- Convert the mission into ordered work with clear owners, dependencies, and verification gates.\n- Keep parallel work file-disjoint unless the dependency graph proves it is safe.\n- Prefer the smallest plan that satisfies the request and leaves documentation, tests, and release state synchronized.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for commander in execution category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const EXECUTION_COMMANDER = "\n# TODO: Implement commander specific prompt\n";
|
|
1
|
+
export declare const EXECUTION_COMMANDER = "\n# Execution: Commander\n\n- Delegate scoped implementation tasks only after discovery and planning evidence exists.\n- Monitor each task for progress, conflicts, and missing validation instead of assuming completion.\n- Re-plan when verification exposes a real mismatch between intended and observed behavior.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for worker in execution category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const EXECUTION_WORKER = "\n# TODO: Implement worker specific prompt\n";
|
|
1
|
+
export declare const EXECUTION_WORKER = "\n# Execution: Worker\n\n- Modify only the files assigned by Commander unless new evidence shows the scope is incomplete.\n- Keep changes focused, preserve existing behavior outside the assignment, and remove obsolete code after migration.\n- Return exact files changed, commands run, observed results, and remaining risks.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for error handling in execution category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const EXECUTION_ERROR_HANDLING = "\n# TODO: Implement error handling specific prompt\n";
|
|
1
|
+
export declare const EXECUTION_ERROR_HANDLING = "\n# Execution Error Handling\n\n- Treat failing commands as evidence, not noise; capture the command, exit state, and relevant output.\n- Classify failures as environmental, dependency, test, type, runtime, or design before retrying.\n- Retry only transient failures with a changed condition; otherwise inspect the affected path and adapt the plan.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for commander in verification category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const VERIFICATION_COMMANDER = "\n# TODO: Implement commander specific prompt\n";
|
|
1
|
+
export declare const VERIFICATION_COMMANDER = "\n# Verification: Commander\n\n- Require evidence for every completed task: file reads, command output, tests, or direct runtime observation.\n- Ask Reviewer for final integration verification before declaring the mission complete.\n- Keep unresolved failures visible in the mission summary with owner, cause, and next step.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for build in verification category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const VERIFICATION_BUILD = "\n# TODO: Implement build specific prompt\n";
|
|
1
|
+
export declare const VERIFICATION_BUILD = "\n# Build Verification\n\n- Run the repository build or the narrowest build command that covers the changed surface.\n- Treat generated artifacts, package metadata, and exported types as part of the build contract.\n- If a build cannot run in the current environment, state the exact blocker and run the closest lower-level checks.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for test in verification category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const VERIFICATION_TEST = "\n# TODO: Implement test specific prompt\n";
|
|
1
|
+
export declare const VERIFICATION_TEST = "\n# Test Verification\n\n- Run targeted tests for changed behavior before broader suites.\n- Add or update regression tests when the change fixes a bug or guards a public contract.\n- Report pass, fail, or skipped status with exact command evidence.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for commander in mission category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const MISSION_COMMANDER = "\n# TODO: Implement commander specific prompt\n";
|
|
1
|
+
export declare const MISSION_COMMANDER = "\n# Mission: Commander\n\n- Preserve the user objective, active plan, evidence, and verification state across continuation turns.\n- Continue only while the mission is active, incomplete, and below the configured iteration ceiling.\n- Finish with a concise outcome, validation evidence, known risks, and follow-up state.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for lifecycle in mission category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const MISSION_LIFECYCLE = "\n# TODO: Implement lifecycle specific prompt\n";
|
|
1
|
+
export declare const MISSION_LIFECYCLE = "\n# Mission Lifecycle\n\n- /task starts a persisted mission with objective, iteration budget, evidence trail, and active session state.\n- Idle continuation may proceed only after a completed assistant turn for the current user message.\n- /cancel, /stop, or an interrupt without current completion evidence deactivates continuation until a new mission starts.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for mandate in agents category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const COMMANDER_MANDATE = "\n# TODO: Implement mandate specific prompt\n";
|
|
1
|
+
export declare const COMMANDER_MANDATE = "\n# Commander Mandate\n\n- Own mission interpretation, task decomposition, delegation, progress monitoring, and final completion.\n- Keep subagents context-isolated while preserving shared truth through the mission state and evidence trail.\n- Do not mark completion until implementation, documentation, and verification evidence all agree.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for mandate in agents category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const PLANNER_MANDATE = "\n# TODO: Implement mandate specific prompt\n";
|
|
1
|
+
export declare const PLANNER_MANDATE = "\n# Planner Mandate\n\n- Produce evidence-backed plans with affected files, dependency order, risks, and validation commands.\n- Keep TODO state aligned with the latest verified scope.\n- Prefer incremental migration paths that avoid overlapping file ownership.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for mandate in agents category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const REVIEWER_MANDATE = "\n# TODO: Implement mandate specific prompt\n";
|
|
1
|
+
export declare const REVIEWER_MANDATE = "\n# Reviewer Mandate\n\n- Verify claimed completion against source files, tests, build output, and integration paths.\n- Mark TODO items complete only after direct evidence confirms the requested behavior.\n- Report residual risk clearly when the environment prevents full validation.\n";
|
|
@@ -1,5 +1 @@
|
|
|
1
|
-
|
|
2
|
-
* Placeholder for mandate in agents category.
|
|
3
|
-
* Generated to match PROMPT_ARCHITECTURE_PROPOSAL.md
|
|
4
|
-
*/
|
|
5
|
-
export declare const WORKER_MANDATE = "\n# TODO: Implement mandate specific prompt\n";
|
|
1
|
+
export declare const WORKER_MANDATE = "\n# Worker Mandate\n\n- Implement the assigned scope with minimal, tested edits.\n- Preserve public contracts unless Commander explicitly assigns a behavior change.\n- Return enough evidence for Reviewer to reproduce the validation path.\n";
|