opencode-orchestrator 0.6.28 → 0.7.0

package/README.md

@@ -8,7 +8,7 @@
 
 [![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)
-[![Tests](https://img.shields.io/badge/tests-167%20passed-brightgreen.svg)]()
+[![Tests](https://img.shields.io/badge/tests-216%20passed-brightgreen.svg)]()
 
 ---
 
@@ -18,74 +18,76 @@ Multi-agent system that autonomously executes complex tasks. Commander delegates
 
 | Capability | Detail |
 |------------|--------|
-| **Agents** | 7 specialized (Architect, Builder, Inspector, Recorder, Librarian, Researcher) |
-| **Parallel Sessions** | Up to 50 concurrent |
+| **Agents** | 4 consolidated (Commander, Planner, Worker, Reviewer) |
+| **Parallel Sessions** | Up to 50 concurrent Worker Sessions |
 | **Context Management** | `.opencode/` with adaptive summarization |
 | **Memory Safety** | Auto GC, disk archiving |
-| **Error Handling** | Pattern-based auto recovery |
+| **Error Handling** | Pattern-based auto recovery + session recovery |
+| **Todo Continuation** | Auto-continues when todos remain |
+| **Smart Notifications** | TaskToastManager with consolidated views |
 
 ---
 
-## 🏛️ System Architecture
+## 🏛️ Master Session Architecture
 
 ```
 ┌─────────────────────────────────────────────────────────────────────────────┐
 │                           👤 USER REQUEST                                   │
-│                        OpenCode Terminal / UI                               │
+│                        "/task Build a REST API"                             │
 └─────────────────────────────────────────────────────────────────────────────┘
                                      │
                                      ▼
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│                        🔌 ORCHESTRATOR PLUGIN                               │
+│                    🎯 MASTER SESSION (Commander Agent)                      │
+│                                                                             │
+│  ┌───────────────────────────────────────────────────────────────────────┐  │
+│  │ 1️⃣ THINK     → Analyze request, assess complexity (L1/L2/L3)         │  │
+│  │ 2️⃣ PLAN      → Create .opencode/todo.md via Planner                  │  │
+│  │ 3️⃣ DELEGATE  → Spawn Worker Sessions via delegate_task              │  │
+│  │ 4️⃣ MONITOR   → Watch .opencode/ for progress, handle completions     │  │
+│  └───────────────────────────────────────────────────────────────────────┘  │
 │                                                                             │
 │  ┌─────────────────┐  ┌─────────────────────────────────────────────────┐  │
-│  │  Session State  │  │                   7 AGENTS                      │  │
-│  │  Map<id,state>  │  │  🎯 Commander (primary)                         │  │
-│  └─────────────────┘  │     ↓ delegate_task / OpenCode Task tool        │  │
-│                       │  🏗️ Architect  🔨 Builder  🔍 Inspector         │  │
-│  ┌─────────────────┐  │  💾 Recorder   📚 Librarian 🔬 Researcher       │  │
-│  │  Plugin Hooks   │  │     (subagents, hidden)                         │  │
-│  │  config         │  └─────────────────────────────────────────────────┘  │
-│  │  chat.message   │                                                       │
-│  │  tool.execute   │  ┌─────────────────────────────────────────────────┐  │
-│  └─────────────────┘  │                  12 TOOLS                       │  │
-│                       │  delegate_task    get_task_result   list_tasks  │  │
-│                       │  webfetch         websearch         codesearch  │  │
-│                       │  run_background   grep_search       mgrep       │  │
+│  │  Session State  │  │               4 CONSOLIDATED AGENTS             │  │
+│  │  Map<id,state>  │  │  🎯 Commander  📋 Planner                       │  │
+│  └─────────────────┘  │  🔨 Worker     ✅ Reviewer                       │  │
+│                       └─────────────────────────────────────────────────┘  │
+│  ┌─────────────────┐
+│  │  Plugin Hooks   │                                                       │
+│  │  event          │  ┌─────────────────────────────────────────────────┐  │
+│  │  chat.message   │  │ 🔄 SessionRecovery (auto error handling)        │  │
+│  │  tool.execute   │  │ 📋 TodoContinuation (auto-resume on idle)       │  │
+│  └─────────────────┘  │ 📣 TaskToastManager (consolidated notifications)│  │
 │                       └─────────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────────────────────┘
                                      │
-                                     ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                      ⚙️ PARALLEL AGENT MANAGER                              │
-│                                                                             │
-│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────────────────────┐   │
-│  │ TaskLauncher │  │  TaskPoller  │  │    ConcurrencyController        │   │
-│  │   launch()   │  │   poll()     │  │    MAX=50, PER_AGENT=10         │   │
-│  └──────────────┘  └──────────────┘  └─────────────────────────────────┘   │
-│                                                                             │
-│  ┌─────────────────────────────────────────────────────────────────────┐   │
-│  │                    TaskStore (MAX: 1000 tasks)                      │   │
-│  │    pending → running → completed/error → archived (disk)            │   │
-│  └─────────────────────────────────────────────────────────────────────┘   │
-└─────────────────────────────────────────────────────────────────────────────┘
+                        delegate_task (async)
                                      │
+           ┌─────────────────────────┼─────────────────────────┐
+           ▼                         ▼                         ▼
+┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐
+│  ⚡ Worker Session 1 │  │  ⚡ Worker Session 2 │  │  ⚡ Worker Session N │
+│  Agent: Planner     │  │  Agent: Worker      │  │  Agent: Reviewer    │
+│                     │  │                     │  │                     │
+│  • Independent exec │  │  • Independent exec │  │  • Independent exec │
+│  • Read/Write       │  │  • Read/Write       │  │  • Read/Write       │
+│    .opencode/       │  │    .opencode/       │  │    .opencode/       │
+│  • Notify parent    │  │  • Notify parent    │  │  • Notify parent    │
+│    on complete      │  │    on complete      │  │    on complete      │
+└─────────────────────┘  └─────────────────────┘  └─────────────────────┘
+           │                         │                         │
+           └─────────────────────────┼─────────────────────────┘
                                      ▼
 ┌─────────────────────────────────────────────────────────────────────────────┐
-│                       🔄 CHILD SESSIONS POOL (up to 50)                     │
+│                    📁 SHARED CONTEXT (.opencode/)                           │
 │                                                                             │
-│    Session 1        Session 2        Session 3            Session N         │
-│    Builder 🔨       Librarian 📚     Inspector 🔍         ...               │
-└─────────────────────────────────────────────────────────────────────────────┘
-                                     │
-                                     ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                       📁 SMART CONTEXT (.opencode/)                         │
+│  .opencode/todo.md     ← Master TODO (Planner creates, Reviewer updates)  │
+│  .opencode/context.md  ← Adaptive context (shrinks as progress increases)  │
+│  .opencode/docs/       ← Cached docs (Planner/Worker save, auto-expire)    │
+│  .opencode/archive/    ← Old context for reference                         │
 │                                                                             │
-│    .opencode/todo.md    - Master TODO list (Recorder manages)               │
-│    .opencode/context.md - Adaptive size based on project phase              │
-│    .opencode/docs/      - Cached documentation (auto-cleanup)               │
-│    .opencode/archive/   - Old context for reference                         │
+│  ⚡ All sessions read/write this shared workspace                           │
+│  📊 Progress is tracked via todo.md checkboxes                              │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -158,12 +160,9 @@ What's the difference between useState and useReducer?
 | Agent            | Role         | Responsibility                     |
 | :--------------- | :----------- | :--------------------------------- |
 | **Commander** 🎯 | Orchestrator | Autonomous mission control         |
-| **Architect** 🏗️ | Planner      | Hierarchical task decomposition    |
-| **Builder** 🔨   | Developer    | Full-stack implementation          |
-| **Inspector** 🔍 | Quality      | Audit, auto-fix & doc verification |
-| **Recorder** 💾  | Context      | Progress tracking                  |
-| **Librarian** 📚 | Research     | Documentation & API research       |
-| **Researcher** 🔬 | Investigation | Pre-task research & analysis      |
+| **Planner** 📋   | Planner + Research | Task decomposition, research, caching docs |
+| **Worker** 🔨    | Developer + Docs | Full-stack implementation, documentation |
+| **Reviewer** ✅  | Quality + Context | Verification, TODO updates, context management |
 
 ---
 
@@ -195,19 +194,43 @@ What's the difference between useState and useReducer?
 | Event History | 100 | Ring buffer |
 | Session TTL | 60 min | Auto cleanup |
 | Poll Interval | 1 second | Fast completion detection |
+| Max Poll Count | 600 | Hard limit prevents infinite loops |
+| Sync Timeout | 5 min | Safe delegate_task timeout |
+| Recovery Attempts | 3 | Auto session error recovery |
 
 ---
 
 ## 🧪 Test Coverage
 
 ```
-Test Files:  18 passed
-Tests:       198 passed
+Test Files:  19 passed
+Tests:       216 passed
 Duration:    ~4.3s
 ```
 
 ---
 
+## 🔄 Reliability Features
+
+### Session Recovery
+Automatic recovery from common errors:
+- `tool_result_missing` - Tool crash recovery
+- `thinking_block_order` - Thinking block issues
+- `rate_limit` - API rate limiting with backoff
+- Max 3 recovery attempts per session
+
+### Todo Continuation
+- Monitors `session.idle` events
+- 2-second countdown before auto-continuation
+- Cancels on user interaction
+- Skips if background tasks running
+
+### noReply Optimization
+- Individual task completion: `noReply: true` (saves tokens)
+- All tasks complete: `noReply: false` (AI processes results)
+
+---
+
 ## Uninstall
 
 ```bash

package/dist/agents/consolidated/planner.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Planner Agent - Strategic Planning + Research
+ *
+ * Combines: Architect + Researcher
+ * Role: Plan tasks, research technologies, prepare documentation
+ */
+import { AgentDefinition } from "../../shared/agent.js";
+export declare const planner: AgentDefinition;

package/dist/agents/consolidated/reviewer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reviewer Agent - Verification + Context Management
+ *
+ * Combines: Inspector + Recorder
+ * Role: Verify implementations, track progress, manage context
+ */
+import { AgentDefinition } from "../../shared/agent.js";
+export declare const reviewer: AgentDefinition;

package/dist/agents/consolidated/worker.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Worker Agent - Implementation + Documentation
+ *
+ * Combines: Builder + Librarian
+ * Role: Write code, create files, fetch and cache documentation
+ */
+import { AgentDefinition } from "../../shared/agent.js";
+export declare const worker: AgentDefinition;

package/dist/agents/definitions.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Agent Definitions Registry
+ *
+ * Consolidated agent architecture (v2):
+ * - Commander: Master orchestrator
+ * - Planner: Planning + Research
+ * - Worker: Implementation + Documentation
+ * - Reviewer: Verification + Context Management
+ */
 import { AgentDefinition } from "../shared/agent.js";
 export declare const AGENTS: Record<string, AgentDefinition>;

package/dist/core/agents/manager/task-cleaner.d.ts

@@ -1,5 +1,9 @@
 /**
- * Task Cleaner - Handles cleanup and expiration of tasks
+ * Task Cleaner - Handles cleanup, expiration, and notifications for tasks
+ *
+ * noReply Strategy:
+ * - Individual task completion: noReply=true (save tokens)
+ * - All tasks complete: noReply=false (let AI process results)
  */
 import type { PluginInput } from "@opencode-ai/plugin";
 import { TaskStore } from "../task-store.js";
@@ -12,6 +16,12 @@ export declare class TaskCleaner {
     constructor(client: OpencodeClient, store: TaskStore, concurrency: ConcurrencyController);
     pruneExpiredTasks(): void;
     scheduleCleanup(taskId: string): void;
+    /**
+     * Notify parent session when task(s) complete.
+     * Uses noReply strategy:
+     * - Individual completion: noReply=true (silent notification, save tokens)
+     * - All complete: noReply=false (AI should process and report results)
+     */
     notifyParentIfAllComplete(parentSessionID: string): Promise<void>;
 }
 export {};

package/dist/core/agents/manager.d.ts

@@ -9,6 +9,7 @@
  * This is the main facade that composes the specialized components.
  */
 import type { PluginInput } from "@opencode-ai/plugin";
+import { ConcurrencyController } from "./concurrency.js";
 import { formatDuration } from "./format.js";
 import type { ParallelTask } from "./interfaces/parallel-task.interface.js";
 import type { LaunchInput } from "./interfaces/launch-input.interface.js";
@@ -39,6 +40,7 @@ export declare class ParallelAgentManager {
     getResult(taskId: string): Promise<string | null>;
     setConcurrencyLimit(agentType: string, limit: number): void;
     getPendingCount(parentSessionID: string): number;
+    getConcurrency(): ConcurrencyController;
     cleanup(): void;
     formatDuration: typeof formatDuration;
     handleEvent(event: {

package/dist/core/loop/todo-continuation.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Todo Continuation Handler
+ *
+ * Monitors session.idle events and automatically continues execution
+ * if there are incomplete todos remaining.
+ *
+ * Features:
+ * - Countdown toast before resuming (gives user chance to cancel)
+ * - Skips if background tasks are running
+ * - Respects abort/cancel from user
+ */
+import type { PluginInput } from "@opencode-ai/plugin";
+type OpencodeClient = PluginInput["client"];
+/**
+ * Handle session.idle event - start countdown if todos remain
+ */
+export declare function handleSessionIdle(client: OpencodeClient, sessionID: string, mainSessionID?: string): Promise<void>;
+/**
+ * Handle user message - cancel countdown (user is interacting)
+ */
+export declare function handleUserMessage(sessionID: string): void;
+/**
+ * Handle abort/cancel - prevent automatic continuation
+ */
+export declare function handleAbort(sessionID: string): void;
+/**
+ * Clean up session state
+ */
+export declare function cleanupSession(sessionID: string): void;
+/**
+ * Check if there's a pending continuation countdown
+ */
+export declare function hasPendingContinuation(sessionID: string): boolean;
+export {};

package/dist/core/notification/presets.d.ts

@@ -20,4 +20,5 @@ export declare const presets: {
     warningRateLimited: () => import("./types.js").ToastMessage;
     errorRecovery: (action: string) => import("./types.js").ToastMessage;
     warningMaxDepth: (depth: number) => import("./types.js").ToastMessage;
+    warningMaxRetries: () => import("./types.js").ToastMessage;
 };

package/dist/core/notification/task-toast-manager.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Task Toast Manager
+ *
+ * Manages toast notifications for parallel/background tasks.
+ * Provides consolidated view of running and queued tasks.
+ *
+ * Features:
+ * - Real-time task status display
+ * - Concurrency info (e.g., "2/5 slots")
+ * - New task highlighting
+ * - Completion summaries
+ */
+import type { PluginInput } from "@opencode-ai/plugin";
+import type { ConcurrencyController } from "../agents/concurrency.js";
+type OpencodeClient = PluginInput["client"];
+export type TaskStatus = "running" | "queued" | "completed" | "error" | "cancelled";
+export interface TrackedTask {
+    id: string;
+    description: string;
+    agent: string;
+    status: TaskStatus;
+    startedAt: Date;
+    isBackground: boolean;
+    parentSessionID?: string;
+    sessionID?: string;
+}
+export interface TaskCompletionInfo {
+    id: string;
+    description: string;
+    duration: string;
+    status: TaskStatus;
+    error?: string;
+}
+export declare class TaskToastManager {
+    private tasks;
+    private client;
+    private concurrency;
+    /**
+     * Initialize the manager with OpenCode client
+     */
+    init(client: OpencodeClient, concurrency?: ConcurrencyController): void;
+    /**
+     * Set concurrency controller (can be set after init)
+     */
+    setConcurrencyController(concurrency: ConcurrencyController): void;
+    /**
+     * Add a new task and show consolidated toast
+     */
+    addTask(task: {
+        id: string;
+        description: string;
+        agent: string;
+        isBackground: boolean;
+        parentSessionID?: string;
+        sessionID?: string;
+        status?: TaskStatus;
+    }): void;
+    /**
+     * Update task status
+     */
+    updateTask(id: string, status: TaskStatus): void;
+    /**
+     * Remove a task
+     */
+    removeTask(id: string): void;
+    /**
+     * Get all running tasks (newest first)
+     */
+    getRunningTasks(): TrackedTask[];
+    /**
+     * Get all queued tasks (oldest first - FIFO)
+     */
+    getQueuedTasks(): TrackedTask[];
+    /**
+     * Get tasks by parent session
+     */
+    getTasksByParent(parentSessionID: string): TrackedTask[];
+    /**
+     * Format duration since task started
+     */
+    private formatDuration;
+    /**
+     * Get concurrency info string (e.g., " [2/5]")
+     */
+    private getConcurrencyInfo;
+    /**
+     * Build consolidated task list message
+     */
+    private buildTaskListMessage;
+    /**
+     * Show consolidated toast with all running/queued tasks
+     */
+    private showTaskListToast;
+    /**
+     * Show task completion toast
+     */
+    showCompletionToast(info: TaskCompletionInfo): void;
+    /**
+     * Show all-tasks-complete summary toast
+     */
+    showAllCompleteToast(parentSessionID: string, completedTasks: TaskCompletionInfo[]): void;
+    /**
+     * Show progress toast (for long-running tasks)
+     */
+    showProgressToast(taskId: string, progress: {
+        current: number;
+        total: number;
+        message?: string;
+    }): void;
+    /**
+     * Clear all tracked tasks
+     */
+    clear(): void;
+    /**
+     * Get task count stats
+     */
+    getStats(): {
+        running: number;
+        queued: number;
+        total: number;
+    };
+}
+/**
+ * Get the global TaskToastManager instance
+ */
+export declare function getTaskToastManager(): TaskToastManager | null;
+/**
+ * Initialize the global TaskToastManager
+ */
+export declare function initTaskToastManager(client: OpencodeClient, concurrency?: ConcurrencyController): TaskToastManager;
+export {};

package/dist/core/notification/toast.d.ts

@@ -6,3 +6,4 @@
 export type { ToastVariant, ToastMessage, ToastOptions } from "./types.js";
 export { show, dismiss, getActive, getHistory, clear, onToast, initToastClient } from "./toast-core.js";
 export { presets } from "./presets.js";
+export { TaskToastManager, getTaskToastManager, initTaskToastManager, type TrackedTask, type TaskStatus, type TaskCompletionInfo, } from "./task-toast-manager.js";

package/dist/core/recovery/session-recovery.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Session Recovery Event Handler
+ *
+ * Integrates with the OpenCode event system to automatically recover from session errors.
+ *
+ * Supported error types:
+ * - tool_result_missing: Tool crashed, inject error message
+ * - thinking_block_order: Thinking block ordering issue
+ * - rate_limit: API rate limiting
+ * - context_overflow: Token limit exceeded
+ */
+import type { PluginInput } from "@opencode-ai/plugin";
+type OpencodeClient = PluginInput["client"];
+/**
+ * Handle session error event and attempt recovery
+ */
+export declare function handleSessionError(client: OpencodeClient, sessionID: string, error: unknown, properties?: Record<string, unknown>): Promise<boolean>;
+/**
+ * Mark that recovery is complete for a session
+ */
+export declare function markRecoveryComplete(sessionID: string): void;
+/**
+ * Clean up session recovery state
+ */
+export declare function cleanupSessionRecovery(sessionID: string): void;
+/**
+ * Check if session is currently recovering
+ */
+export declare function isSessionRecovering(sessionID: string): boolean;
+export {};

package/dist/core/task/parser.d.ts

@@ -1,8 +1,8 @@
 /**
- * Task Parser - Parse hierarchy from Architect output
+ * Task Parser - Parse hierarchy from Planner output
  */
 import type { TaskHierarchy } from "./interfaces.js";
 /**
- * Parse task hierarchy from text (Architect output)
+ * Parse task hierarchy from text (Planner output)
  */
 export declare function parseFromText(sessionId: string, text: string): TaskHierarchy;

package/dist/index.d.ts

@@ -1,14 +1,14 @@
 /**
  * OpenCode Orchestrator Plugin
  *
- * This is the main entry point for the 5-Agent structured architecture.
- * We've optimized it for weaker models by using:
+ * This is the main entry point for the 4-Agent consolidated architecture.
+ * We've optimized it for better efficiency by using:
  * - XML-structured prompts with clear boundaries
  * - Explicit reasoning patterns (THINK -> ACT -> OBSERVE -> ADJUST)
  * - Evidence-based completion requirements
  * - Autonomous execution loop that keeps going until done
  *
- * The agents are: Commander, Architect, Builder, Inspector, Recorder
+ * The agents are: Commander, Planner, Worker, Reviewer
  */
 import type { Plugin } from "@opencode-ai/plugin";
 declare const OrchestratorPlugin: Plugin;