From 2ecb011982346698b58b69922652dca6a5cd0ef5 Mon Sep 17 00:00:00 2001 From: Prateek Date: Fri, 13 Feb 2026 18:07:59 +0530 Subject: [PATCH] fix: address all review comments, lint/format, bugbot issues Review fixes: - metadata: sessionId validation to prevent path traversal - event-bus: guard appendFileSync, remove unused import - lifecycle-manager: fix reaction retry counting (track attempts, clear on status transition), allow retry on send failure instead of immediate escalation, detect killed sessions in polling loop, map session.killed to agent-exited reaction - session-manager: validate status against union, clean up runtime and workspace on spawn failure, kill with default plugins when project config is missing Lint/format fixes: - Remove unused imports across all test files - Replace `Function` type with typed callback in tmux tests - Replace require() with dynamic import() in tests - Replace dynamic delete with object spread in metadata - Apply prettier formatting to all files Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 45 +- CLAUDE.orchestrator.md | 38 +- artifacts/architecture-design.md | 212 ++--- artifacts/competitive-research.md | 99 ++- artifacts/implementation-plan.md | 133 +-- eslint.config.js | 9 +- packages/core/src/__tests__/event-bus.test.ts | 72 +- .../src/__tests__/lifecycle-manager.test.ts | 1 - packages/core/src/__tests__/metadata.test.ts | 15 +- .../src/__tests__/session-manager.test.ts | 11 +- packages/core/src/__tests__/tmux.test.ts | 36 +- packages/core/src/config.ts | 34 +- packages/core/src/event-bus.ts | 11 +- packages/core/src/lifecycle-manager.ts | 167 ++-- packages/core/src/metadata.ts | 45 +- packages/core/src/session-manager.ts | 145 ++-- packages/core/src/tmux.ts | 24 +- packages/core/src/types.ts | 8 +- pnpm-lock.yaml | 802 +++++++++++++++++- 19 files changed, 1407 insertions(+), 500 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index fbbb90dd7..5b6447cfc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -22,16 +22,16 @@ An open-source, agent-agnostic system for orchestrating parallel AI coding agent 8 plugin slots — every abstraction is swappable: -| Slot | Interface | Default Plugin | -|------|-----------|---------------| -| Runtime | `Runtime` | tmux | -| Agent | `Agent` | claude-code | -| Workspace | `Workspace` | worktree | -| Tracker | `Tracker` | github | -| SCM | `SCM` | github | -| Notifier | `Notifier` | desktop | -| Terminal | `Terminal` | iterm2 | -| Lifecycle | (core, not pluggable) | — | +| Slot | Interface | Default Plugin | +| --------- | --------------------- | -------------- | +| Runtime | `Runtime` | tmux | +| Agent | `Agent` | claude-code | +| Workspace | `Workspace` | worktree | +| Tracker | `Tracker` | github | +| SCM | `SCM` | github | +| Notifier | `Notifier` | desktop | +| Terminal | `Terminal` | iterm2 | +| Lifecycle | (core, not pluggable) | — | All interfaces are defined in `packages/core/src/types.ts`. **Read this file first** — it is the source of truth for all abstractions. @@ -120,7 +120,7 @@ const { stdout } = await execFileAsync("git", ["branch", "--show-current"], { ti // BAD — shell injection risk import { exec } from "node:child_process"; -exec(`git checkout ${branchName}`); // branchName could contain ; rm -rf / +exec(`git checkout ${branchName}`); // branchName could contain ; rm -rf / ``` ### Error Handling @@ -170,6 +170,7 @@ pnpm test # run all tests ### Before Committing Always run lint and typecheck: + ```bash pnpm lint && pnpm typecheck ``` @@ -187,17 +188,17 @@ Fix any issues before pushing. CI will reject PRs that fail lint or typecheck. The `scripts/` directory contains the original bash scripts that this TypeScript codebase replaces. Use them as behavioral specifications: -| Script | What It Specifies | -|--------|------------------| -| `claude-ao-session` | Session lifecycle (spawn, list, kill, cleanup) | -| `claude-dashboard` | Web dashboard, API, activity detection | -| `claude-batch-spawn` | Batch spawning with duplicate detection | -| `send-to-session` | Smart message delivery (busy detection, wait-for-idle) | -| `claude-status` | JSONL introspection, live branch detection | -| `claude-review-check` | PR review scanning, fix prompt generation | -| `claude-bugbot-fix` | Automated comment detection + fixes | -| `claude-session-status` | Activity classification (working/idle/blocked) | -| `get-claude-session-info` | Agent introspection (session ID, summary extraction) | +| Script | What It Specifies | +| ------------------------- | ------------------------------------------------------ | +| `claude-ao-session` | Session lifecycle (spawn, list, kill, cleanup) | +| `claude-dashboard` | Web dashboard, API, activity detection | +| `claude-batch-spawn` | Batch spawning with duplicate detection | +| `send-to-session` | Smart message delivery (busy detection, wait-for-idle) | +| `claude-status` | JSONL introspection, live branch detection | +| `claude-review-check` | PR review scanning, fix prompt generation | +| `claude-bugbot-fix` | Automated comment detection + fixes | +| `claude-session-status` | Activity classification (working/idle/blocked) | +| `get-claude-session-info` | Agent introspection (session ID, summary extraction) | ## Key Design Decisions diff --git a/CLAUDE.orchestrator.md b/CLAUDE.orchestrator.md index 481ecba47..133132734 100644 --- a/CLAUDE.orchestrator.md +++ b/CLAUDE.orchestrator.md @@ -49,24 +49,25 @@ You are the **orchestrator agent** for the agent-orchestrator project. You manag ## Commands Reference -| Task | Command | -|------|---------| -| **See all sessions** | `~/claude-status` | -| **Batch spawn** | `~/claude-batch-spawn ao AO-1 AO-2 AO-3` | -| **Single spawn** | `~/claude-spawn ao AO-1` | -| **List sessions** | `~/claude-ao-session ls` | -| **Attach** | `~/claude-ao-session attach ao-1` | -| **Kill** | `~/claude-ao-session kill ao-1` | -| **Cleanup** | `~/claude-ao-session cleanup` | -| **Open all tabs** | `~/claude-open-all ao` | -| **PR review fixes** | `~/claude-review-check ao` | -| **Peek at screen** | `tmux capture-pane -t "ao-1" -p -S -30` | -| **Send message** | `~/send-to-session ao-1 "your message"` | +| Task | Command | +| ---------------------- | ------------------------------------------------------------ | +| **See all sessions** | `~/claude-status` | +| **Batch spawn** | `~/claude-batch-spawn ao AO-1 AO-2 AO-3` | +| **Single spawn** | `~/claude-spawn ao AO-1` | +| **List sessions** | `~/claude-ao-session ls` | +| **Attach** | `~/claude-ao-session attach ao-1` | +| **Kill** | `~/claude-ao-session kill ao-1` | +| **Cleanup** | `~/claude-ao-session cleanup` | +| **Open all tabs** | `~/claude-open-all ao` | +| **PR review fixes** | `~/claude-review-check ao` | +| **Peek at screen** | `tmux capture-pane -t "ao-1" -p -S -30` | +| **Send message** | `~/send-to-session ao-1 "your message"` | | **Spawn with context** | `~/claude-spawn-with-context ao AO-1 /tmp/prompt.txt --open` | ## Typical Workflows ### Spawn Work for Linear Tickets + ```bash # 1. Check what's already running ~/claude-status @@ -79,6 +80,7 @@ You are the **orchestrator agent** for the agent-orchestrator project. You manag ``` ### Check Progress + ```bash ~/claude-status # Quick overview ~/claude-ao-session ls # AO sessions only @@ -86,6 +88,7 @@ tmux capture-pane -t "ao-1" -p -S -30 # Peek at session ``` ### Ask a Session to Do Something + ```bash # Short message ~/send-to-session ao-1 "address the unresolved comments on your PR" @@ -98,6 +101,7 @@ PROMPT ``` ### Cleanup + ```bash ~/claude-ao-session cleanup # Kills sessions with merged PRs / completed tickets ~/claude-ao-session kill ao-3 # Kill specific session @@ -106,7 +110,9 @@ PROMPT ## Session Data ### Metadata Files + Each session has a flat file at `~/.ao-sessions/ao-N`: + ``` worktree=/Users/equinox/.worktrees/ao/ao-1 branch=feat/AO-1 @@ -116,6 +122,7 @@ pr=https://github.com/ComposioHQ/agent-orchestrator/pull/5 ``` ### Environment Variables (inside sessions) + - `AO_SESSION` — e.g., `ao-1` - `LINEAR_API_KEY` — required for cleanup to check ticket status @@ -151,6 +158,7 @@ agent-orchestrator/ ## Architecture ### Session Lifecycle + ``` spawn → tmux session created → Claude started → working on ticket ↓ @@ -164,12 +172,15 @@ PR merged → cleanup kills session, archives metadata ``` ### Activity Detection + The dashboard detects if agents are working/idle/exited by: + 1. Checking Claude's JSONL session file modification time and last message type 2. Walking the process tree from tmux pane PID to find `claude` processes 3. Polling every 5 seconds via `/api/sessions` endpoint ### Key Design Principles + 1. **tmux-based** — persistence, detach/attach, scriptability 2. **Flat metadata files** — `key=value` format, easy to parse and update 3. **Worktree isolation** — each session gets its own git worktree @@ -195,6 +206,7 @@ The dashboard detects if agents are working/idle/exited by: ## Linear Integration Create tickets via Rube MCP: + ``` RUBE_SEARCH_TOOLS: queries=[{use_case: "create an issue in Linear"}] diff --git a/artifacts/architecture-design.md b/artifacts/architecture-design.md index e453144ca..971e0ab9b 100644 --- a/artifacts/architecture-design.md +++ b/artifacts/architecture-design.md @@ -1,6 +1,6 @@ # Architecture Design — Agent Orchestrator -*Compiled: 2026-02-13* +_Compiled: 2026-02-13_ ## Core Philosophy @@ -42,18 +42,18 @@ Human only intervenes when notified. Everything else is handled. ## Nomenclature -| Term | Definition | Examples | -|------|-----------|---------| -| **Orchestrator** | The central server that manages everything | The Next.js app | -| **Project** | A configured repository to work on | `my-app`, `backend-api` | -| **Session** | A running agent instance working on a task | `my-app-1`, `my-app-2` | -| **Runtime** | Where/how the session executes | tmux, docker, k8s, process | -| **Agent** | The AI coding tool being used | claude-code, codex, aider | -| **Workspace** | Isolated code copy for a session | git worktree, clone, volume | -| **Tracker** | Issue/task tracking system | github, linear, jira | -| **SCM** | Source code management platform | github, gitlab, bitbucket | -| **Notifier** | Communication/alert channel | slack, discord, desktop, webhook | -| **Terminal** | Human interaction interface | iterm2, web terminal, none | +| Term | Definition | Examples | +| ---------------- | ------------------------------------------ | -------------------------------- | +| **Orchestrator** | The central server that manages everything | The Next.js app | +| **Project** | A configured repository to work on | `my-app`, `backend-api` | +| **Session** | A running agent instance working on a task | `my-app-1`, `my-app-2` | +| **Runtime** | Where/how the session executes | tmux, docker, k8s, process | +| **Agent** | The AI coding tool being used | claude-code, codex, aider | +| **Workspace** | Isolated code copy for a session | git worktree, clone, volume | +| **Tracker** | Issue/task tracking system | github, linear, jira | +| **SCM** | Source code management platform | github, gitlab, bitbucket | +| **Notifier** | Communication/alert channel | slack, discord, desktop, webhook | +| **Terminal** | Human interaction interface | iterm2, web terminal, none | --- @@ -124,23 +124,23 @@ interface Runtime { } ``` -| Implementation | How it works | Best for | -|---------------|-------------|----------| -| `tmux` (default) | tmux sessions + send-keys | Local development, interactive | -| `process` | Child processes + stdin/stdout | Headless, CI/CD, scripting | -| `docker` | Docker containers + exec | Isolation, reproducibility | -| `kubernetes` | K8s pods/jobs | Scale, enterprise | -| `ssh` | SSH to remote + tmux/process | Remote machines | -| `e2b` | E2B SDK (Firecracker microVMs) | Cloud sandboxes | -| `fly` | Fly.io Machines API | Cost-effective cloud | -| `modal` | Modal Sandboxes | GPU, autoscaling | +| Implementation | How it works | Best for | +| ---------------- | ------------------------------ | ------------------------------ | +| `tmux` (default) | tmux sessions + send-keys | Local development, interactive | +| `process` | Child processes + stdin/stdout | Headless, CI/CD, scripting | +| `docker` | Docker containers + exec | Isolation, reproducibility | +| `kubernetes` | K8s pods/jobs | Scale, enterprise | +| `ssh` | SSH to remote + tmux/process | Remote machines | +| `e2b` | E2B SDK (Firecracker microVMs) | Cloud sandboxes | +| `fly` | Fly.io Machines API | Cost-effective cloud | +| `modal` | Modal Sandboxes | GPU, autoscaling | ### 2. Agent — AI coding tool ```typescript interface Agent { readonly name: string; - readonly processName: string; // for detection + readonly processName: string; // for detection // Launch getLaunchCommand(session: SessionConfig, project: ProjectConfig): string; @@ -159,14 +159,14 @@ interface Agent { } ``` -| Implementation | Launch command | Activity detection | -|---------------|---------------|-------------------| +| Implementation | Launch command | Activity detection | +| ----------------------- | --------------------------------------- | -------------------------- | | `claude-code` (default) | `claude --dangerously-skip-permissions` | JSONL mtime + process tree | -| `claude-headless` | `claude -p --output-format stream-json` | stdout parsing | -| `codex` | `codex` | Process detection | -| `aider` | `aider --no-auto-commits` | Process detection | -| `goose` | `goose session` | Process detection | -| `custom` | User-defined command | Configurable | +| `claude-headless` | `claude -p --output-format stream-json` | stdout parsing | +| `codex` | `codex` | Process detection | +| `aider` | `aider --no-auto-commits` | Process detection | +| `goose` | `goose session` | Process detection | +| `custom` | User-defined command | Configurable | ### 3. Workspace — Code isolation @@ -183,12 +183,12 @@ interface Workspace { } ``` -| Implementation | How | Tradeoff | -|---------------|-----|----------| -| `worktree` (default) | `git worktree add` | Fast, shared objects, requires same repo | -| `clone` | `git clone` | Full isolation, slower, more disk | -| `copy` | `cp -r` | No git dependency, heaviest | -| `volume` | Docker/K8s volume mounts | For container runtimes | +| Implementation | How | Tradeoff | +| -------------------- | ------------------------ | ---------------------------------------- | +| `worktree` (default) | `git worktree add` | Fast, shared objects, requires same repo | +| `clone` | `git clone` | Full isolation, slower, more disk | +| `copy` | `cp -r` | No git dependency, heaviest | +| `volume` | Docker/K8s volume mounts | For container runtimes | ### 4. Tracker — Issue/task tracking @@ -209,12 +209,12 @@ interface Tracker { } ``` -| Implementation | API | Auth | -|---------------|-----|------| -| `github` (default) | `gh` CLI | GitHub token | -| `linear` | GraphQL API | Linear API key | -| `jira` | REST API | Jira token | -| `plain` | Local files | None | +| Implementation | API | Auth | +| ------------------ | ----------- | -------------- | +| `github` (default) | `gh` CLI | GitHub token | +| `linear` | GraphQL API | Linear API key | +| `jira` | REST API | Jira token | +| `plain` | Local files | None | ### 5. SCM — Source code platform (PR, CI, Reviews) @@ -244,11 +244,11 @@ interface SCM { } ``` -| Implementation | API | Features | -|---------------|-----|----------| -| `github` (default) | `gh` CLI + REST API | Full PR/CI/review support | -| `gitlab` | REST API | MR/pipeline/review support | -| `bitbucket` | REST API | PR/pipeline support | +| Implementation | API | Features | +| ------------------ | ------------------- | -------------------------- | +| `github` (default) | `gh` CLI + REST API | Full PR/CI/review support | +| `gitlab` | REST API | MR/pipeline/review support | +| `bitbucket` | REST API | PR/pipeline support | ### 6. Notifier — THE PRIMARY INTERFACE @@ -270,19 +270,19 @@ interface Notifier { // Notifications can include actions the human can take directly interface NotifyAction { - label: string; // "Merge PR", "Open Dashboard", "Kill Session" - url?: string; // Deep link to dashboard action - callback?: string; // API endpoint to call + label: string; // "Merge PR", "Open Dashboard", "Kill Session" + url?: string; // Deep link to dashboard action + callback?: string; // API endpoint to call } ``` -| Implementation | Channel | Best for | Actionable? | -|---------------|---------|----------|-------------| -| `desktop` (default) | OS notifications (clickable) | Solo developer | Click → opens dashboard | -| `slack` | Slack messages with buttons | Teams | Buttons → merge, review, kill | -| `discord` | Discord messages | Communities | Links | -| `webhook` | HTTP POST | Custom integrations | Custom | -| `email` | Email digest | Async | Links | +| Implementation | Channel | Best for | Actionable? | +| ------------------- | ---------------------------- | ------------------- | ----------------------------- | +| `desktop` (default) | OS notifications (clickable) | Solo developer | Click → opens dashboard | +| `slack` | Slack messages with buttons | Teams | Buttons → merge, review, kill | +| `discord` | Discord messages | Communities | Links | +| `webhook` | HTTP POST | Custom integrations | Custom | +| `email` | Email digest | Async | Links | **Multiple notifiers can be active simultaneously.** E.g., desktop for immediate alerts + Slack for team visibility + email for daily digest. @@ -300,17 +300,18 @@ interface Terminal { } ``` -| Implementation | How | Platform | -|---------------|-----|----------| -| `auto` (default) | Detect best available | Any | -| `iterm2` | AppleScript API | macOS | -| `web` | xterm.js in browser | Any | -| `tmux-attach` | `tmux attach` in terminal | Any with tmux | -| `none` | Headless | CI/CD | +| Implementation | How | Platform | +| ---------------- | ------------------------- | ------------- | +| `auto` (default) | Detect best available | Any | +| `iterm2` | AppleScript API | macOS | +| `web` | xterm.js in browser | Any | +| `tmux-attach` | `tmux attach` in terminal | Any with tmux | +| `none` | Headless | CI/CD | ### 8. Lifecycle Manager (Core — not pluggable) The Lifecycle Manager is the orchestrator's brain. It: + - Polls SCM + Agent plugins on configurable intervals - Maintains state machine per session - Emits events on state transitions @@ -396,24 +397,24 @@ The orchestrator operates on a simple principle: handle everything you can autom **Tier 1: Auto-handled (human never sees these)** The orchestrator resolves these silently. The human is only notified if auto-resolution fails. -| Event | Auto-Response | Escalation | -|-------|--------------|------------| -| CI failed | Send fix prompt to agent | Notify after 2 failed attempts | -| Review comments | Send "address comments" to agent | Notify if unresolved after 30min | -| Bugbot/linter comments | Send fix prompt to agent | Notify if unresolved after 30min | -| Merge conflicts | Send "rebase" to agent | Notify if unresolved after 15min | +| Event | Auto-Response | Escalation | +| ---------------------- | -------------------------------- | -------------------------------- | +| CI failed | Send fix prompt to agent | Notify after 2 failed attempts | +| Review comments | Send "address comments" to agent | Notify if unresolved after 30min | +| Bugbot/linter comments | Send fix prompt to agent | Notify if unresolved after 30min | +| Merge conflicts | Send "rebase" to agent | Notify if unresolved after 15min | **Tier 2: Notify human (requires human judgment)** These always push a notification. The human's phone buzzes, Slack pings, etc. -| Event | Priority | Notification | -|-------|----------|-------------| -| **Agent needs input** (permission, question, stuck) | URGENT | "Session X needs your input" + deep link | -| **Agent errored** (crashed, unrecoverable) | URGENT | "Session X crashed" + error context | -| **PR ready to merge** (approved + CI green) | ACTION | "PR #42 ready to merge" + merge button | -| **Agent idle too long** (no PR, no progress) | WARNING | "Session X idle for 15min, may need help" | -| **Auto-fix failed** (CI fix failed 2x, comments not addressed) | WARNING | "Session X couldn't resolve CI/review — needs you" | -| **All work complete** | INFO | "All 20 sessions done. 18 PRs merged, 2 need review." | +| Event | Priority | Notification | +| -------------------------------------------------------------- | -------- | ----------------------------------------------------- | +| **Agent needs input** (permission, question, stuck) | URGENT | "Session X needs your input" + deep link | +| **Agent errored** (crashed, unrecoverable) | URGENT | "Session X crashed" + error context | +| **PR ready to merge** (approved + CI green) | ACTION | "PR #42 ready to merge" + merge button | +| **Agent idle too long** (no PR, no progress) | WARNING | "Session X idle for 15min, may need help" | +| **Auto-fix failed** (CI fix failed 2x, comments not addressed) | WARNING | "Session X couldn't resolve CI/review — needs you" | +| **All work complete** | INFO | "All 20 sessions done. 18 PRs merged, 2 need review." | ### Escalation Chains @@ -447,10 +448,10 @@ Different priorities route to different channels: ```yaml notifications: routing: - urgent: [desktop, slack, sms] # Agent stuck, errored, needs input - action: [desktop, slack] # PR ready to merge - warning: [slack] # Auto-fix failed, idle too long - info: [slack] # Summary, all done + urgent: [desktop, slack, sms] # Agent stuck, errored, needs input + action: [desktop, slack] # PR ready to merge + warning: [slack] # Auto-fix failed, idle too long + info: [slack] # Summary, all done ``` ### Reactions (configurable auto-responses) @@ -463,7 +464,7 @@ reactions: action: send-to-agent message: "CI is failing. Run `gh pr checks` to see failures, fix them, and push." retries: 2 - escalate-after: 2 # notify human after 2 failed auto-fix attempts + escalate-after: 2 # notify human after 2 failed auto-fix attempts changes-requested: auto: true @@ -484,7 +485,7 @@ reactions: escalate-after: 15m approved-and-green: - auto: false # require human confirmation by default + auto: false # require human confirmation by default action: notify priority: action message: "PR is ready to merge" @@ -507,10 +508,10 @@ reactions: action: notify priority: info message: "All sessions complete" - include-summary: true # PRs merged, pending, failed + include-summary: true # PRs merged, pending, failed agent-idle-no-pr: - threshold: 30m # working for 30min with no PR + threshold: 30m # working for 30min with no PR action: notify priority: warning message: "Agent has been working for 30min without creating a PR" @@ -543,6 +544,7 @@ projects: ``` Everything else uses sensible defaults: + - Runtime: tmux - Agent: claude-code - Workspace: worktree @@ -555,9 +557,9 @@ Everything else uses sensible defaults: ```yaml # agent-orchestrator.yaml -dataDir: ~/.agent-orchestrator # metadata storage -worktreeDir: ~/.worktrees # workspace root -port: 3000 # web dashboard port +dataDir: ~/.agent-orchestrator # metadata storage +worktreeDir: ~/.worktrees # workspace root +port: 3000 # web dashboard port defaults: runtime: tmux @@ -596,13 +598,13 @@ projects: # Agent-specific config agentConfig: - permissions: skip # --dangerously-skip-permissions + permissions: skip # --dangerously-skip-permissions model: opus # Reaction overrides reactions: approved-and-green: - auto: true # enable auto-merge for this project + auto: true # enable auto-merge for this project # Notification channels notifiers: @@ -634,17 +636,17 @@ reactions: ## Tech Stack -| Segment | Choice | Why | -|---------|--------|-----| -| **Core library** | TypeScript | Shared types across all packages | -| **Web + API** | Next.js 15 (App Router) | SSR + API routes in one process | -| **Styling** | Tailwind CSS | Dark theme, responsive | -| **Real-time** | Server-Sent Events | One-way push, auto-reconnect, simpler than WebSocket | -| **CLI** | TypeScript + Commander.js | Shares types with core | -| **Config** | YAML + Zod validation | Human-readable, type-safe | -| **State** | Flat metadata files + Event log (JSONL) | Stateless orchestrator, crash recovery | -| **Package manager** | pnpm workspaces | Fast, monorepo-native | -| **Distribution** | npm (`npx agent-orchestrator`) | Zero install | +| Segment | Choice | Why | +| ------------------- | --------------------------------------- | ---------------------------------------------------- | +| **Core library** | TypeScript | Shared types across all packages | +| **Web + API** | Next.js 15 (App Router) | SSR + API routes in one process | +| **Styling** | Tailwind CSS | Dark theme, responsive | +| **Real-time** | Server-Sent Events | One-way push, auto-reconnect, simpler than WebSocket | +| **CLI** | TypeScript + Commander.js | Shares types with core | +| **Config** | YAML + Zod validation | Human-readable, type-safe | +| **State** | Flat metadata files + Event log (JSONL) | Stateless orchestrator, crash recovery | +| **Package manager** | pnpm workspaces | Fast, monorepo-native | +| **Distribution** | npm (`npx agent-orchestrator`) | Zero install | ### Why TypeScript Throughout @@ -744,6 +746,7 @@ agent-orchestrator/ ## Implementation Phases ### Phase 1: Foundation (Dog-food ready) + - Monorepo scaffolding - Core types + interfaces - Config loader @@ -758,6 +761,7 @@ agent-orchestrator/ - Reaction engine (CI failed, changes requested, agent stuck) ### Phase 2: Multi-Runtime + More Plugins + - Process runtime (headless claude -p) - Docker runtime - Codex + Aider agent adapters @@ -766,12 +770,14 @@ agent-orchestrator/ - Web terminal (xterm.js) ### Phase 3: Cloud + Scale + - Kubernetes runtime - E2B / Fly.io runtimes - Cost tracking - Webhook-triggered spawning ### Phase 4: Team + Enterprise + - Dashboard auth - Role-based access - Remote session support diff --git a/artifacts/competitive-research.md b/artifacts/competitive-research.md index f0e166e8f..981cb2ef4 100644 --- a/artifacts/competitive-research.md +++ b/artifacts/competitive-research.md @@ -1,6 +1,6 @@ # Competitive Research — Agent Orchestration Tools -*Compiled: 2026-02-13* +_Compiled: 2026-02-13_ ## Overview @@ -18,26 +18,27 @@ Research into 16+ projects that orchestrate AI coding agents. The goal: understa **Architecture — MEOW Stack (Molecular Expression of Work):** -| Layer | What | How | -|-------|------|-----| -| **Beads** | Atomic work units | JSONL files tracked in Git. IDs like `gt-abc12`. Universal data/control plane. | -| **Epics** | Hierarchical collections | Organize beads into tree structures for parallel/sequential execution | -| **Molecules** | Workflow graphs | Sequenced beads with dependencies, gates, loops | -| **Protomolecules & Formulas** | Reusable templates | TOML format workflow definitions | +| Layer | What | How | +| ----------------------------- | ------------------------ | ------------------------------------------------------------------------------ | +| **Beads** | Atomic work units | JSONL files tracked in Git. IDs like `gt-abc12`. Universal data/control plane. | +| **Epics** | Hierarchical collections | Organize beads into tree structures for parallel/sequential execution | +| **Molecules** | Workflow graphs | Sequenced beads with dependencies, gates, loops | +| **Protomolecules & Formulas** | Reusable templates | TOML format workflow definitions | **Agent Roles (7 roles, 2 scopes):** -| Role | Scope | Purpose | -|------|-------|---------| -| **Mayor** | Town | Chief AI coordinator with full workspace context | -| **Deacon** | Town | Health daemon running patrol loops | -| **Dogs** | Town | Maintenance helpers | -| **Crew** | Rig | Named, persistent agents for sustained design/review work | -| **Polecats** | Rig | Ephemeral "cattle" workers spawned for specific tasks | -| **Refinery** | Rig | Merge queue manager handling conflicts | -| **Witness** | Rig | Supervises polecats, unblocks stuck work | +| Role | Scope | Purpose | +| ------------ | ----- | --------------------------------------------------------- | +| **Mayor** | Town | Chief AI coordinator with full workspace context | +| **Deacon** | Town | Health daemon running patrol loops | +| **Dogs** | Town | Maintenance helpers | +| **Crew** | Rig | Named, persistent agents for sustained design/review work | +| **Polecats** | Rig | Ephemeral "cattle" workers spawned for specific tasks | +| **Refinery** | Rig | Merge queue manager handling conflicts | +| **Witness** | Rig | Supervises polecats, unblocks stuck work | **Other Abstractions:** + - **Town** — Workspace directory (`~/gt/`) housing all projects - **Rigs** — Project containers wrapping git repositories - **Hooks** — Git worktree-based persistent storage surviving crashes @@ -47,6 +48,7 @@ Research into 16+ projects that orchestrate AI coding agents. The goal: understa **Runtime Backends:** claude, gemini, codex, cursor, auggie, amp (per-rig config) **Communication/Isolation:** + - Git worktrees for filesystem isolation per agent - Beads/Hooks for coordination (external state, not shared context windows) - GUPP: deterministic handoffs through version control, not LLM-judged phase gates @@ -63,12 +65,14 @@ Research into 16+ projects that orchestrate AI coding agents. The goal: understa - **Closest to our current approach** **Key Abstractions:** + - **Sessions**: Single-repo isolated branches via git worktrees + tmux sessions - **Workspaces**: Multi-repo synchronized development contexts - **Control Center**: Unified tmux session with windows for each context - **Labels**: Globally unique, human-readable names **Features:** + - `par start my-feature` — creates worktree + branch + tmux session - `par send