opencode-orchestrator 0.5.30 → 0.6.1

package/README.md

@@ -30,276 +30,67 @@
 ## 🏛️ System Architecture
 
 ```
-┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
-│                                                                                                        │
-│                                         USER REQUEST                                                   │
-│                                    (OpenCode Terminal / UI)                                            │
-│                                              │                                                         │
-└──────────────────────────────────────────────┼────────────────────────────────────────────────────────┘
-                                               │
-                                               ▼
-┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
-│                                                                                                        │
-│                              ORCHESTRATOR PLUGIN  (src/index.ts)                                       │
-│                                                                                                        │
-│  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐   │
-│  │   Session State     │  │   Agent Definitions │  │   Tools Registry    │  │   Toast.enable      │   │
-│  │   Map<sessionId,    │  │   (7 agents)        │  │   (15+ tools)       │  │   AutoToasts()      │   │
-│  │   {step, maxSteps,  │  │                     │  │                     │  │   → EventBus sub    │   │
-│  │    timestamp}>      │  │   • Commander 🎯    │  │   • call_agent      │  │                     │   │
-│  │                     │  │   • Architect 🏗️   │  │   • launch_parallel │  └─────────────────────┘   │
-│  │   Cleanup:          │  │   • Builder 🔨     │  │   • check_parallel  │                            │
-│  │   session.deleted   │  │   • Inspector 🔍   │  │   • webfetch        │  ┌─────────────────────┐   │
-│  │   → sessions.delete │  │   • Recorder 💾    │  │   • websearch       │  │ ProgressTracker     │   │
-│  │   → Progress.clear  │  │   • Librarian 📚   │  │   • grep_search     │  │   .startSession()   │   │
-│  └─────────────────────┘  │   • Researcher 🔬  │  │   • run_background  │  │   .recordSnapshot() │   │
-│                           └─────────────────────┘  └─────────────────────┘  │   .clearSession()   │   │
-│                                                                              └─────────────────────┘   │
-│                                               │                                                        │
-│                                               ▼                                                        │
-│  ┌─────────────────────────────────────────────────────────────────────────────────────────────────┐  │
-│  │                                                                                                  │  │
-│  │                               PARENT SESSION (Main Execution Loop)                              │  │
-│  │                                                                                                  │  │
-│  │   ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐  │  │
-│  │   │  Commander  │───▶│  Architect  │───▶│   Builder   │───▶│  Inspector  │───▶│  Recorder   │  │  │
-│  │   │     🎯      │    │     🏗️     │    │     🔨      │    │     🔍      │    │     💾      │  │  │
-│  │   │             │    │             │    │             │    │             │    │             │  │  │
-│  │   │ Orchestrate │    │ Decompose   │    │ Implement   │    │ Audit &     │    │ Save        │  │  │
-│  │   │ & delegate  │    │ into tasks  │    │ code        │    │ verify      │    │ context     │  │  │
-│  │   └─────────────┘    └─────────────┘    └──────┬──────┘    └─────────────┘    └─────────────┘  │  │
-│  │                                                │                                                │  │
-│  │                                                │ launch_parallel_agent()                        │  │
-│  │                                                ▼                                                │  │
-│  │   ┌──────────────────────────────────────────────────────────────────────────────────────────┐ │  │
-│  │   │                                                                                           │ │  │
-│  │   │    hooks: "chat.message" / "tool.execute.after" / "handler"                               │ │  │
-│  │   │                                                                                           │ │  │
-│  │   │    chat.message:                                                                          │ │  │
-│  │   │      • Parse /task, /plan slash commands                                                  │ │  │
-│  │   │      • Auto-start session on Commander agent selection                                    │ │  │
-│  │   │      • emit(TASK_EVENTS.STARTED, { taskId, agent })                                       │ │  │
-│  │   │                                                                                           │ │  │
-│  │   │    tool.execute.after:                                                                    │ │  │
-│  │   │      • Check "MISSION COMPLETE" → emit(MISSION_EVENTS.COMPLETE)                           │ │  │
-│  │   │      • Check "/stop" or "/cancel" → emit(TASK_EVENTS.FAILED)                              │ │  │
-│  │   │      • Record ProgressTracker.recordSnapshot()                                             │ │  │
-│  │   │      • Inject CONTINUE_INSTRUCTION → client.session.prompt()                              │ │  │
-│  │   │                                                                                           │ │  │
-│  │   │    handler (event):                                                                       │ │  │
-│  │   │      • session.deleted → cleanup sessions, state, ProgressTracker                         │ │  │
-│  │   │      • Pass to ParallelAgentManager.handleEvent()                                         │ │  │
-│  │   │                                                                                           │ │  │
-│  │   └──────────────────────────────────────────────────────────────────────────────────────────┘ │  │
-│  │                                                                                                  │  │
-│  └─────────────────────────────────────────────────────────────────────────────────────────────────┘  │
-│                                                                                                        │
-└────────────────────────────────────────────────────┬───────────────────────────────────────────────────┘
-                                                     │
-                                                     ▼
-┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
-│                                                                                                        │
-│                            PARALLEL AGENT MANAGER  (src/core/agents/manager.ts)                        │
-│                                                                                                        │
-│   ┌────────────────────────────────────────────────────────────────────────────────────────────────┐  │
-│   │                                   Component Composition                                         │  │
-│   │                                                                                                 │  │
-│   │   ┌───────────────────────┐      ┌───────────────────────┐      ┌───────────────────────┐      │  │
-│   │   │    TaskLauncher       │      │    TaskResumer        │      │    TaskPoller         │      │  │
-│   │   │  (task-launcher.ts)   │      │  (task-resumer.ts)    │      │  (task-poller.ts)     │      │  │
-│   │   │  ─────────────────    │      │  ─────────────────    │      │  ─────────────────    │      │  │
-│   │   │                       │      │                       │      │                       │      │  │
-│   │   │  async launch():      │      │  async resume():      │      │  poll() every 1s:     │      │  │
-│   │   │    1. await acquire() │      │    1. Find task       │      │    1. Get running     │      │  │
-│   │   │    2. session.create()│      │    2. session.message │      │    2. Check events    │      │  │
-│   │   │    3. store.set()     │      │    3. Notify parent   │      │    3. If idle+stable  │      │  │
-│   │   │    4. emit(STARTED)   │      │                       │      │       → completed     │      │  │
-│   │   │    5. session.message │      └───────────────────────┘      │    4. emit(COMPLETED) │      │  │
-│   │   │    6. Start poller    │                                     │    5. scheduleCleanup │      │  │
-│   │   │                       │                                     │                       │      │  │
-│   │   └───────────┬───────────┘                                     └───────────┬───────────┘      │  │
-│   │               │                                                             │                  │  │
-│   │               ▼                                                             ▼                  │  │
-│   │   ┌───────────────────────┐      ┌───────────────────────┐      ┌───────────────────────┐      │  │
-│   │   │    TaskCleaner        │      │    EventHandler       │      │ ConcurrencyController │      │  │
-│   │   │  (task-cleaner.ts)    │      │  (event-handler.ts)   │      │  (concurrency.ts)     │      │  │
-│   │   │  ─────────────────    │      │  ─────────────────    │      │  ─────────────────    │      │  │
-│   │   │                       │      │                       │      │                       │      │  │
-│   │   │  pruneExpiredTasks(): │      │  handle(event):       │      │  acquire(key):        │      │  │
-│   │   │    • TTL > 60min      │      │                       │      │    • limit = 10       │      │  │
-│   │   │    → status=timeout   │      │    session.idle:      │      │    • if < limit       │      │  │
-│   │   │    → release()        │      │      • MIN_STABILITY  │      │      → immediate      │      │  │
-│   │   │    → session.delete() │      │      • validateOutput │      │    • else queue.push  │      │  │
-│   │   │                       │      │      → completed      │      │                       │      │  │
-│   │   │  scheduleCleanup():   │      │      → release()      │      │  release(key):        │      │  │
-│   │   │    • setTimeout 10min │      │      → scheduleClean  │      │    • if queue.length  │      │  │
-│   │   │    → session.delete() │      │                       │      │      → queue.shift()  │      │  │
-│   │   │    → store.delete()   │      │    session.deleted:   │      │      → next()         │      │  │
-│   │   │                       │      │      → release()      │      │    • else count--     │      │  │
-│   │   │  notifyParent():      │      │      → store.delete() │      │                       │      │  │
-│   │   │    → session.prompt() │      │                       │      │  getLimit(key):       │      │  │
-│   │   │                       │      └───────────────────────┘      │    • MAX_TOTAL = 50   │      │  │
-│   │   └───────────────────────┘                                     │    • PER_AGENT = 10   │      │  │
-│   │                                                                 └───────────────────────┘      │  │
-│   └────────────────────────────────────────────────────────────────────────────────────────────────┘  │
-│                                                     │                                                  │
-│                                                     ▼                                                  │
-│   ┌────────────────────────────────────────────────────────────────────────────────────────────────┐  │
-│   │                                                                                                 │  │
-│   │                              TaskStore  (task-store.ts)                                         │  │
-│   │                                                                                                 │  │
-│   │   ┌─────────────────────────┐  ┌─────────────────────────┐  ┌─────────────────────────┐        │  │
-│   │   │   tasks: Map<id, Task>  │  │ pendingByParent: Map    │  │ notifications: Map      │        │  │
-│   │   │   MAX: 1000             │  │ <parentId, Set<taskId>> │  │ <parentId, Task[]>      │        │  │
-│   │   │                         │  │                         │  │ MAX: 100/parent         │        │  │
-│   │   │   set() → auto gc()     │  │ trackPending()          │  │                         │        │  │
-│   │   │   getRunning()          │  │ untrackPending()        │  │ queueNotification()     │        │  │
-│   │   │   getByParent()         │  │ hasPending()            │  │ → FIFO eviction         │        │  │
-│   │   └─────────────────────────┘  └─────────────────────────┘  └─────────────────────────┘        │  │
-│   │                                                                                                 │  │
-│   │   ┌─────────────────────────────────────────────────────────────────────────────────────────┐  │  │
-│   │   │                                                                                          │  │  │
-│   │   │   async gc():                                                                            │  │  │
-│   │   │     • completed > 30min → archiveTasks() → .cache/task-archive/tasks_YYYY-MM-DD.jsonl   │  │  │
-│   │   │     • error/cancelled > 10min → delete                                                  │  │  │
-│   │   │                                                                                          │  │  │
-│   │   └─────────────────────────────────────────────────────────────────────────────────────────┘  │  │
-│   │                                                                                                 │  │
-│   └────────────────────────────────────────────────────────────────────────────────────────────────┘  │
-│                                                     │                                                  │
-│                                                     ▼                                                  │
-│   ┌────────────────────────────────────────────────────────────────────────────────────────────────┐  │
-│   │                                                                                                 │  │
-│   │                           CHILD SESSIONS POOL  (up to 50 concurrent)                            │  │
-│   │                                                                                                 │  │
-│   │   ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │  │
-│   │   │Session 1 │ │Session 2 │ │Session 3 │ │Session 4 │ │Session 5 │ │Session 6 │ │ ... 50   │  │  │
-│   │   │ Builder  │ │Librarian │ │Researcher│ │Inspector │ │ Builder  │ │ Builder  │ │          │  │  │
-│   │   │   🔨     │ │   📚     │ │   🔬     │ │   🔍     │ │   🔨     │ │   🔨     │ │          │  │  │
-│   │   │          │ │          │ │          │ │          │ │          │ │          │ │          │  │  │
-│   │   │ running  │ │ running  │ │completed │ │ running  │ │ error    │ │ pending  │ │          │  │  │
-│   │   └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └──────────┘  │  │
-│   │        │            │            │            │            │            │                      │  │
-│   │        └────────────┴────────────┴────────────┴────────────┴────────────┘                      │  │
-│   │                                         │                                                       │  │
-│   └─────────────────────────────────────────┼───────────────────────────────────────────────────────┘  │
-│                                             │                                                          │
-└─────────────────────────────────────────────┼──────────────────────────────────────────────────────────┘
-                                              │
-                                              ▼
-┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
-│                                                                                                        │
-│                                    EVENT BUS  (src/core/bus/)                                          │
-│                                                                                                        │
-│   ┌────────────────────────────────────────────────────────────────────────────────────────────────┐  │
-│   │                                                                                                 │  │
-│   │                                    Event Types (Pub/Sub)                                        │  │
-│   │                                                                                                 │  │
-│   │   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │  │
-│   │   │task.started │  │task.completed│ │ task.failed │  │session.idle │  │ mission.complete    │  │  │
-│   │   │             │  │             │  │             │  │session.delete│ │ mission.all_complete│  │  │
-│   │   └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────────┬──────────┘  │  │
-│   │          │                │                │                │                    │             │  │
-│   │          └────────────────┴────────────────┴────────────────┴────────────────────┘             │  │
-│   │                                            │                                                    │  │
-│   │                                            ▼                                                    │  │
-│   │   ┌─────────────────────────────────────────────────────────────────────────────────────────┐  │  │
-│   │   │                                    Subscribers                                           │  │  │
-│   │   │                                                                                          │  │  │
-│   │   │   Toast.enableAutoToasts():           EventHandler.handle():                             │  │  │
-│   │   │     • task.started → presets.taskStarted()      • release concurrency                    │  │  │
-│   │   │     • task.completed → presets.taskCompleted()  • cleanup resources                      │  │  │
-│   │   │     • task.failed → presets.taskFailed()                                                │  │  │
-│   │   │     • mission.complete → presets.missionComplete()                                      │  │  │
-│   │   │     • document.cached → presets.documentCached()                                        │  │  │
-│   │   │                                                                                          │  │  │
-│   │   │   Returns: () => void (unsubscribe function for cleanup)                                │  │  │
-│   │   │                                                                                          │  │  │
-│   │   └─────────────────────────────────────────────────────────────────────────────────────────┘  │  │
-│   │                                                                                                 │  │
-│   │   ┌─────────────────────────────────────────────────────────────────────────────────────────┐  │  │
-│   │   │   EventBusImpl:                                                                          │  │  │
-│   │   │     • subscribe(type, handler) → unsubscribe fn                                         │  │  │
-│   │   │     • publish(type, properties) → Event                                                 │  │  │
-│   │   │     • emit(type, properties) → void                                                     │  │  │
-│   │   │     • once(type, handler) → unsubscribe fn                                              │  │  │
-│   │   │     • waitFor(type, timeout) → Promise<Event>                                           │  │  │
-│   │   │     • history: Event[] (max 100, FIFO)                                                  │  │  │
-│   │   └─────────────────────────────────────────────────────────────────────────────────────────┘  │  │
-│   │                                                                                                 │  │
-│   └────────────────────────────────────────────────────────────────────────────────────────────────┘  │
-│                                                                                                        │
-└────────────────────────────────────────────────────┬───────────────────────────────────────────────────┘
-                                                     │
-                                                     ▼
-┌───────────────────────────────────────────────────────────────────────────────────────────────────────┐
-│                                                                                                        │
-│                                        CORE SYSTEMS LAYER                                              │
-│                                                                                                        │
-│   ┌──────────────────────────┐  ┌──────────────────────────┐  ┌──────────────────────────┐            │
-│   │   Progress Tracker       │  │   Auto Recovery          │  │   Document Cache         │            │
-│   │   (src/core/progress/)   │  │   (src/core/recovery/)   │  │   (src/core/cache/)      │            │
-│   │   ──────────────────     │  │   ──────────────────     │  │   ──────────────────     │            │
-│   │                          │  │                          │  │                          │            │
-│   │   startSession(id)       │  │   handleError(context)   │  │   get(filename)          │            │
-│   │   recordSnapshot(id, {   │  │     → match patterns     │  │   set(filename, content) │            │
-│   │     currentStep,         │  │     → return action      │  │   list()                 │            │
-│   │     maxSteps             │  │                          │  │   clear(filename)        │            │
-│   │   })                     │  │   Patterns:              │  │   cleanExpired()         │            │
-│   │   formatCompact(id)      │  │     • rate_limit         │  │                          │            │
-│   │   clearSession(id)       │  │       → retry+backoff    │  │   Storage:               │            │
-│   │                          │  │     • context_overflow   │  │   .cache/docs/*.md       │            │
-│   │   Store:                 │  │       → compact          │  │                          │            │
-│   │   sessions: Map<id,      │  │     • network            │  │                          │            │
-│   │     ProgressSnapshot[]>  │  │       → retry 3x         │  │                          │            │
-│   │   max 100/session        │  │     • parse_error        │  │                          │            │
-│   │                          │  │       → skip             │  │                          │            │
-│   └──────────────────────────┘  └──────────────────────────┘  └──────────────────────────┘            │
-│                                                                                                        │
-│   ┌──────────────────────────┐  ┌──────────────────────────┐  ┌──────────────────────────┐            │
-│   │   Toast Notifier         │  │   Async Queue            │  │   Background Commands    │            │
-│   │   (src/core/notification)│  │   (src/core/queue/)      │  │   (src/core/commands/)   │            │
-│   │   ──────────────────     │  │   ──────────────────     │  │   ──────────────────     │            │
-│   │                          │  │                          │  │                          │            │
-│   │   show({ title, msg })   │  │   workPool(items, fn,    │  │   runBackground(cmd)     │            │
-│   │                          │  │     concurrency)         │  │   checkBackground(id)    │            │
-│   │   presets:               │  │   workPoolWithResults()  │  │   listBackground()       │            │
-│   │     • taskStarted()      │  │   processBatches()       │  │   killBackground(id)     │            │
-│   │     • taskCompleted()    │  │                          │  │                          │            │
-│   │     • taskFailed()       │  │   retryWithBackoff(fn,   │  │   Storage:               │            │
-│   │     • missionComplete()  │  │     maxRetries, delay)   │  │   backgroundJobs: Map    │            │
-│   │     • documentCached()   │  │   withTimeout(fn, ms)    │  │   <id, BackgroundTask>   │            │
-│   │                          │  │   debounceAsync(fn, ms)  │  │                          │            │
-│   │   enableAutoToasts()     │  │                          │  │                          │            │
-│   │   → EventBus.subscribe() │  │   AsyncQueue<T>:         │  │                          │            │
-│   │   → returns disable fn   │  │     async iterator       │  │                          │            │
-│   │                          │  │                          │  │                          │            │
-│   └──────────────────────────┘  └──────────────────────────┘  └──────────────────────────┘            │
-│                                                                                                        │
-│   ┌──────────────────────────┐  ┌──────────────────────────┐  ┌──────────────────────────┐            │
-│   │   Shared Context         │  │   Task Decomposer        │  │   Todo Enforcer          │            │
-│   │   (src/core/session/)    │  │   (src/core/task/)       │  │   (src/core/loop/)       │            │
-│   │   ──────────────────     │  │   ──────────────────     │  │   ──────────────────     │            │
-│   │                          │  │                          │  │                          │            │
-│   │   create(id, parentId)   │  │   create(id, objective)  │  │   parseTodos(data)       │            │
-│   │   get(id)                │  │   addTask(id, {          │  │   getIncompleteCount()   │            │
-│   │   getMerged(id)          │  │     description,         │  │   hasRemainingWork()     │            │
-│   │   → includes parent ctx  │  │     level: 1|2|3,        │  │   getNextPending()       │            │
-│   │                          │  │     parallelGroup?,      │  │   getStats()             │            │
-│   │   addDocument(id, doc)   │  │     dependsOn?           │  │   formatProgress()       │            │
-│   │   addFinding(id, find)   │  │   })                     │  │   isMissionComplete()    │            │
-│   │   addDecision(id, dec)   │  │   updateStatus(id, task) │  │                          │            │
-│   │                          │  │   getNextTasks(id)       │  │   generateContinuation   │            │
-│   │   delete(id)             │  │   getParallelBatch(id)   │  │     Prompt()             │            │
-│   │   getStats(id)           │  │   getSummary(id)         │  │   generateCompletion     │            │
-│   │                          │  │                          │  │     Message()            │            │
-│   └──────────────────────────┘  └──────────────────────────┘  └──────────────────────────┘            │
-│                                                                                                        │
-└───────────────────────────────────────────────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           👤 USER REQUEST                                   │
+│                        OpenCode Terminal / UI                               │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        🔌 ORCHESTRATOR PLUGIN                               │
+│                                                                             │
+│  ┌─────────────────┐  ┌─────────────────────────────────────────────────┐  │
+│  │  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       │  │
+│                       └─────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                      ⚙️ PARALLEL AGENT MANAGER                              │
+│                                                                             │
+│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────────────────────┐   │
+│  │ TaskLauncher │  │  TaskPoller  │  │    ConcurrencyController        │   │
+│  │   launch()   │  │   poll()     │  │    MAX=50, PER_AGENT=10         │   │
+│  └──────────────┘  └──────────────┘  └─────────────────────────────────┘   │
+│                                                                             │
+│  ┌─────────────────────────────────────────────────────────────────────┐   │
+│  │                    TaskStore (MAX: 1000 tasks)                      │   │
+│  │    pending → running → completed/error → archived (disk)            │   │
+│  └─────────────────────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                       🔄 CHILD SESSIONS POOL (up to 50)                     │
+│                                                                             │
+│    Session 1        Session 2        Session 3            Session N         │
+│    Builder 🔨       Librarian 📚     Inspector 🔍         ...               │
+└─────────────────────────────────────────────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           📡 EVENT BUS                                      │
+│                                                                             │
+│    task.started | task.completed | task.failed | session.idle               │
+└─────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ---
 
+
+
 ## 🎯 Key Differentiators
 
 | Capability | OpenCode Orchestrator | Basic Plugins |
@@ -393,16 +184,17 @@ What's the difference between useState and useReducer?
 
 | Tool | Description |
 |------|-------------|
-| `call_agent` | Call another agent synchronously |
-| `launch_parallel_agent` | Start parallel async session |
-| `check_parallel_task` | Check task status |
-| `collect_parallel_results` | Gather completed results |
+| `delegate_task` | Delegate work to subagent (async/sync) |
+| `get_task_result` | Get result from delegated task |
+| `list_tasks` | List all running/completed tasks |
+| `cancel_task` | Cancel a running task |
 | `webfetch` | Fetch URL content as Markdown |
 | `websearch` | Search web (SearXNG → Brave → DuckDuckGo) |
 | `codesearch` | Search open source code patterns |
 | `cache_docs` | Manage cached documentation |
 | `run_background` | Run command in background |
-| `grep_search` / `glob_search` | Fast file search |
+| `check_background` / `list_background` | Monitor background jobs |
+| `grep_search` / `glob_search` / `mgrep` | Fast file search |
 
 ---
 
@@ -423,7 +215,7 @@ What's the difference between useState and useReducer?
 
 ```
 Test Files:  18 passed
-Tests:       211 passed
+Tests:       198 passed
 Duration:    ~4.3s
 ```
 
@@ -437,6 +229,19 @@ npm uninstall -g opencode-orchestrator
 
 ---
 
+## 🔧 Debugging
+
+**Log file location:**
+```bash
+# macOS/Linux
+tail -f /tmp/opencode-orchestrator.log
+
+# Windows
+# C:\Users\<username>\AppData\Local\Temp\opencode-orchestrator.log
+```
+
+---
+
 ## Documentation
 
 - **[System Architecture](docs/SYSTEM_ARCHITECTURE.md)** — Detailed technical docs

package/dist/core/agents/interfaces/launch-input.interface.d.ts

@@ -6,4 +6,5 @@ export interface LaunchInput {
     prompt: string;
     agent: string;
     parentSessionID: string;
+    depth?: number;
 }

package/dist/core/agents/interfaces/parallel-task.interface.d.ts

@@ -16,6 +16,7 @@ export interface ParallelTask {
     error?: string;
     result?: string;
     concurrencyKey?: string;
+    depth: number;
     lastMsgCount?: number;
     stablePolls?: number;
     progress?: TaskProgress;

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

@@ -1,4 +1,7 @@
 /**
  * Debug logger for parallel agent
+ * Logs to both console (when DEBUG=true) and file (always)
+ * Log file location: /tmp/opencode-orchestrator.log (or OS temp dir)
  */
 export declare function log(...args: unknown[]): void;
+export declare function getLogPath(): string;

package/dist/core/orchestrator/index.d.ts

@@ -1,7 +1,6 @@
 /**
- * Session Module - State and Task management
+ * Session Module - State management
  */
 export * from "./types/index.js";
 export * from "./interfaces/index.js";
-export { TaskGraph } from "./task-graph.js";
 export { state } from "./state.js";

package/dist/core/orchestrator/interfaces/index.d.ts

@@ -1,5 +1,4 @@
 /**
  * Session Interfaces Index
  */
-export { Task } from "./task.js";
 export { SessionState } from "./session-state.js";

package/dist/core/orchestrator/interfaces/session-state.d.ts

@@ -1,13 +1,11 @@
 /**
  * SessionState - State for a single orchestration session
  */
-import type { TaskGraph } from "../task-graph.js";
 export interface SessionState {
     enabled: boolean;
     iterations: number;
     taskRetries: Map<string, number>;
     currentTask: string;
-    graph?: TaskGraph;
     anomalyCount: number;
     lastHealthyOutput?: string;
 }

package/dist/core/orchestrator/types/index.d.ts

@@ -2,4 +2,3 @@
  * Orchestrator Types Index
  */
 export { TaskStatus } from "./task-status.js";
-export { TaskType } from "./task-type.js";