Package Exports

opencode-orchestrator

Readme

OpenCode Orchestrator

Production-Grade Multi-Agent Orchestration Engine for High-Integrity Software Engineering

Version: 1.2.67

⚡ Quick Start

npm install -g opencode-orchestrator

Install hooks are source-checkout safe, prefer opencode.jsonc when present, preserve sibling plugin entries, and skip automatic config mutation in CI environments.

Inside an OpenCode environment:

/task "Implement a new authentication module with JWT and audit logs"

🚀 Engine Workflow

Hub-and-Spoke Architecture with Work-Stealing Queues for parallel, context-isolated task execution.

╔══════════════════════════════════════════════════════════════════════════════╗
║                           USER INPUT /task "..."                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
                                         │
                                         ▼
╔══════════════════════════════════════════════════════════════════════════════╗
║  ┌─────────────────────────────────────────────────────────────────────────┐ ║
║  │                            C O M M A N D E R                           │ ║
║  │                    [ Mission Analysis & Delegation ]                    │ ║
║  │                                                                          │ ║
║  │    • Interprets user intent    • Coordinates multi-agent workflow      │ ║
║  │    • Monitors progress          • Manages work-stealing queues         │ ║
║  └─────────────────────────────────────────────────────────────────────────┘ ║
╚══════════════════════════════════════════════════════════════════════════════╝
                                         │
                         ┌───────────────┼───────────────┐
                         ▼               ▼               ▼
╔═════════════════╗  ╔═════════════════╗  ╔═════════════════╗
║   P L A N N E R ║  ║     W O R K E R ║  ║    W O R K E R   ║
║  [Architect]    ║  ║  [Implementer]  ║  ║  [Implementer]   ║
║                 ║  ║                 ║  ║                 ║
║  • Dependency   ║  ║  • File coding ║  ║  • File coding  ║
║    analysis     ║  ║  • TDD workflow ║  ║  • TDD workflow ║
║  • Roadmap gen ║  ║  • Documentation║  ║  • Documentation║
║  • TODO.md      ║  ║                 ║  ║                 ║
╚═════════════════╝  ╚═════════════════╝  ╚═════════════════╝
         │                   │                     │
         │    ┌──────────────┼─────────────────────┘
         │    │              │
         ▼    ▼              ▼
╔══════════════════════════════════════╗
║         SESSION POOL (MVCC Sync)   ║
║   ┌─────────────────────────────────┐ ║
║   │  Object Pool │ Buffer Pool      │ ║
║   │  String Pool │ Connection Pool  │ ║
║   └─────────────────────────────────┘ ║
╚══════════════════════════════════════╝
         │
         ▼
╔══════════════════════════════════════╗
║       MSVP MONITOR / REVIEWER       ║
║  ┌─────────────────────────────────┐ ║
║  │  • Adaptive polling (500ms-5s) │ ║
║  │  • Stability detection         │ ║
║  │  • Unit test verification      │ ║
║  └─────────────────────────────────┘ ║
╚══════════════════════════════════════╝
                 │
                 ▼
        ┌────────────────┐
        │  ✨ COMPLETED  │
        └────────────────┘

🏗️ Architecture Layers

┌─────────────────────────────────────────────────────────────────────────────┐
│                           PRESENTATION LAYER                                │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  │
│  │ Task Toast  │  │ Progress    │  │ Notification│  │ Mission Summary │  │
│  │ Manager     │  │ Notifier    │  │ Manager     │  │ Display         │  │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────────┘  │
├─────────────────────────────────────────────────────────────────────────────┤
│                           BUSINESS LOGIC LAYER                              │
│  ┌───────────────────────────────────────────────────────────────────────┐  │
│  │                    Parallel Agent Orchestration                        │  │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────────┐  │  │
│  │  │ Commander  │  │  Planner   │  │  Worker    │  │   Reviewer     │  │  │
│  │  │   Agent    │  │   Agent    │  │   Agent    │  │     Agent      │  │  │
│  │  └────────────┘  └────────────┘  └────────────┘  └────────────────┘  │  │
│  └───────────────────────────────────────────────────────────────────────┘  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────────┐│
│  │ Concurrency     │  │   Task Store   │  │    Hook System              ││
│  │ Controller      │  │   (In-Memory)  │  │  [Early/Normal/Late Phases] ││
│  └─────────────────┘  └─────────────────┘  └─────────────────────────────┘│
├─────────────────────────────────────────────────────────────────────────────┤
│                           INFRASTRUCTURE LAYER                              │
│  ┌────────────────┐  ┌────────────────┐  ┌────────────────────────────┐  │
│  │ Session Pool   │  │ Work-Stealing  │  │    Memory Pools           │  │
│  │ [5 per agent]  │  │ [Chase-Lev]    │  │  ┌──────┐ ┌──────┐ ┌─────┐│  │
│  │ [10 reuse max] │  │ [LIFO/FIFO]    │  │  │Object│ │String│ │Buffer││  │
│  └────────────────┘  └────────────────┘  │  │ 200  │ │ intern│ │ 4KB ││  │
│                                          │  └──────┘ └──────┘ └─────┘│  │
│  ┌────────────────┐  ┌────────────────┐  └────────────────────────────┘  │
│  │ MVCC State     │  │ Circuit Breaker │  ┌────────────────────────────┐  │
│  │ [Atomic Sync]  │  │ [5 failures→open│  │ Rust Connection Pool     │  │
│  │                │  │  [2 success→close│ │ [4 processes, 30s idle]   │  │
│  └────────────────┘  └────────────────┘  └────────────────────────────┘  │
├─────────────────────────────────────────────────────────────────────────────┤
│                           SAFETY LAYER                                      │
│  ┌────────────────┐  ┌────────────────┐  ┌─────────────────────────────┐ │
│  │ RAII Pattern   │  │ Shutdown       │  │ Auto-Recovery               │ │
│  │ [Zero Leaks]   │  │ Manager        │  │ [Exponential Backoff]       │ │
│  │                │  │ [5s timeout]   │  │ [Rate limit handling]       │ │
│  └────────────────┘  └────────────────┘  └─────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

🧪 Test Utilities

Reusable test helpers keep filesystem, task, and process-heavy flows deterministic:

tests/harness/
├── fixture.ts          Disposable tmpdir utilities
│   ├── tmpdir()        async disposable with cleanup
│   ├── tmpdirSync()    sync disposable with cleanup  
│   ├── createMockFs()  In-memory fs mock
│   └── waitFor()       Async condition waiter
│
├── builders.ts         Factory functions for test objects
│   ├── createParallelTask()    Build ParallelTask instances
│   ├── createBackgroundTask()  Build BackgroundTask instances
│   └── createTodo()            Build Todo instances
│
├── mocks.ts           Mock utilities
│   ├── mockConsole()         Spy on console.log/error
│   ├── mockProcessExit()     Mock process.exit
│   ├── useFakeTimers()       Time manipulation
│   └── createMockEmitter()   EventEmitter spy
│
└── index.ts           Unified exports

Usage Example

import { tmpdir, createParallelTask, mockConsole } from "@/tests/harness";

describe("My test", () => {
  let consoleMock;

  beforeEach(() => {
    consoleMock = mockConsole();
    consoleMock.setup();
  });

  afterEach(() => {
    consoleMock.restore();
  });

  it("should work", async () => {
    await using tmp = await tmpdir({ git: true });
    const task = createParallelTask({ description: "Test" });
    expect(task.status).toBe("pending");
  });
});

⚡ Elite Multi-Agent Swarm

Agent	Role	Core Responsibilities
Commander	Mission Hub	Task decomposition, agent coordination, work-stealing orchestration, final mission seal
Planner	Architect	Dependency analysis, roadmap generation, TODO.md creation via MVCC, file-level planning
Worker	Implementer	High-throughput coding, TDD workflow, documentation, isolated file execution
Reviewer	Auditor	Unit test verification, LSP/Lint validation, integration testing, quality gate

🛠️ Core Capabilities

🔒 Atomic MVCC State Synchronization

Solves the "Concurrent TODO Update" problem using MVCC + Mutex. Agents safely mark tasks complete in parallel without data loss or race conditions. Every state change is cryptographically hashed and logged.

🧩 Advanced Hook Orchestration

Execution flows governed by a Priority-Phase Hook Registry. Hooks are grouped into phases (early, normal, late) and executed via Topological Sort for predictable, dependency-aware ordering.

🛡️ Autonomous Recovery

Self-healing loops with adaptive stagnation detection
Proactive Agency: Smart monitoring that audits logs and plans ahead during background tasks
Auto-retry with backoff: Exponential backoff for transient failures

🎯 State-Level Session Isolation

Reused sessions in the SessionPool are explicitly reset via server-side compaction, ensuring previous task context never leaks into new tasks.

🚀 Zero-Payload Turbo Mode

Leverages system.transform to unshift agent instruction sets server-side, reducing initial message payloads by 90%+ and preventing context fragmentation.

🧠 Hierarchical Memory System

Maintains focus across thousands of conversation turns using a 4-tier memory structure with EMA-based Context Gating to preserve architectural truth while pruning noise.

🔄 Adaptive Intelligence Loop

Stagnation Detection: Senses when no progress is made across iterations
Diagnostic Intervention: Forces "Diagnostic Mode" mandating log audits and strategy pivots
Proactive Agency: Mandates Speculative Planning during background task execution

⚙️ Performance Benchmarks

Metric	Improvement
CPU Utilization	90%+ (up from 50-70%)
Tool Call Speed	10x faster (5-10ms vs 50-100ms) via Rust pool
Session Creation	90% faster (50ms vs 500ms) via session pooling
Memory Usage	60% reduction via object/string/buffer pooling
GC Pressure	80% reduction
Token Efficiency	40% reduction via Incremental State & System Transform
Sync Accuracy	99.95% via MVCC+Mutex
Parallel Efficiency	80% improvement (50% → 90%+)

🏗️ Infrastructure & Reliability

Resource Safety

RAII Pattern: Guaranteed resource cleanup with zero leaks
ShutdownManager: Priority-based graceful shutdown (5s timeout per handler)
Atomic File Operations: Temp file + rename for corruption-proof writes
Automatic Backups: Timestamped config backups with rollback support

Safety Features

Circuit Breaker: Auto-recovery from API failures (5 failures → open)
Resource Pressure Detection: Rejects low-priority tasks when memory > 80%
Terminal Node Guard: Prevents infinite recursion via depth limit
Auto-Scaling: Concurrency slots adjust based on success/failure rate

Technical Stack

Runtime: Node.js 18+ (TypeScript)
Tools: Rust-based CLI tools (grep, glob, ast) via connection pool
Concurrency: Chase-Lev work-stealing deque + priority queues
Memory: Object pooling + string interning + buffer pooling
State Management: MVCC + Mutex
Safety: RAII + circuit breaker + resource pressure detection

🔧 Installation & Configuration

Safe Installation

The installation process is production-safe with multiple protection layers:

✅ Never overwrites — always merges with existing config
✅ Automatic backups — timestamped, last 5 kept
✅ Atomic writes — temp file + rename (OS-level atomic)
✅ Automatic rollback — restores from backup on any failure
✅ Cross-platform — Windows (native, Git Bash, WSL2), macOS, Linux
✅ CI-aware — skips non-essential operations in CI environments
✅ Timeout protection — 30s timeout prevents hanging
✅ Graceful degradation — exits 0 on non-critical failures

Configuration Logs

Unix: /tmp/opencode-orchestrator.log
Windows: %TEMP%\opencode-orchestrator.log

🧪 Testing & Stability

Test Utilities

Reusable helpers under tests/harness/ provide:

Disposable tmpdir: Automatic cleanup with Symbol.asyncDispose / Symbol.dispose
Test builders: Factory functions for ParallelTask, BackgroundTask, Todo
Mock utilities: Console, process, timers, file system, event emitter mocks

import { tmpdir, createParallelTask, mockConsole } from "@/tests/harness";

await using tmp = await tmpdir({ git: true });
const task = createParallelTask({ description: "Test" });

TUI Stability

Cleanup guarantees: initToastClient() returns a cleanup function
Timeout protection: AbortController-based 2-10s timeout for async toast operations
Error isolation: Try/catch around all toast operations prevents cascade failures

Cross-Platform Reliability

Windows guard: Proper handling of WSL2, Git Bash, native Windows paths
Signal handling: Graceful shutdown on SIGINT/SIGTERM
Process isolation: Child process cleanup with timeout

📚 Documentation

📄 License

MIT License — see LICENSE for details.

_{Built with ⚡ for production-grade autonomous software engineering}