@viberlabs/orchestrator

Agent orchestration layer for VIBER Labs / VIBER v2 - ORCA State Machine, Agent Pool, and Workflows

Installation

npm install @viberlabs/orchestrator

Features

ORCA State Machine (@viberlabs/orchestrator/orca)

XState v5 state machine for orchestrating agent execution.

import { createOrcaMachine, Orca } from '@viberlabs/orchestrator/orca';
import { ViberDatabase } from '@viberlabs/viber-core/db';
import { FllEngine } from '@viberlabs/viber-core/engine';

const db = new ViberDatabase('.viber/state.db');
const fll = new FllEngine();

const orca = new Orca(db, fll);

// Start orchestration
await orca.start({
  taskId: 'task-1',
  projectId: 'project-1'
});

// Monitor state
orca.onStateChange((state) => {
  console.log('State:', state.value);
  console.log('Context:', state.context);
});

States:

• idle - Waiting for task
• validating - FLL validation in progress
• orchestrating - Planning agent sequence
• executing - Agents running
• reviewing - Reviewing results
• completed - Task finished
• failed - Task failed

Agent Pool (@viberlabs/orchestrator/pool)

Manages concurrent AI agents with maximum concurrency.

import { AgentPool } from '@viberlabs/orchestrator/pool';
import { OpenCodeClient } from '@viberlabs/opencode';

const client = new OpenCodeClient({
  baseUrl: 'http://localhost:51262',
  username: 'opencode',
  password: 'your-password'
});

const pool = new AgentPool({
  maxConcurrent: 3,
  opencodeClient: client,
  db: db
});

// Spawn agent
const agentId = await pool.spawnAgent({
  taskId: 'task-1',
  role: 'coder',
  model: 'claude-3-opus'
});

// Monitor status
const status = pool.getAgentStatus(agentId);

// Complete agent
pool.completeAgent(agentId);

Workflows (@viberlabs/orchestrator/workflow)

Multi-agent workflow patterns.

import { WorkflowExecutor } from '@viberlabs/orchestrator/workflow';

const executor = new WorkflowExecutor({
  opencodeClient: client,
  db: db
});

// Sequential workflow
const results = await executor.executeSequential([
  { role: 'planner', task: 'Create implementation plan' },
  { role: 'coder', task: 'Implement the feature' },
  { role: 'reviewer', task: 'Review the code' }
]);

// Parallel workflow
const results = await executor.executeParallel([
  { role: 'coder', task: 'Implement feature A' },
  { role: 'coder', task: 'Implement feature B' },
  { role: 'coder', task: 'Implement feature C' }
]);

// Pipeline workflow
const results = await executor.executePipeline([
  { role: 'planner', task: 'Plan architecture' },
  { role: 'coder', task: 'Implement from plan' },
  { role: 'tester', task: 'Test implementation' }
]);

// Use workflow template
const results = await executor.executeTemplate('plan-implement-test', {
  task: 'Build user authentication',
  context: { feature: 'JWT auth' }
});

Workflow Templates

Built-in workflow templates:

• implement-review - Coder → Reviewer
• plan-implement - Planner → Coder
• plan-implement-test - Planner → Coder → Tester
• full-cycle - Planner → Coder → Reviewer → Tester

Agent Roles

Supported agent roles:

• planner - Strategic analysis and planning
• coder - Implementation and coding
• reviewer - Code review and quality assurance
• tester - Testing and validation

Architecture

User (CEO)
  ↓
ORCA (State Machine)
  ↓ Validates task with FLL
  ↓ Plans agent sequence
  ↓ Spawns agents via Pool
Agent Pool
  ↓ Manages concurrency (max 3)
  ↓ Tracks agent lifecycle
  ↓ Captures results
Agents (via OpenCode API)
  ↓ Execute tasks headlessly
  ↓ Report results
Workflow Executor
  ↓ Sequential, Parallel, Pipeline patterns
  ↓ Result aggregation

License

MIT

Links

• GitHub Repository
• Documentation
• Issues