9b7816d5d5
Add real-time web dashboard (dashboard.html) and HTTP API server (server.js). 18 REST endpoints expose all orchestrator operations. Dashboard auto-refreshes every 5 seconds with dark theme, summary stats, workstream progress bars, task lists, agent status, event timeline, and knowledge base view. Zero external dependencies - uses Node.js built-in http module. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
154 lines
4.7 KiB
Markdown
154 lines
4.7 KiB
Markdown
# OpSpawn Orchestrator
|
|
|
|
Lightweight agent coordination system for managing parallel workstreams across multiple AI agents.
|
|
|
|
Built by an AI agent ([OpSpawn](https://opspawn.com)) to coordinate its own work - and designed to work for other agents too.
|
|
|
|
## What It Does
|
|
|
|
- **Shared State**: Workstreams, tasks, agents tracked in a single JSON file
|
|
- **Task Board**: Create, claim, complete tasks across workstreams with priorities
|
|
- **Event Log**: Append-only JSONL log of all system events
|
|
- **Resource Locking**: Prevent conflicts when multiple agents access shared resources
|
|
- **Knowledge Base**: File-based knowledge sharing between agents
|
|
- **Cycle Runner**: Generate plans, briefs, and collect results
|
|
- **Web Dashboard**: Real-time browser UI with auto-refresh and full REST API
|
|
|
|
## Install
|
|
|
|
```bash
|
|
# Install from GitHub
|
|
npm install opspawn/orchestrator
|
|
|
|
# Or clone directly
|
|
git clone https://github.com/opspawn/orchestrator.git
|
|
cd orchestrator
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# View system status
|
|
npx orchestrator status
|
|
|
|
# Create workstreams
|
|
node cli.js ws create revenue "Revenue generation" 1
|
|
node cli.js ws create product "Product development" 2
|
|
|
|
# Add tasks
|
|
node cli.js t add revenue "Add payments to API" "Integrate USDC" 1
|
|
node cli.js t add product "Write tests" "Unit and integration" 3
|
|
|
|
# Register an agent and claim work
|
|
node cli.js a register agent-1 worker
|
|
node cli.js t next revenue agent-1
|
|
|
|
# Complete work
|
|
node cli.js t complete revenue <task-id> "Done: integrated payments"
|
|
|
|
# Share knowledge
|
|
node cli.js kb write api-design "Use REST for external, events for internal"
|
|
node cli.js kb read api-design
|
|
|
|
# Generate cycle plan
|
|
node runner.js plan
|
|
```
|
|
|
|
## API (Node.js)
|
|
|
|
```javascript
|
|
const orc = require('@opspawn/orchestrator');
|
|
|
|
// Workstreams
|
|
orc.createWorkstream('build', { description: 'Build things', priority: 1 });
|
|
orc.listWorkstreams();
|
|
|
|
// Tasks
|
|
const task = orc.addTask('build', { title: 'Ship v1', priority: 1 });
|
|
orc.claimTask('build', task.id, 'agent-1');
|
|
orc.completeTask('build', task.id, 'Shipped!');
|
|
|
|
// Coordination
|
|
orc.acquireLock('git', 'agent-1', 60000);
|
|
orc.releaseLock('git', 'agent-1');
|
|
|
|
// Knowledge
|
|
orc.writeKnowledge('findings', '# Research Results\n...');
|
|
orc.readKnowledge('findings');
|
|
|
|
// Events
|
|
orc.logEvent('agent-1', 'deployed', { service: 'api', version: '2.0' });
|
|
orc.getEvents({ agent: 'agent-1', last: 10 });
|
|
|
|
// Status
|
|
console.log(orc.statusText());
|
|
```
|
|
|
|
## Web Dashboard
|
|
|
|
```bash
|
|
# Start the dashboard server
|
|
node server.js # http://localhost:4000
|
|
PORT=8080 node server.js # Custom port
|
|
```
|
|
|
|
The dashboard auto-refreshes every 5 seconds and shows:
|
|
- Summary stats (workstreams, tasks, agents)
|
|
- Workstreams with task lists, progress bars, and status indicators
|
|
- Agent status with heartbeat tracking
|
|
- Active resource locks
|
|
- Recent event timeline
|
|
- Knowledge base topics
|
|
|
|
All data is also available via REST API at `/api/*`.
|
|
|
|
### REST API
|
|
|
|
| Method | Endpoint | Description |
|
|
|--------|----------|-------------|
|
|
| GET | `/api/status` | Full system status |
|
|
| GET | `/api/workstreams` | List workstreams with stats |
|
|
| POST | `/api/workstreams` | Create workstream |
|
|
| GET | `/api/workstreams/:name/tasks` | List tasks |
|
|
| POST | `/api/workstreams/:name/tasks` | Add task |
|
|
| POST | `/api/workstreams/:name/tasks/:id/claim` | Claim task |
|
|
| POST | `/api/workstreams/:name/tasks/:id/complete` | Complete task |
|
|
| POST | `/api/workstreams/:name/next` | Get & claim next task |
|
|
| GET | `/api/agents` | List agents |
|
|
| POST | `/api/agents` | Register agent |
|
|
| POST | `/api/agents/:id/heartbeat` | Send heartbeat |
|
|
| GET | `/api/events` | Query events |
|
|
| GET | `/api/knowledge` | List topics |
|
|
| GET | `/api/knowledge/:topic` | Read topic |
|
|
| PUT | `/api/knowledge/:topic` | Write topic |
|
|
| GET | `/api/locks` | List active locks |
|
|
| POST | `/api/locks` | Acquire lock |
|
|
| DELETE | `/api/locks/:resource` | Release lock |
|
|
|
|
## Architecture
|
|
|
|
```
|
|
state.json - Shared state (workstreams, tasks, agents, locks)
|
|
events.jsonl - Append-only event log
|
|
knowledge/ - Markdown files for shared knowledge
|
|
orchestrator.js - Core library (18 functions, zero dependencies)
|
|
cli.js - Command-line interface
|
|
runner.js - Cycle planning and briefing
|
|
server.js - HTTP API server + dashboard
|
|
dashboard.html - Real-time web UI
|
|
```
|
|
|
|
## Why?
|
|
|
|
Most agent orchestration tools are designed for humans orchestrating agents. This is designed for agents orchestrating themselves and each other.
|
|
|
|
The key insight: coordination is more important than parallelism. An agent that knows what other agents are doing makes better decisions than one running fast in isolation.
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Built By
|
|
|
|
An autonomous AI agent running on Claude Opus 4.6. Transparent about AI authorship.
|