opencode-orchestrator 0.9.6 → 0.9.8

package/README.md

@@ -4,7 +4,7 @@
 
 # OpenCode Orchestrator
 
-> Autonomous multi-agent plugin for [OpenCode](https://opencode.ai)
+> **🚀 Multi-Agent Orchestration Plugin for [OpenCode](https://opencode.ai)**
 
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![npm](https://img.shields.io/npm/v/opencode-orchestrator.svg)](https://www.npmjs.com/package/opencode-orchestrator)
@@ -12,112 +12,120 @@
 
 ---
 
+## 🔥 Why This Plugin?
+
+**Budget models have limits. Orchestration breaks them.**
+
+---
+
 ## ⚡ Quick Start
 
 ```bash
 npm install -g opencode-orchestrator
 ```
 
-Restart OpenCode after installation. Then:
+Then in OpenCode:
 
 ```bash
 /task "Build a REST API with authentication"
 ```
 
-That's it! The Commander takes over and works until the mission is complete.
+**Done.** You just deployed an army of AI agents. They plan, build, test, fix — and don't stop until it's sealed. ✨
 
 ---
 
-## 💡 Why I Built This
-
-Budget models have limits. Orchestration breaks them.
-
----
+## 🎯 What Makes This Different?
 
-## 🎯 What is This?
+### 🚀 Core Capabilities
 
-A multi-agent system that **autonomously executes complex tasks** from start to finish. Just describe your mission — the Commander handles everything else.
+| | Feature | What It Means |
+|:---:|:---|:---|
+| ⚡ | **Multi-Session Parallel** | 50 isolated sessions running simultaneously. True multi-threading. |
+| 🔥 | **Parallel Execution** | Workers build different files at once. 10x faster. |
+| � | **Non-Blocking Async** | Fire-and-forget. Commander never waits. Results collected automatically. |
+| 🧩 | **Smart Distribution** | One file = one worker. No conflicts. No stepping on each other. |
+| 🔗 | **Real-Time Sync** | Shared `.opencode/` state. All agents see updates instantly. |
+| 🛡️ | **Auto Verify & Test** | E2E tests, import checks, integration validation. Bugs get caught. |
+| 🩹 | **Self-Healing** | Auto-recovery from crashes, rate limits, context overflow. 3 retries. |
+| � | **Live Monitoring** | Track sessions, progress, queues. Toast notifications in real-time. |
 
 ---
 
-## ✨ v0.9.4 Highlights
 
-> 🚀 **"Relentless execution until absolute success."**
+## 🏛️ How It Works
 
-| Category | Feature |
-|----------|----------|
-| 🛡️ **Resilience** | Never stops. Auto-pivots Plan↔Search on any error |
-| ⚡ **Parallelism** | 50 isolated sessions run simultaneously |
-| 🔧 **TDD Workers** | Each agent works in complete isolation (1 file = 1 worker) |
-| 🔄 **Sync Integration** | Shared `.opencode/` state synchronizes all agents |
-| ✅ **Stability Checks** | TODO + Issue verification before mission seal |
-| 🧠 **Smart Fixers** | Anti-overengineering: simple errors get simple fixes |
+```
+                          YOU
+                           │
+                           │  /task "Build REST API"
+                           ▼
+    ╔══════════════════════════════════════════════════════════╗
+    ║                   🎯 COMMANDER                           ║
+    ║            "I orchestrate. I never sleep."               ║
+    ╚══════════════════════════════════════════════════════════╝
+                           │
+          ┌────────────────┼────────────────┐
+          │                │                │
+          ▼                ▼                ▼
+    ┌──────────┐    ┌──────────┐    ┌──────────┐
+    │📋 PLANNER│    │🔨 WORKER │    │🔨 WORKER │    x50 PARALLEL
+    │  Plan &  │    │ auth.ts  │    │  api.ts  │    SESSIONS
+    │ Research │    │  (TDD)   │    │  (TDD)   │
+    └──────────┘    └──────────┘    └──────────┘
+          │                │                │
+          └────────────────┼────────────────┘
+                           ▼
+    ╔══════════════════════════════════════════════════════════╗
+    ║                   ✅ REVIEWER                            ║
+    ║         E2E Tests • Sync Check • Validate                ║
+    ╚══════════════════════════════════════════════════════════╝
+                           │
+                    ┌──────┴──────┐
+                    │  Complete?  │
+                    └──────┬──────┘
+                     No ↙     ↘ Yes
+                   ♻️           🎖️
+                 LOOP         SEALED
+              (auto-fix)    (mission done)
+```
 
 ---
 
-## 🚀 How It Works
+## 🤖 The 4 Agents
 
-```
-                    /task "Build REST API"
-                              │
-                              ▼
-             ┌────────────────────────────────┐
-             │         🎯 COMMANDER           │
-             │  Read state → Delegate → Loop  │
-             └────────────────────────────────┘
-                              │
-      ┌───────────────────────┼───────────────────────┐
-      ▼                       ▼                       ▼
- ┌─────────┐            ┌─────────┐            ┌─────────┐
- │ PLANNER │            │ WORKER  │            │ WORKER  │    ⚡ PARALLEL
- │ Plan it │            │ Build A │            │ Build B │       EXECUTION
- └─────────┘            └─────────┘            └─────────┘
-      │                       │                       │
-      └───────────────────────┼───────────────────────┘
-                              ▼
-             ┌────────────────────────────────┐
-             │         ✅ REVIEWER            │
-             │       Verify → Sync            │
-             └────────────────────────────────┘
-                              │
-                   ┌──────────┴──────────┐
-                   │  TODO incomplete?   │
-                   │  Sync issues?       │
-                   └──────────┬──────────┘
-                        Yes ↓     ↓ No
-                    ♻️ LOOP    🎖️ SEALED
-```
+| Agent | Role | Superpower |
+|-------|------|------------|
+| **🎯 Commander** | Orchestrator | Sees everything, delegates intelligently, never stops |
+| **📋 Planner** | Strategist | Web search, doc caching, file-level task breakdown |
+| **🔨 Worker** | Builder | TDD isolation, 1 file = 1 session, parallel execution |
+| **✅ Reviewer** | Quality Gate | E2E tests, sync checks, integration validation |
 
-### 🔑 Core Principles
+---
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│  🔒 ISOLATION    │  🔄 SYNC       │  ✅ STABILITY          │
-├─────────────────────────────────────────────────────────────┤
-│  Each worker     │  Shared state  │  TODO 100% complete    │
-│  owns 1 file     │  via .opencode │  + Zero sync issues    │
-│  No conflicts    │  Real-time     │  = Mission SEALED      │
-└─────────────────────────────────────────────────────────────┘
-```
+## 📊 System Specs
 
+| Capability | Value |
+|------------|-------|
+| **Parallel Sessions** | 50 simultaneous |
+| **Concurrency per Agent** | 10 default |
+| **Poll Interval** | 1 second |
+| **Session TTL** | 60 minutes |
+| **Auto-Recovery** | 3 attempts per session |
+| **Max Iterations** | 20 per mission |
+| **Memory Limit** | 1,000 tasks (auto GC) |
 
 ---
 
-## 🎮 Usage
-
-| Mode | Trigger | What Happens |
-|------|---------|--------------|
-| **Commander Mode** 🎯 | `/task "mission"` | Full autonomous execution |
-| **Chat Mode** 💬 | Just type normally | Simple Q&A, no automation |
+## 🎮 What Happens When You Run `/task`
 
-**Example Commands:**
-```bash
-/task "Fix the login bug in docker-compose"
-/task "Add dark mode to the entire app"
-/task "Refactor the API to TypeScript"
-```
+1. **🎯 Commander** reads state, creates TODO
+2. **📋 Planner** breaks down into file-level tasks  
+3. **🔨 Workers** build in parallel (50 simultaneous sessions!)
+4. **✅ Reviewer** validates, runs E2E tests
+5. **♻️ Loop** until all TODOs checked + zero issues
+6. **🎖️ SEALED** — mission complete
 
-**Stop anytime:** `/stop` or `/cancel`
+> **Tip:** Stop anytime with `/stop`
 
 <div align="center">
   <p><strong>TUI</strong></p>
@@ -130,37 +138,29 @@ A multi-agent system that **autonomously executes complex tasks** from start to
   <p><strong>Window</strong></p>
   <img src="assets/window_image.png" alt="Commander Window" width="600" />
 </div>
----
-
-## 🤖 The 4 Agents
-
-| Agent | Role | Key Actions |
-|-------|------|-------------|
-| **Commander** 🎯 | Orchestrator | Delegates tasks, monitors progress, seals mission |
-| **Planner** 📋 | Research + Plan | Web search, doc caching, TODO creation |
-| **Worker** 🔨 | Implementation | Code writing, file ops, background commands |
-| **Reviewer** ✅ | Quality Control | Verification, TODO updates, context management |
 
 ---
 
-## 📊 Resource Limits
+## 🔧 Self-Healing Features
 
-| Resource | Limit |
-|----------|-------|
-| Parallel Sessions | 50 |
-| Tasks in Memory | 1,000 (auto GC) |
-| Session TTL | 60 min |
-| Recovery Attempts | 3 per session |
-| Max Iterations | 20 per mission |
+```
+┌────────────────────────────────────────────────────────────┐
+│ ERROR TYPE              │ AUTO-RECOVERY ACTION             │
+├────────────────────────────────────────────────────────────┤
+│ Tool crash              │ Inject recovery prompt           │
+│ Rate limit              │ Exponential backoff + retry      │
+│ Context overflow        │ Smart compaction                 │
+│ Thinking block error    │ Auto-restructure                 │
+│ Session timeout         │ Resume from checkpoint           │
+│ Build failure           │ Loop back, fix, retry            │
+└────────────────────────────────────────────────────────────┘
+```
 
 ---
 
 ## 📚 Documentation
 
-For detailed architecture, directory structure, and internals:
-
-- **[System Architecture](docs/SYSTEM_ARCHITECTURE.md)** — Complete technical documentation
-- [Release Notes](docs/releases/) — Version history
+- **[System Architecture](docs/SYSTEM_ARCHITECTURE.md)** — Full technical deep-dive
 
 ---
 
@@ -179,5 +179,6 @@ MIT License. [LICENSE](LICENSE)
 ---
 
 <div align="center">
-  <b>🚀 v0.9.4 — "Relentless execution until absolute success."</b>
+  <h3>🚀 v0.9.7 — "Relentless execution until absolute success."</h3>
+  <p><i>Multi-agent. Parallel. Non-blocking. Self-healing. Enterprise-grade.</i></p>
 </div>

package/dist/index.js

@@ -232,6 +232,9 @@ var SESSION_EVENTS = {
   CREATED: "session.created",
   ERROR: "session.error"
 };
+var MESSAGE_EVENTS = {
+  UPDATED: "message.updated"
+};
 
 // src/shared/session/constants/event-types.ts
 var TASK_EVENTS = {
@@ -311,7 +314,11 @@ var PART_TYPES = {
   TEXT: "text",
   REASONING: "reasoning",
   TOOL_CALL: "tool_call",
-  TOOL_RESULT: "tool_result"
+  TOOL_RESULT: "tool_result",
+  /** Anthropic-style tool reference */
+  TOOL: "tool",
+  /** Anthropic-style tool invocation */
+  TOOL_USE: "tool_use"
 };
 
 // src/shared/message/constants/prompts.ts
@@ -321,6 +328,20 @@ var PROMPTS = {
   CONTINUE_DEFAULT: "continue from where we left off"
 };
 
+// src/shared/message/constants/message-roles.ts
+var MESSAGE_ROLES = {
+  /** AI assistant message */
+  ASSISTANT: "assistant",
+  /** User message */
+  USER: "user",
+  /** System message */
+  SYSTEM: "system"
+};
+var SESSION_STATUS = {
+  IDLE: "idle",
+  BUSY: "busy"
+};
+
 // src/shared/errors/patterns.ts
 var ERROR_PATTERNS = {
   TOOL_RESULT_MISSING: /tool_result_missing|tool result.*missing/i,
@@ -15957,7 +15978,7 @@ var TaskPoller = class {
       for (const task of running) {
         try {
           const sessionStatus = allStatuses[task.sessionID];
-          if (sessionStatus?.type === "idle") {
+          if (sessionStatus?.type === SESSION_STATUS.IDLE) {
             const elapsed2 = Date.now() - task.startedAt.getTime();
             if (elapsed2 < CONFIG.MIN_STABILITY_MS) continue;
             if (!await this.validateSessionHasOutput(task.sessionID)) continue;
@@ -15984,7 +16005,7 @@ var TaskPoller = class {
     try {
       const response = await this.client.session.messages({ path: { id: sessionID } });
       const messages = response.data ?? [];
-      return messages.some((m) => m.info?.role === "assistant" && m.parts?.some((p) => p.type === PART_TYPES.TEXT && p.text?.trim() || p.type === "tool"));
+      return messages.some((m) => m.info?.role === MESSAGE_ROLES.ASSISTANT && m.parts?.some((p) => p.type === PART_TYPES.TEXT && p.text?.trim() || p.type === PART_TYPES.TOOL));
     } catch {
       return true;
     }
@@ -16010,13 +16031,13 @@ var TaskPoller = class {
       const result = await this.client.session.messages({ path: { id: task.sessionID } });
       if (result.error) return;
       const messages = result.data ?? [];
-      const assistantMsgs = messages.filter((m) => m.info?.role === "assistant");
+      const assistantMsgs = messages.filter((m) => m.info?.role === MESSAGE_ROLES.ASSISTANT);
       let toolCalls = 0;
       let lastTool;
       let lastMessage;
       for (const msg of assistantMsgs) {
         for (const part of msg.parts ?? []) {
-          if (part.type === "tool_use" || part.tool) {
+          if (part.type === PART_TYPES.TOOL_USE || part.tool) {
             toolCalls++;
             lastTool = part.tool || part.name;
           }
@@ -16332,7 +16353,7 @@ var ParallelAgentManager = class _ParallelAgentManager {
       const result = await this.client.session.messages({ path: { id: task.sessionID } });
       if (result.error) return `Error: ${result.error}`;
       const messages = result.data ?? [];
-      const lastMsg = messages.filter((m) => m.info?.role === "assistant").reverse()[0];
+      const lastMsg = messages.filter((m) => m.info?.role === MESSAGE_ROLES.ASSISTANT).reverse()[0];
       if (!lastMsg) return "(No response)";
       const text = lastMsg.parts?.filter((p) => p.type === PART_TYPES.TEXT || p.type === PART_TYPES.REASONING).map((p) => p.text ?? "").filter(Boolean).join("\n") ?? "";
       task.result = text;
@@ -16370,7 +16391,7 @@ var ParallelAgentManager = class _ParallelAgentManager {
   handleTaskError(taskId, error45) {
     const task = this.store.get(taskId);
     if (!task) return;
-    task.status = "error";
+    task.status = TASK_STATUS.ERROR;
     task.error = error45 instanceof Error ? error45.message : String(error45);
     task.completedAt = /* @__PURE__ */ new Date();
     if (task.concurrencyKey) this.concurrency.release(task.concurrencyKey);
@@ -16395,20 +16416,20 @@ async function validateSessionHasOutput(session, sessionID) {
     const response = await session.messages({ path: { id: sessionID } });
     const messages = response.data ?? [];
     const hasAssistantMessage = messages.some(
-      (m) => m.info?.role === "assistant"
+      (m) => m.info?.role === MESSAGE_ROLES.ASSISTANT
     );
     if (!hasAssistantMessage) {
       return false;
     }
     const hasContent = messages.some((m) => {
-      if (m.info?.role !== "assistant") return false;
+      if (m.info?.role !== MESSAGE_ROLES.ASSISTANT) return false;
       const parts = m.parts ?? [];
       return parts.some(
         (p) => (
           // Text content
           p.type === PART_TYPES.TEXT && p.text && p.text.trim().length > 0 || // Reasoning content
           p.type === PART_TYPES.REASONING && p.text && p.text.trim().length > 0 || // Tool calls (indicates work was done)
-          p.type === "tool" || p.type === "tool_use" || p.tool
+          p.type === PART_TYPES.TOOL || p.type === PART_TYPES.TOOL_USE || p.tool
         )
       );
     });
@@ -16448,7 +16469,7 @@ async function pollWithSafetyLimits(session, sessionID, startTime) {
         stablePolls = 0;
         continue;
       }
-      if (sessionStatus.type !== "idle") {
+      if (sessionStatus.type !== SESSION_STATUS.IDLE) {
         stablePolls = 0;
         continue;
       }
@@ -16491,7 +16512,7 @@ async function extractSessionResult(session, sessionID) {
   try {
     const msgs = await session.messages({ path: { id: sessionID } });
     const messages = msgs.data ?? [];
-    const lastMsg = messages.filter((m) => m.info?.role === "assistant").reverse()[0];
+    const lastMsg = messages.filter((m) => m.info?.role === MESSAGE_ROLES.ASSISTANT).reverse()[0];
     const text = lastMsg?.parts?.filter((p) => p.type === PART_TYPES.TEXT || p.type === PART_TYPES.REASONING).map((p) => p.text ?? "").join("\n") || "";
     return text;
   } catch (error45) {
@@ -18159,7 +18180,7 @@ async function detectSealInSession(client, sessionID) {
   try {
     const response = await client.session.messages({ path: { id: sessionID } });
     const messages = response.data ?? [];
-    const assistantMessages = messages.filter((m) => m.info?.role === "assistant");
+    const assistantMessages = messages.filter((m) => m.info?.role === MESSAGE_ROLES.ASSISTANT);
     const recentMessages = assistantMessages.slice(-3);
     for (const msg of recentMessages) {
       if (!msg.parts) continue;
@@ -18450,12 +18471,12 @@ function createEventHandler(ctx) {
       manager.handleEvent(event);
     } catch {
     }
-    if (event.type === "session.created") {
+    if (event.type === SESSION_EVENTS.CREATED) {
       const sessionID = event.properties?.id || "";
       log2("[event-handler] session.created", { sessionID });
       presets.missionStarted(`Session ${sessionID.slice(0, 12)}...`);
     }
-    if (event.type === "session.deleted") {
+    if (event.type === SESSION_EVENTS.DELETED) {
       const sessionID = event.properties?.id || event.properties?.info?.id || "";
       const session = sessions.get(sessionID);
       if (session) {
@@ -18471,7 +18492,7 @@ function createEventHandler(ctx) {
         presets.sessionCompleted(sessionID, duration3);
       }
     }
-    if (event.type === "session.error") {
+    if (event.type === SESSION_EVENTS.ERROR) {
       const sessionID = event.properties?.sessionId || event.properties?.sessionID || "";
       const error45 = event.properties?.error;
       log2("[event-handler] session.error", { sessionID, error: error45 });
@@ -18493,19 +18514,19 @@ function createEventHandler(ctx) {
       }
       presets.taskFailed("session", String(error45).slice(0, 50));
     }
-    if (event.type === "message.updated") {
+    if (event.type === MESSAGE_EVENTS.UPDATED) {
       const messageInfo = event.properties?.info;
       const sessionID = messageInfo?.sessionID;
       const role = messageInfo?.role;
-      if (sessionID && role === "assistant") {
+      if (sessionID && role === MESSAGE_ROLES.ASSISTANT) {
         markRecoveryComplete(sessionID);
       }
-      if (sessionID && role === "user") {
+      if (sessionID && role === MESSAGE_ROLES.USER) {
         handleUserMessage(sessionID);
         handleUserMessage2(sessionID);
       }
     }
-    if (event.type === "session.idle") {
+    if (event.type === SESSION_EVENTS.IDLE) {
       const sessionID = event.properties?.sessionID || "";
       if (sessionID) {
         const isMainSession = sessions.has(sessionID);

package/dist/shared/message/constants/index.d.ts

@@ -4,3 +4,5 @@
 export { PART_TYPES } from "./part-types.js";
 export { PROMPTS } from "./prompts.js";
 export { SLASH_COMMANDS } from "./slash-commands.js";
+export { PLUGIN_HOOKS, type PluginHookName } from "./plugin-hooks.js";
+export { MESSAGE_ROLES, SESSION_STATUS, type MessageRole, type SessionStatus } from "./message-roles.js";

package/dist/shared/message/constants/message-roles.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Message Role Constants
+ *
+ * OpenCode message roles
+ * Use these instead of hardcoded strings
+ */
+export declare const MESSAGE_ROLES: {
+    /** AI assistant message */
+    readonly ASSISTANT: "assistant";
+    /** User message */
+    readonly USER: "user";
+    /** System message */
+    readonly SYSTEM: "system";
+};
+export type MessageRole = typeof MESSAGE_ROLES[keyof typeof MESSAGE_ROLES];
+/**
+ * Session Status Types
+ */
+export declare const SESSION_STATUS: {
+    readonly IDLE: "idle";
+    readonly BUSY: "busy";
+};
+export type SessionStatus = typeof SESSION_STATUS[keyof typeof SESSION_STATUS];

package/dist/shared/message/constants/part-types.d.ts

@@ -6,4 +6,8 @@ export declare const PART_TYPES: {
     readonly REASONING: "reasoning";
     readonly TOOL_CALL: "tool_call";
     readonly TOOL_RESULT: "tool_result";
+    /** Anthropic-style tool reference */
+    readonly TOOL: "tool";
+    /** Anthropic-style tool invocation */
+    readonly TOOL_USE: "tool_use";
 };

package/dist/shared/message/constants/plugin-hooks.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Plugin Hook Constants
+ *
+ * OpenCode plugin hook names (from @opencode-ai/plugin)
+ * Use these instead of hardcoded strings
+ */
+export declare const PLUGIN_HOOKS: {
+    /** Intercepts user messages before sending to LLM */
+    readonly CHAT_MESSAGE: "chat.message";
+    /** Runs after LLM finishes responding */
+    readonly ASSISTANT_DONE: "assistant.done";
+    /** Runs after any tool call completes */
+    readonly TOOL_EXECUTE_AFTER: "tool.execute.after";
+};
+export type PluginHookName = typeof PLUGIN_HOOKS[keyof typeof PLUGIN_HOOKS];

package/dist/shared/session/constants/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Session constants
  */
-export { SESSION_EVENTS } from "./session-events.js";
-export type { SessionEventType } from "./session-events.js";
+export { SESSION_EVENTS, MESSAGE_EVENTS } from "./session-events.js";
+export type { SessionEventType, MessageEventType } from "./session-events.js";
 export { TASK_EVENTS, TODO_EVENTS, SESSION_EVENTS as SESSION_STATE_EVENTS, DOCUMENT_EVENTS, MISSION_EVENTS, SPECIAL_EVENTS, EVENT_TYPES, } from "./event-types.js";
 export type { EventTypeValue } from "./event-types.js";

package/dist/shared/session/constants/session-events.d.ts

@@ -8,3 +8,10 @@ export declare const SESSION_EVENTS: {
     readonly ERROR: "session.error";
 };
 export type SessionEventType = (typeof SESSION_EVENTS)[keyof typeof SESSION_EVENTS];
+/**
+ * Message Event Types
+ */
+export declare const MESSAGE_EVENTS: {
+    readonly UPDATED: "message.updated";
+};
+export type MessageEventType = (typeof MESSAGE_EVENTS)[keyof typeof MESSAGE_EVENTS];

package/package.json

@@ -2,7 +2,7 @@
   "name": "opencode-orchestrator",
   "displayName": "OpenCode Orchestrator",
   "description": "Distributed Cognitive Architecture for OpenCode. Turns simple prompts into specialized multi-agent workflows (Planner, Coder, Reviewer).",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "author": "agnusdei1207",
   "license": "MIT",
   "repository": {