opencode-orchestrator 0.5.12 → 0.5.17

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.
Files changed (85) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +437 -92
  3. package/dist/agents/subagents/librarian.d.ts +10 -0
  4. package/dist/agents/subagents/researcher.d.ts +11 -0
  5. package/dist/core/agents/concurrency.d.ts +2 -6
  6. package/dist/core/agents/config.d.ts +1 -1
  7. package/dist/core/agents/consts/index.d.ts +4 -0
  8. package/dist/core/agents/consts/task-status.const.d.ts +12 -0
  9. package/dist/core/agents/interfaces/concurrency-config.interface.d.ts +9 -0
  10. package/dist/core/agents/interfaces/index.d.ts +6 -3
  11. package/dist/core/agents/interfaces/{parallel-task.d.ts → parallel-task.interface.d.ts} +4 -8
  12. package/dist/core/agents/interfaces/resume-input.interface.d.ts +17 -0
  13. package/dist/core/agents/interfaces/task-progress.interface.d.ts +9 -0
  14. package/dist/core/agents/manager/event-handler.d.ts +34 -0
  15. package/dist/core/agents/manager/index.d.ts +10 -0
  16. package/dist/core/agents/manager/task-cleaner.d.ts +17 -0
  17. package/dist/core/agents/manager/task-launcher.d.ts +20 -0
  18. package/dist/core/agents/manager/task-poller.d.ts +26 -0
  19. package/dist/core/agents/manager/task-resumer.d.ts +18 -0
  20. package/dist/core/agents/manager.d.ts +11 -29
  21. package/dist/core/agents/task-store.d.ts +29 -3
  22. package/dist/core/agents/types/index.d.ts +1 -1
  23. package/dist/core/agents/types/parallel-task-status.type.d.ts +4 -0
  24. package/dist/core/bus/event-bus.d.ts +53 -0
  25. package/dist/core/bus/index.d.ts +19 -0
  26. package/dist/core/bus/interfaces.d.ts +34 -0
  27. package/dist/core/bus/types.d.ts +12 -0
  28. package/dist/core/cache/constants.d.ts +6 -0
  29. package/dist/core/cache/document-cache.d.ts +6 -0
  30. package/dist/core/cache/index.d.ts +4 -0
  31. package/dist/core/cache/interfaces.d.ts +53 -0
  32. package/dist/core/cache/operations.d.ts +36 -0
  33. package/dist/core/cache/utils.d.ts +20 -0
  34. package/dist/core/loop/formatters.d.ts +16 -0
  35. package/dist/core/loop/interfaces.d.ts +34 -0
  36. package/dist/core/loop/parser.d.ts +8 -0
  37. package/dist/core/loop/stats.d.ts +24 -0
  38. package/dist/core/loop/todo-enforcer.d.ts +9 -0
  39. package/dist/core/notification/event-integration.d.ts +7 -0
  40. package/dist/core/notification/presets.d.ts +14 -0
  41. package/dist/core/notification/toast-core.d.ts +28 -0
  42. package/dist/core/notification/toast.d.ts +9 -0
  43. package/dist/core/notification/types.d.ts +19 -0
  44. package/dist/core/orchestrator/types/task-status.d.ts +2 -2
  45. package/dist/core/progress/calculator.d.ts +11 -0
  46. package/dist/core/progress/formatters.d.ts +20 -0
  47. package/dist/core/progress/interfaces.d.ts +54 -0
  48. package/dist/core/progress/store.d.ts +28 -0
  49. package/dist/core/progress/tracker.d.ts +11 -0
  50. package/dist/core/queue/async-queue.d.ts +46 -0
  51. package/dist/core/queue/async-utils.d.ts +20 -0
  52. package/dist/core/queue/index.d.ts +8 -0
  53. package/dist/core/queue/work-pool.d.ts +19 -0
  54. package/dist/core/recovery/auto-recovery.d.ts +9 -0
  55. package/dist/core/recovery/constants.d.ts +6 -0
  56. package/dist/core/recovery/handler.d.ts +27 -0
  57. package/dist/core/recovery/interfaces.d.ts +63 -0
  58. package/dist/core/recovery/patterns.d.ts +8 -0
  59. package/dist/core/session/interfaces.d.ts +53 -0
  60. package/dist/core/session/shared-context.d.ts +8 -0
  61. package/dist/core/session/store.d.ts +44 -0
  62. package/dist/core/session/summary.d.ts +7 -0
  63. package/dist/core/task/interfaces.d.ts +54 -0
  64. package/dist/core/task/parser.d.ts +8 -0
  65. package/dist/core/task/scheduler.d.ts +12 -0
  66. package/dist/core/task/store.d.ts +32 -0
  67. package/dist/core/task/summary.d.ts +7 -0
  68. package/dist/core/task/task-decomposer.d.ts +10 -0
  69. package/dist/index.d.ts +56 -2
  70. package/dist/index.js +2605 -690
  71. package/dist/scripts/postinstall.js +0 -0
  72. package/dist/scripts/preuninstall.js +0 -0
  73. package/dist/shared/agent.d.ts +2 -0
  74. package/dist/shared/constants.d.ts +56 -3
  75. package/dist/shared/event-types.d.ts +77 -0
  76. package/dist/tools/background-cmd/list.d.ts +2 -2
  77. package/dist/tools/parallel/delegate-task.d.ts +3 -0
  78. package/dist/tools/web/cache-docs.d.ts +21 -0
  79. package/dist/tools/web/codesearch.d.ts +19 -0
  80. package/dist/tools/web/index.d.ts +9 -0
  81. package/dist/tools/web/webfetch.d.ts +19 -0
  82. package/dist/tools/web/websearch.d.ts +17 -0
  83. package/package.json +74 -73
  84. package/dist/core/agents/types/parallel-task-status.d.ts +0 -4
  85. /package/dist/core/agents/interfaces/{launch-input.d.ts → launch-input.interface.d.ts} +0 -0
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 agnusdei1207
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 agnusdei1207
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,92 +1,437 @@
1
- <div align="center">
2
- <img src="assets/logo.png" alt="Logo" width="200" />
3
- </div>
4
-
5
- # OpenCode Orchestrator 🎯
6
-
7
- > **Autonomous Multi-Agent Plugin for [OpenCode](https://opencode.ai)**
8
-
9
- [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
10
- [![npm](https://img.shields.io/npm/v/opencode-orchestrator.svg)](https://www.npmjs.com/package/opencode-orchestrator)
11
-
12
- ---
13
-
14
- ## Why?
15
-
16
- Tested GLM-4, got disappointed. Built this to make mid-tier models work like premium ones through structured orchestration.
17
-
18
- ### Key Features
19
- - **🎯 Autonomous Loop** — Commander runs until the mission is complete
20
- - **🔍 Environment Scan** — Analyzes Infra, Stack, and Domain before coding
21
- - **🔨 Smart Implementation** — Matches existing codebase patterns
22
- - **🛡️ Rigorous Audit** — Proves success with builds/tests/logs
23
- - **💾 Persistent Context** — Saves session state to disk
24
- - **🏗️ Parallel Agents** — Run multiple agents concurrently
25
- - **⏳ Background Tasks** — Non-blocking command execution
26
-
27
- ---
28
-
29
- ## Installation
30
-
31
- ```bash
32
- npm install -g opencode-orchestrator
33
- ```
34
-
35
- Restart OpenCode after installation.
36
-
37
- ---
38
-
39
- ## Usage
40
-
41
- ### 🚀 Select Commander via Tab Key (Recommended)
42
-
43
- Press `Tab` in OpenCode → Select **Commander** → Type your mission!
44
-
45
- ```
46
- "Fix the login bug in the docker-compose environment"
47
- ```
48
-
49
- ### 📋 Use /task Command
50
-
51
- ```bash
52
- /task "Implement user authentication with JWT"
53
- ```
54
-
55
- > **💡 Tip:** `/task` makes Commander run **2x longer** for complex tasks.
56
-
57
- ---
58
-
59
- ## The 5 Agents
60
-
61
- | Agent | Role | Responsibility |
62
- | :--- | :--- | :--- |
63
- | **Commander** 🎯 | Orchestrator | Autonomous mission control |
64
- | **Architect** 🏗️ | Planner | Task decomposition |
65
- | **Builder** 🔨 | Developer | Full-stack implementation |
66
- | **Inspector** 🔍 | Quality | Audit & auto-fix |
67
- | **Recorder** 💾 | Context | Progress tracking |
68
-
69
- ---
70
-
71
- ## Uninstall
72
-
73
- ```bash
74
- npm uninstall -g opencode-orchestrator
75
- ```
76
-
77
- ---
78
-
79
- ## Documentation
80
-
81
- - [Architecture & Design](docs/ARCHITECTURE.md)
82
- - [Troubleshooting](docs/PLUGIN_TROUBLESHOOTING.md)
83
-
84
- ---
85
-
86
- ## License
87
-
88
- MIT License. [LICENSE](LICENSE)
89
-
90
- ---
91
-
92
- **Reliability over slop. Environment over assumptions.**
1
+ <div align="center">
2
+ <img src="assets/logo.png" alt="Logo" width="200" />
3
+ </div>
4
+
5
+ # OpenCode Orchestrator 🎯
6
+
7
+ > **Enterprise-Grade Autonomous Multi-Agent Plugin for [OpenCode](https://opencode.ai)**
8
+
9
+ [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
10
+ [![npm](https://img.shields.io/npm/v/opencode-orchestrator.svg)](https://www.npmjs.com/package/opencode-orchestrator)
11
+ [![Tests](https://img.shields.io/badge/tests-211%20passed-brightgreen.svg)]()
12
+
13
+ ---
14
+
15
+ ## 🚀 What's New in v0.6.0
16
+
17
+ **Ultimate Agent Architecture** - Production-ready distributed agent orchestration!
18
+
19
+ | Feature | Description |
20
+ |---------|-------------|
21
+ | **♾️ Unlimited Mode** | No step limits - runs until mission complete |
22
+ | **🧠 Anti-Hallucination** | Research before coding, verify with docs |
23
+ | **⚡ 50x Parallel Sessions** | Massive concurrent task execution |
24
+ | **📊 Auto Memory Management** | GC, archiving, zero memory leaks |
25
+ | **🔄 Auto Recovery** | Handles rate limits, errors automatically |
26
+ | **📡 Event-Driven** | Real-time pub/sub across all components |
27
+
28
+ ---
29
+
30
+ ## 🏛️ System Architecture
31
+
32
+ ```
33
+ ┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
34
+ │ │
35
+ │ USER REQUEST │
36
+ │ (OpenCode Terminal / UI) │
37
+ │ │ │
38
+ └──────────────────────────────────────────────┼────────────────────────────────────────────────────────┘
39
+ │
40
+ ▼
41
+ ┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
42
+ │ │
43
+ │ ORCHESTRATOR PLUGIN (src/index.ts) │
44
+ │ │
45
+ │ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐ │
46
+ │ │ Session State │ │ Agent Definitions │ │ Tools Registry │ │ Toast.enable │ │
47
+ │ │ Map<sessionId, │ │ (7 agents) │ │ (15+ tools) │ │ AutoToasts() │ │
48
+ │ │ {step, maxSteps, │ │ │ │ │ │ → EventBus sub │ │
49
+ │ │ timestamp}> │ │ • Commander 🎯 │ │ • call_agent │ │ │ │
50
+ │ │ │ │ • Architect 🏗️ │ │ • launch_parallel │ └─────────────────────┘ │
51
+ │ │ Cleanup: │ │ • Builder 🔨 │ │ • check_parallel │ │
52
+ │ │ session.deleted │ │ • Inspector 🔍 │ │ • webfetch │ ┌─────────────────────┐ │
53
+ │ │ → sessions.delete │ │ • Recorder 💾 │ │ • websearch │ │ ProgressTracker │ │
54
+ │ │ → Progress.clear │ │ • Librarian 📚 │ │ • grep_search │ │ .startSession() │ │
55
+ │ └─────────────────────┘ │ • Researcher 🔬 │ │ • run_background │ │ .recordSnapshot() │ │
56
+ │ └─────────────────────┘ └─────────────────────┘ │ .clearSession() │ │
57
+ │ └─────────────────────┘ │
58
+ │ │ │
59
+ │ ▼ │
60
+ │ ┌─────────────────────────────────────────────────────────────────────────────────────────────────┐ │
61
+ │ │ │ │
62
+ │ │ PARENT SESSION (Main Execution Loop) │ │
63
+ │ │ │ │
64
+ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │
65
+ │ │ │ Commander │───▶│ Architect │───▶│ Builder │───▶│ Inspector │───▶│ Recorder │ │ │
66
+ │ │ │ 🎯 │ │ 🏗️ │ │ 🔨 │ │ 🔍 │ │ 💾 │ │ │
67
+ │ │ │ │ │ │ │ │ │ │ │ │ │ │
68
+ │ │ │ Orchestrate │ │ Decompose │ │ Implement │ │ Audit & │ │ Save │ │ │
69
+ │ │ │ & delegate │ │ into tasks │ │ code │ │ verify │ │ context │ │ │
70
+ │ │ └─────────────┘ └─────────────┘ └──────┬──────┘ └─────────────┘ └─────────────┘ │ │
71
+ │ │ │ │ │
72
+ │ │ │ launch_parallel_agent() │ │
73
+ │ │ ▼ │ │
74
+ │ │ ┌──────────────────────────────────────────────────────────────────────────────────────────┐ │ │
75
+ │ │ │ │ │ │
76
+ │ │ │ hooks: "chat.message" / "tool.execute.after" / "handler" │ │ │
77
+ │ │ │ │ │ │
78
+ │ │ │ chat.message: │ │ │
79
+ │ │ │ • Parse /task, /plan slash commands │ │ │
80
+ │ │ │ • Auto-start session on Commander agent selection │ │ │
81
+ │ │ │ • emit(TASK_EVENTS.STARTED, { taskId, agent }) │ │ │
82
+ │ │ │ │ │ │
83
+ │ │ │ tool.execute.after: │ │ │
84
+ │ │ │ • Check "MISSION COMPLETE" → emit(MISSION_EVENTS.COMPLETE) │ │ │
85
+ │ │ │ • Check "/stop" or "/cancel" → emit(TASK_EVENTS.FAILED) │ │ │
86
+ │ │ │ • Record ProgressTracker.recordSnapshot() │ │ │
87
+ │ │ │ • Inject CONTINUE_INSTRUCTION → client.session.prompt() │ │ │
88
+ │ │ │ │ │ │
89
+ │ │ │ handler (event): │ │ │
90
+ │ │ │ • session.deleted → cleanup sessions, state, ProgressTracker │ │ │
91
+ │ │ │ • Pass to ParallelAgentManager.handleEvent() │ │ │
92
+ │ │ │ │ │ │
93
+ │ │ └──────────────────────────────────────────────────────────────────────────────────────────┘ │ │
94
+ │ │ │ │
95
+ │ └─────────────────────────────────────────────────────────────────────────────────────────────────┘ │
96
+ │ │
97
+ └────────────────────────────────────────────────────┬───────────────────────────────────────────────────┘
98
+ │
99
+ ▼
100
+ ┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
101
+ │ │
102
+ │ PARALLEL AGENT MANAGER (src/core/agents/manager.ts) │
103
+ │ │
104
+ │ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
105
+ │ │ Component Composition │ │
106
+ │ │ │ │
107
+ │ │ ┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐ │ │
108
+ │ │ │ TaskLauncher │ │ TaskResumer │ │ TaskPoller │ │ │
109
+ │ │ │ (task-launcher.ts) │ │ (task-resumer.ts) │ │ (task-poller.ts) │ │ │
110
+ │ │ │ ───────────────── │ │ ───────────────── │ │ ───────────────── │ │ │
111
+ │ │ │ │ │ │ │ │ │ │
112
+ │ │ │ async launch(): │ │ async resume(): │ │ poll() every 1s: │ │ │
113
+ │ │ │ 1. await acquire() │ │ 1. Find task │ │ 1. Get running │ │ │
114
+ │ │ │ 2. session.create()│ │ 2. session.message │ │ 2. Check events │ │ │
115
+ │ │ │ 3. store.set() │ │ 3. Notify parent │ │ 3. If idle+stable │ │ │
116
+ │ │ │ 4. emit(STARTED) │ │ │ │ → completed │ │ │
117
+ │ │ │ 5. session.message │ └───────────────────────┘ │ 4. emit(COMPLETED) │ │ │
118
+ │ │ │ 6. Start poller │ │ 5. scheduleCleanup │ │ │
119
+ │ │ │ │ │ │ │ │
120
+ │ │ └───────────┬───────────┘ └───────────┬───────────┘ │ │
121
+ │ │ │ │ │ │
122
+ │ │ ▼ ▼ │ │
123
+ │ │ ┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐ │ │
124
+ │ │ │ TaskCleaner │ │ EventHandler │ │ ConcurrencyController │ │ │
125
+ │ │ │ (task-cleaner.ts) │ │ (event-handler.ts) │ │ (concurrency.ts) │ │ │
126
+ │ │ │ ───────────────── │ │ ───────────────── │ │ ───────────────── │ │ │
127
+ │ │ │ │ │ │ │ │ │ │
128
+ │ │ │ pruneExpiredTasks(): │ │ handle(event): │ │ acquire(key): │ │ │
129
+ │ │ │ • TTL > 60min │ │ │ │ • limit = 10 │ │ │
130
+ │ │ │ → status=timeout │ │ session.idle: │ │ • if < limit │ │ │
131
+ │ │ │ → release() │ │ • MIN_STABILITY │ │ → immediate │ │ │
132
+ │ │ │ → session.delete() │ │ • validateOutput │ │ • else queue.push │ │ │
133
+ │ │ │ │ │ → completed │ │ │ │ │
134
+ │ │ │ scheduleCleanup(): │ │ → release() │ │ release(key): │ │ │
135
+ │ │ │ • setTimeout 10min │ │ → scheduleClean │ │ • if queue.length │ │ │
136
+ │ │ │ → session.delete() │ │ │ │ → queue.shift() │ │ │
137
+ │ │ │ → store.delete() │ │ session.deleted: │ │ → next() │ │ │
138
+ │ │ │ │ │ → release() │ │ • else count-- │ │ │
139
+ │ │ │ notifyParent(): │ │ → store.delete() │ │ │ │ │
140
+ │ │ │ → session.prompt() │ │ │ │ getLimit(key): │ │ │
141
+ │ │ │ │ └───────────────────────┘ │ • MAX_TOTAL = 50 │ │ │
142
+ │ │ └───────────────────────┘ │ • PER_AGENT = 10 │ │ │
143
+ │ │ └───────────────────────┘ │ │
144
+ │ └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
145
+ │ │ │
146
+ │ ▼ │
147
+ │ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
148
+ │ │ │ │
149
+ │ │ TaskStore (task-store.ts) │ │
150
+ │ │ │ │
151
+ │ │ ┌─────────────────────────┐ ┌─────────────────────────┐ ┌─────────────────────────┐ │ │
152
+ │ │ │ tasks: Map<id, Task> │ │ pendingByParent: Map │ │ notifications: Map │ │ │
153
+ │ │ │ MAX: 1000 │ │ <parentId, Set<taskId>> │ │ <parentId, Task[]> │ │ │
154
+ │ │ │ │ │ │ │ MAX: 100/parent │ │ │
155
+ │ │ │ set() → auto gc() │ │ trackPending() │ │ │ │ │
156
+ │ │ │ getRunning() │ │ untrackPending() │ │ queueNotification() │ │ │
157
+ │ │ │ getByParent() │ │ hasPending() │ │ → FIFO eviction │ │ │
158
+ │ │ └─────────────────────────┘ └─────────────────────────┘ └─────────────────────────┘ │ │
159
+ │ │ │ │
160
+ │ │ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │ │
161
+ │ │ │ │ │ │
162
+ │ │ │ async gc(): │ │ │
163
+ │ │ │ • completed > 30min → archiveTasks() → .cache/task-archive/tasks_YYYY-MM-DD.jsonl │ │ │
164
+ │ │ │ • error/cancelled > 10min → delete │ │ │
165
+ │ │ │ │ │ │
166
+ │ │ └─────────────────────────────────────────────────────────────────────────────────────────┘ │ │
167
+ │ │ │ │
168
+ │ └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
169
+ │ │ │
170
+ │ ▼ │
171
+ │ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
172
+ │ │ │ │
173
+ │ │ CHILD SESSIONS POOL (up to 50 concurrent) │ │
174
+ │ │ │ │
175
+ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
176
+ │ │ │Session 1 │ │Session 2 │ │Session 3 │ │Session 4 │ │Session 5 │ │Session 6 │ │ ... 50 │ │ │
177
+ │ │ │ Builder │ │Librarian │ │Researcher│ │Inspector │ │ Builder │ │ Builder │ │ │ │ │
178
+ │ │ │ 🔨 │ │ 📚 │ │ 🔬 │ │ 🔍 │ │ 🔨 │ │ 🔨 │ │ │ │ │
179
+ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │ │
180
+ │ │ │ running │ │ running │ │completed │ │ running │ │ error │ │ pending │ │ │ │ │
181
+ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────────┘ │ │
182
+ │ │ │ │ │ │ │ │ │ │
183
+ │ │ └────────────┴────────────┴────────────┴────────────┴────────────┘ │ │
184
+ │ │ │ │ │
185
+ │ └─────────────────────────────────────────┼───────────────────────────────────────────────────────┘ │
186
+ │ │ │
187
+ └─────────────────────────────────────────────┼──────────────────────────────────────────────────────────┘
188
+ │
189
+ ▼
190
+ ┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
191
+ │ │
192
+ │ EVENT BUS (src/core/bus/) │
193
+ │ │
194
+ │ ┌────────────────────────────────────────────────────────────────────────────────────────────────┐ │
195
+ │ │ │ │
196
+ │ │ Event Types (Pub/Sub) │ │
197
+ │ │ │ │
198
+ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
199
+ │ │ │task.started │ │task.completed│ │ task.failed │ │session.idle │ │ mission.complete │ │ │
200
+ │ │ │ │ │ │ │ │ │session.delete│ │ mission.all_complete│ │ │
201
+ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │ │
202
+ │ │ │ │ │ │ │ │ │
203
+ │ │ └────────────────┴────────────────┴────────────────┴────────────────────┘ │ │
204
+ │ │ │ │ │
205
+ │ │ ▼ │ │
206
+ │ │ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │ │
207
+ │ │ │ Subscribers │ │ │
208
+ │ │ │ │ │ │
209
+ │ │ │ Toast.enableAutoToasts(): EventHandler.handle(): │ │ │
210
+ │ │ │ • task.started → presets.taskStarted() • release concurrency │ │ │
211
+ │ │ │ • task.completed → presets.taskCompleted() • cleanup resources │ │ │
212
+ │ │ │ • task.failed → presets.taskFailed() │ │ │
213
+ │ │ │ • mission.complete → presets.missionComplete() │ │ │
214
+ │ │ │ • document.cached → presets.documentCached() │ │ │
215
+ │ │ │ │ │ │
216
+ │ │ │ Returns: () => void (unsubscribe function for cleanup) │ │ │
217
+ │ │ │ │ │ │
218
+ │ │ └─────────────────────────────────────────────────────────────────────────────────────────┘ │ │
219
+ │ │ │ │
220
+ │ │ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │ │
221
+ │ │ │ EventBusImpl: │ │ │
222
+ │ │ │ • subscribe(type, handler) → unsubscribe fn │ │ │
223
+ │ │ │ • publish(type, properties) → Event │ │ │
224
+ │ │ │ • emit(type, properties) → void │ │ │
225
+ │ │ │ • once(type, handler) → unsubscribe fn │ │ │
226
+ │ │ │ • waitFor(type, timeout) → Promise<Event> │ │ │
227
+ │ │ │ • history: Event[] (max 100, FIFO) │ │ │
228
+ │ │ └─────────────────────────────────────────────────────────────────────────────────────────┘ │ │
229
+ │ │ │ │
230
+ │ └────────────────────────────────────────────────────────────────────────────────────────────────┘ │
231
+ │ │
232
+ └────────────────────────────────────────────────────┬───────────────────────────────────────────────────┘
233
+ │
234
+ ▼
235
+ ┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
236
+ │ │
237
+ │ CORE SYSTEMS LAYER │
238
+ │ │
239
+ │ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐ │
240
+ │ │ Progress Tracker │ │ Auto Recovery │ │ Document Cache │ │
241
+ │ │ (src/core/progress/) │ │ (src/core/recovery/) │ │ (src/core/cache/) │ │
242
+ │ │ ────────────────── │ │ ────────────────── │ │ ────────────────── │ │
243
+ │ │ │ │ │ │ │ │
244
+ │ │ startSession(id) │ │ handleError(context) │ │ get(filename) │ │
245
+ │ │ recordSnapshot(id, { │ │ → match patterns │ │ set(filename, content) │ │
246
+ │ │ currentStep, │ │ → return action │ │ list() │ │
247
+ │ │ maxSteps │ │ │ │ clear(filename) │ │
248
+ │ │ }) │ │ Patterns: │ │ cleanExpired() │ │
249
+ │ │ formatCompact(id) │ │ • rate_limit │ │ │ │
250
+ │ │ clearSession(id) │ │ → retry+backoff │ │ Storage: │ │
251
+ │ │ │ │ • context_overflow │ │ .cache/docs/*.md │ │
252
+ │ │ Store: │ │ → compact │ │ │ │
253
+ │ │ sessions: Map<id, │ │ • network │ │ │ │
254
+ │ │ ProgressSnapshot[]> │ │ → retry 3x │ │ │ │
255
+ │ │ max 100/session │ │ • parse_error │ │ │ │
256
+ │ │ │ │ → skip │ │ │ │
257
+ │ └──────────────────────────┘ └──────────────────────────┘ └──────────────────────────┘ │
258
+ │ │
259
+ │ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐ │
260
+ │ │ Toast Notifier │ │ Async Queue │ │ Background Commands │ │
261
+ │ │ (src/core/notification)│ │ (src/core/queue/) │ │ (src/core/commands/) │ │
262
+ │ │ ────────────────── │ │ ────────────────── │ │ ────────────────── │ │
263
+ │ │ │ │ │ │ │ │
264
+ │ │ show({ title, msg }) │ │ workPool(items, fn, │ │ runBackground(cmd) │ │
265
+ │ │ │ │ concurrency) │ │ checkBackground(id) │ │
266
+ │ │ presets: │ │ workPoolWithResults() │ │ listBackground() │ │
267
+ │ │ • taskStarted() │ │ processBatches() │ │ killBackground(id) │ │
268
+ │ │ • taskCompleted() │ │ │ │ │ │
269
+ │ │ • taskFailed() │ │ retryWithBackoff(fn, │ │ Storage: │ │
270
+ │ │ • missionComplete() │ │ maxRetries, delay) │ │ backgroundJobs: Map │ │
271
+ │ │ • documentCached() │ │ withTimeout(fn, ms) │ │ <id, BackgroundTask> │ │
272
+ │ │ │ │ debounceAsync(fn, ms) │ │ │ │
273
+ │ │ enableAutoToasts() │ │ │ │ │ │
274
+ │ │ → EventBus.subscribe() │ │ AsyncQueue<T>: │ │ │ │
275
+ │ │ → returns disable fn │ │ async iterator │ │ │ │
276
+ │ │ │ │ │ │ │ │
277
+ │ └──────────────────────────┘ └──────────────────────────┘ └──────────────────────────┘ │
278
+ │ │
279
+ │ ┌──────────────────────────┐ ┌──────────────────────────┐ ┌──────────────────────────┐ │
280
+ │ │ Shared Context │ │ Task Decomposer │ │ Todo Enforcer │ │
281
+ │ │ (src/core/session/) │ │ (src/core/task/) │ │ (src/core/loop/) │ │
282
+ │ │ ────────────────── │ │ ────────────────── │ │ ────────────────── │ │
283
+ │ │ │ │ │ │ │ │
284
+ │ │ create(id, parentId) │ │ create(id, objective) │ │ parseTodos(data) │ │
285
+ │ │ get(id) │ │ addTask(id, { │ │ getIncompleteCount() │ │
286
+ │ │ getMerged(id) │ │ description, │ │ hasRemainingWork() │ │
287
+ │ │ → includes parent ctx │ │ level: 1|2|3, │ │ getNextPending() │ │
288
+ │ │ │ │ parallelGroup?, │ │ getStats() │ │
289
+ │ │ addDocument(id, doc) │ │ dependsOn? │ │ formatProgress() │ │
290
+ │ │ addFinding(id, find) │ │ }) │ │ isMissionComplete() │ │
291
+ │ │ addDecision(id, dec) │ │ updateStatus(id, task) │ │ │ │
292
+ │ │ │ │ getNextTasks(id) │ │ generateContinuation │ │
293
+ │ │ delete(id) │ │ getParallelBatch(id) │ │ Prompt() │ │
294
+ │ │ getStats(id) │ │ getSummary(id) │ │ generateCompletion │ │
295
+ │ │ │ │ │ │ Message() │ │
296
+ │ └──────────────────────────┘ └──────────────────────────┘ └──────────────────────────┘ │
297
+ │ │
298
+ └───────────────────────────────────────────────────────────────────────────────────────────────────────┘
299
+ ```
300
+
301
+ ---
302
+
303
+ ## 🎯 Key Differentiators
304
+
305
+ | Capability | OpenCode Orchestrator | Basic Plugins |
306
+ |------------|----------------------|---------------|
307
+ | **Parallel Sessions** | Up to 50 concurrent | Single session |
308
+ | **Memory Management** | Auto GC + disk archiving | Memory leaks |
309
+ | **Error Recovery** | Pattern-based auto retry | Crash |
310
+ | **Context Sharing** | Parent-child merge | Isolated |
311
+ | **Event System** | Real-time pub/sub | None |
312
+ | **Task Decomposition** | 3-level hierarchy | Flat |
313
+
314
+ ---
315
+
316
+ ## Installation
317
+
318
+ ```bash
319
+ npm install -g opencode-orchestrator
320
+ ```
321
+
322
+ Restart OpenCode after installation.
323
+
324
+ ---
325
+
326
+ ## Usage
327
+
328
+ ### 🚀 Select Commander via Tab Key (Recommended)
329
+
330
+ Press `Tab` in OpenCode → Select **Commander** → Type your mission!
331
+
332
+ <div align="center">
333
+ <img src="assets/tui_image.png" alt="Commander TUI" width="600" />
334
+ <p><sub><b>Commander</b> agent selection interface in OpenCode (TUI)</sub></p>
335
+
336
+ <br/> <img src="assets/window_image.png" alt="Commander Windows" width="600" />
337
+ <p><sub>Execution of <b>Commander</b> agent on Windows environment</sub></p>
338
+ </div>
339
+
340
+ ```
341
+ "Fix the login bug in the docker-compose environment"
342
+ ```
343
+
344
+ > **💡 Recommended:** For complex missions, select **Commander** directly via `Tab` to use the full orchestration system with parallel processing, anti-hallucination, and auto-recovery features.
345
+
346
+ ### 📋 Use /task Command (Simple Tasks)
347
+
348
+ For quick, simple tasks, you can use the `/task` command:
349
+
350
+ ```bash
351
+ /task "Add a loading spinner to the button"
352
+ ```
353
+
354
+ > **⚠️ Note:** `/task` uses a simplified prompt template. For complex multi-step missions, use **Commander** directly via `Tab` key.
355
+
356
+ ---
357
+
358
+ ## The 7 Agents
359
+
360
+ | Agent | Role | Responsibility |
361
+ | :--------------- | :----------- | :--------------------------------- |
362
+ | **Commander** 🎯 | Orchestrator | Autonomous mission control |
363
+ | **Architect** 🏗️ | Planner | Hierarchical task decomposition |
364
+ | **Builder** 🔨 | Developer | Full-stack implementation |
365
+ | **Inspector** 🔍 | Quality | Audit, auto-fix & doc verification |
366
+ | **Recorder** 💾 | Context | Progress tracking |
367
+ | **Librarian** 📚 | Research | Documentation & API research |
368
+ | **Researcher** 🔬 | Investigation | Pre-task research & analysis |
369
+
370
+ ---
371
+
372
+ ## 🛠️ Available Tools
373
+
374
+ | Tool | Description |
375
+ |------|-------------|
376
+ | `call_agent` | Call another agent synchronously |
377
+ | `launch_parallel_agent` | Start parallel async session |
378
+ | `check_parallel_task` | Check task status |
379
+ | `collect_parallel_results` | Gather completed results |
380
+ | `webfetch` | Fetch URL content as Markdown |
381
+ | `websearch` | Search web (SearXNG → Brave → DuckDuckGo) |
382
+ | `codesearch` | Search open source code patterns |
383
+ | `cache_docs` | Manage cached documentation |
384
+ | `run_background` | Run command in background |
385
+ | `grep_search` / `glob_search` | Fast file search |
386
+
387
+ ---
388
+
389
+ ## 📊 Resource Guarantees
390
+
391
+ | Resource | Limit | Safety Mechanism |
392
+ |----------|-------|------------------|
393
+ | Parallel Sessions | 50 | Queue overflow protection |
394
+ | Tasks in Memory | 1,000 | Auto GC + disk archive |
395
+ | Notifications | 100/parent | FIFO eviction |
396
+ | Event History | 100 | Ring buffer |
397
+ | Session TTL | 60 min | Auto cleanup |
398
+ | Poll Interval | 1 second | Fast completion detection |
399
+
400
+ ---
401
+
402
+ ## 🧪 Test Coverage
403
+
404
+ ```
405
+ Test Files: 18 passed
406
+ Tests: 211 passed
407
+ Duration: ~4.3s
408
+ ```
409
+
410
+ ---
411
+
412
+ ## Uninstall
413
+
414
+ ```bash
415
+ npm uninstall -g opencode-orchestrator
416
+ ```
417
+
418
+ ---
419
+
420
+ ## Documentation
421
+
422
+ - **[System Architecture](docs/SYSTEM_ARCHITECTURE.md)** — Detailed technical docs
423
+ - **[OpenCode SDK Reference](docs/OPENCODE_SDK_REFERENCE.md)** — API usage reference
424
+ - [Release Notes](docs/releases/) — Version history
425
+ - [Troubleshooting](docs/PLUGIN_TROUBLESHOOTING.md)
426
+
427
+ ---
428
+
429
+ ## License
430
+
431
+ MIT License. [LICENSE](LICENSE)
432
+
433
+ ---
434
+
435
+ <div align="center">
436
+ <b>Enterprise-scale. Memory-safe. Self-healing. Unlimited.</b>
437
+ </div>
package/dist/agents/subagents/librarian.d.ts ADDED
@@ -0,0 +1,10 @@
1
+ /**
2
+ * Librarian Agent - Documentation and API research specialist
3
+ *
4
+ * Purpose: Reduce hallucination by researching before implementing
5
+ * - Searches official documentation
6
+ * - Caches important findings locally
7
+ * - Provides verified information with citations
8
+ */
9
+ import { AgentDefinition } from "../../shared/agent.js";
10
+ export declare const librarian: AgentDefinition;
package/dist/agents/subagents/researcher.d.ts ADDED
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Researcher Agent - Pre-task investigation specialist
3
+ *
4
+ * Purpose: Gather all necessary information BEFORE implementation begins
5
+ * - Analyzes task requirements
6
+ * - Searches for official documentation
7
+ * - Finds existing patterns in codebase
8
+ * - Caches important references
9
+ */
10
+ import { AgentDefinition } from "../../shared/agent.js";
11
+ export declare const researcher: AgentDefinition;