fix: dashboard config discovery + CLI service layer refactoring (#70)
* fix: config discovery, activity detection, and metadata port storage - findConfigFile() checks AO_CONFIG_PATH env var (resolved to absolute path) - loadConfig() delegates to findConfigFile() for consistent validation - Pure Node.js readLastJsonlEntry (no external tail binary), safe for multi-byte UTF-8 at chunk boundaries - Added "ready" activity state to agent plugins - Store dashboardPort, terminalWsPort, directTerminalWsPort in session metadata so ao stop targets the correct processes - Zod schema port default aligned with TypeScript interface Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: dashboard config discovery + CLI service layer refactoring - Config discovery via AO_CONFIG_PATH env var - Auto port detection with PortManager - Activity detection with ready state, pure Node.js readLastLine - 5 CLI services: ConfigService, PortManager, DashboardManager, MetadataService, ProcessManager - Store all service ports in metadata for ao stop - Set NEXT_PUBLIC_ env vars for frontend terminal components - Multi-byte UTF-8 safe readLastJsonlEntry - Tests for all new services and utils Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: address bugbot review comments (port fallback + systemPrompt) 1. Align port fallback to 3000 everywhere (matching Zod schema default): - start.ts: config.port ?? 3000 - dashboard.ts: config.port ?? 3000 - types.ts JSDoc: "defaults to 3000" - orchestrator-prompt.ts: already correct at 3000 2. Add --append-system-prompt to Claude Code plugin's getLaunchCommand so orchestrator context is actually passed to the Claude agent. Previously systemPrompt was generated but silently dropped. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: remove dead ConfigService mock from status test The vi.mock for ConfigService.js referenced a deleted module. Config mocking is already handled by the @composio/ao-core mock. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: extract shared buildDashboardEnv to eliminate duplication Dashboard env construction (AO_CONFIG_PATH, PORT, NEXT_PUBLIC_*) was duplicated between start.ts and dashboard.ts. Extracted into buildDashboardEnv() in web-dir.ts (already shared by both commands). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
prateek
GitHub
parent
b75c6b04ea
commit
59c490a3af
|
|
@ -0,0 +1,55 @@
|
|||
name: Onboarding Integration Test
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- 'packages/**'
|
||||
- 'scripts/setup.sh'
|
||||
- 'tests/integration/**'
|
||||
- '.github/workflows/onboarding-test.yml'
|
||||
push:
|
||||
branches:
|
||||
- main
|
||||
|
||||
jobs:
|
||||
onboarding-test:
|
||||
name: Test Fresh Onboarding
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
|
||||
steps:
|
||||
- name: Checkout repository
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Set up Docker Buildx
|
||||
uses: docker/setup-buildx-action@v3
|
||||
|
||||
- name: Build test image
|
||||
working-directory: tests/integration
|
||||
run: docker compose build
|
||||
|
||||
- name: Run onboarding test
|
||||
id: test
|
||||
working-directory: tests/integration
|
||||
run: |
|
||||
docker compose up --abort-on-container-exit --exit-code-from onboarding-test
|
||||
|
||||
- name: Extract metrics
|
||||
if: always()
|
||||
run: |
|
||||
# Extract onboarding time from container logs
|
||||
docker logs ao-onboarding-test 2>&1 | grep "Total onboarding time" || echo "Metrics not available"
|
||||
|
||||
- name: Cleanup
|
||||
if: always()
|
||||
working-directory: tests/integration
|
||||
run: docker compose down -v
|
||||
|
||||
- name: Upload test logs
|
||||
if: failure()
|
||||
uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: onboarding-test-logs
|
||||
path: |
|
||||
tests/integration/*.log
|
||||
retention-days: 7
|
||||
|
|
@ -1,5 +1,6 @@
|
|||
node_modules/
|
||||
dist/
|
||||
.pnpm-store/
|
||||
.next/
|
||||
*.tsbuildinfo
|
||||
coverage/
|
||||
|
|
|
|||
|
|
@ -1,48 +1,68 @@
|
|||
# Orchestrator Agent — Agent Orchestrator
|
||||
# CLAUDE.orchestrator.md - Agent Orchestrator
|
||||
|
||||
You are the **orchestrator agent** for the agent-orchestrator project. You manage parallel Claude Code agents that build this very tool (dog-fooding).
|
||||
|
||||
## Your Role
|
||||
## Project Info
|
||||
|
||||
You plan, delegate, and monitor — you do NOT implement. Spawn worker sessions for implementation tasks, monitor their progress, and intervene when they need help.
|
||||
|
||||
## Project
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Repo | ComposioHQ/agent-orchestrator (GitHub) |
|
||||
| Issue Tracker | Linear (AO team) |
|
||||
| Default Branch | `main` |
|
||||
| Session Prefix | `ao` |
|
||||
| Session Naming | `ao-1`, `ao-2`, etc. |
|
||||
- **Repo**: ComposioHQ/agent-orchestrator (GitHub)
|
||||
- **Issue Tracker**: Linear (AO team)
|
||||
- **Main Branch**: `main`
|
||||
- **Session Prefix**: `ao`
|
||||
- **Session Naming**: `ao-1`, `ao-2`, etc.
|
||||
- **Metadata Dir**: `~/.ao-sessions/`
|
||||
- **Worktrees**: `~/.worktrees/ao/`
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
ao status # See all sessions
|
||||
ao spawn ao AO-1 # Spawn one session for a Linear ticket
|
||||
ao batch-spawn ao AO-1 AO-2 AO-3 # Spawn multiple
|
||||
ao send ao-1 "fix the CI failure" # Send message to worker
|
||||
ao session ls -p ao # List sessions
|
||||
ao session cleanup -p ao # Remove merged sessions
|
||||
ao open ao # Open all in terminal tabs
|
||||
# See all sessions
|
||||
~/claude-status
|
||||
|
||||
# Spawn sessions for Linear tickets
|
||||
~/claude-batch-spawn ao AO-1 AO-2 AO-3
|
||||
|
||||
# Spawn single session (new iTerm2 tab)
|
||||
~/claude-spawn ao AO-1
|
||||
|
||||
# List ao sessions
|
||||
~/claude-ao-session ls
|
||||
|
||||
# Attach to a session
|
||||
~/claude-ao-session attach ao-1
|
||||
|
||||
# Kill a session
|
||||
~/claude-ao-session kill ao-1
|
||||
|
||||
# Cleanup completed work (merged PRs / done tickets)
|
||||
~/claude-ao-session cleanup
|
||||
```
|
||||
|
||||
## Key Commands
|
||||
## Agent Hierarchy
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| See all sessions | `ao status` |
|
||||
| Batch spawn | `ao batch-spawn ao AO-1 AO-2 AO-3` |
|
||||
| Single spawn | `ao spawn ao AO-1` |
|
||||
| List sessions | `ao session ls -p ao` |
|
||||
| Kill session | `ao session kill ao-3` |
|
||||
| Cleanup | `ao session cleanup -p ao` |
|
||||
| Send message | `ao send ao-1 "your message"` |
|
||||
| Open all tabs | `ao open ao` |
|
||||
| PR review fixes | `ao review-check ao` |
|
||||
| Peek at screen | `tmux capture-pane -t "ao-1" -p -S -30` |
|
||||
| Status as JSON | `ao status --json` |
|
||||
```
|
||||
~/agent-orchestrator/ <- YOU (Orchestrator)
|
||||
└── ao agents <- Managed via ~/claude-ao-session
|
||||
├── ao-1 (~/.worktrees/ao/ao-1)
|
||||
├── ao-2 (~/.worktrees/ao/ao-2)
|
||||
└── ao-N
|
||||
```
|
||||
|
||||
## 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"` |
|
||||
| **Spawn with context** | `~/claude-spawn-with-context ao AO-1 /tmp/prompt.txt --open` |
|
||||
|
||||
## Typical Workflows
|
||||
|
||||
|
|
@ -50,92 +70,138 @@ ao open ao # Open all in terminal tabs
|
|||
|
||||
```bash
|
||||
# 1. Check what's already running
|
||||
ao status
|
||||
~/claude-status
|
||||
|
||||
# 2. Spawn sessions (auto-deduplicates)
|
||||
ao batch-spawn ao AO-1 AO-2 AO-3
|
||||
~/claude-batch-spawn ao AO-1 AO-2 AO-3
|
||||
|
||||
# 3. Open all in terminal
|
||||
ao open ao
|
||||
# 3. Open all in iTerm2
|
||||
~/claude-open-all ao
|
||||
```
|
||||
|
||||
### Check Progress
|
||||
|
||||
```bash
|
||||
ao status # Full dashboard
|
||||
ao session ls -p ao # Quick list
|
||||
tmux capture-pane -t "ao-1" -p -S -30 # Peek at session
|
||||
~/claude-status # Quick overview
|
||||
~/claude-ao-session ls # AO sessions only
|
||||
tmux capture-pane -t "ao-1" -p -S -30 # Peek at session
|
||||
```
|
||||
|
||||
### Ask a Session to Do Something
|
||||
|
||||
```bash
|
||||
# Short message
|
||||
ao send ao-1 "address the unresolved comments on your PR"
|
||||
~/send-to-session ao-1 "address the unresolved comments on your PR"
|
||||
|
||||
# Long instructions from file
|
||||
ao send ao-1 -f /tmp/detailed-instructions.txt
|
||||
```
|
||||
|
||||
### Handle PR Reviews
|
||||
|
||||
```bash
|
||||
# Automatic: scan all PRs and trigger agents to fix
|
||||
ao review-check ao
|
||||
|
||||
# Manual: send targeted instruction
|
||||
ao send ao-2 "address the review comments on your PR"
|
||||
# Long prompt via file
|
||||
cat > /tmp/prompt.txt << 'PROMPT'
|
||||
Your detailed instructions here...
|
||||
PROMPT
|
||||
~/claude-spawn-with-context ao AO-1 /tmp/prompt.txt --open
|
||||
```
|
||||
|
||||
### Cleanup
|
||||
|
||||
```bash
|
||||
ao session cleanup -p ao --dry-run # Preview what would be killed
|
||||
ao session cleanup -p ao # Actually clean up
|
||||
ao session kill ao-3 # Kill specific session
|
||||
~/claude-ao-session cleanup # Kills sessions with merged PRs / completed tickets
|
||||
~/claude-ao-session kill ao-3 # Kill specific session
|
||||
```
|
||||
|
||||
## Session Lifecycle
|
||||
## Session Data
|
||||
|
||||
### Metadata Files
|
||||
|
||||
Each session has a flat file at `~/.ao-sessions/ao-N`:
|
||||
|
||||
```
|
||||
ao spawn ao AO-123
|
||||
|
|
||||
v
|
||||
[Worktree created from origin/main]
|
||||
|
|
||||
v
|
||||
[Feature branch: feat/AO-123]
|
||||
|
|
||||
v
|
||||
[tmux session: ao-N, agent launched with issue context]
|
||||
|
|
||||
v
|
||||
[Agent works: implement -> test -> PR -> push]
|
||||
|
|
||||
v
|
||||
[ao status shows PR/CI/review state]
|
||||
|
|
||||
v
|
||||
[PR merged] --> ao session cleanup removes session
|
||||
worktree=/Users/equinox/.worktrees/ao/ao-1
|
||||
branch=feat/AO-1
|
||||
status=starting
|
||||
issue=https://linear.app/composio/issue/AO-1
|
||||
pr=https://github.com/ComposioHQ/agent-orchestrator/pull/5
|
||||
```
|
||||
|
||||
## How to Behave
|
||||
### Environment Variables (inside sessions)
|
||||
|
||||
### Always Do
|
||||
- `AO_SESSION` — e.g., `ao-1`
|
||||
- `LINEAR_API_KEY` — required for cleanup to check ticket status
|
||||
|
||||
1. **Check before spawning** — Run `ao status` first. Never spawn duplicates.
|
||||
2. **Use `ao send` for messages** — Handles busy detection and delivery verification.
|
||||
3. **Delegate, don't duplicate** — Send short instructions. Workers have `gh`, git, and full repo access.
|
||||
4. **Batch when possible** — `ao batch-spawn` has built-in duplicate detection.
|
||||
5. **Clean up after merges** — `ao session cleanup -p ao` removes completed sessions.
|
||||
## Repo Structure
|
||||
|
||||
### Never Do
|
||||
```
|
||||
agent-orchestrator/
|
||||
├── scripts/ # All orchestrator scripts
|
||||
│ ├── claude-ao-session # Session manager for this project
|
||||
│ ├── claude-status # Unified CLI dashboard
|
||||
│ ├── claude-batch-spawn # Spawn multiple sessions
|
||||
│ ├── claude-spawn # Spawn single session (new tab)
|
||||
│ ├── claude-dashboard # HTML dashboard with live PR status
|
||||
│ ├── claude-open-all # Open iTerm2 tabs for sessions
|
||||
│ ├── claude-review-check # Trigger PR review fixes
|
||||
│ ├── claude-bugbot-fix # Fix bugbot comments
|
||||
│ ├── claude-session-status # Health monitor
|
||||
│ ├── claude-spawn-with-context # Spawn with custom prompt file
|
||||
│ ├── claude-spawn-on-branch # Spawn on existing branch
|
||||
│ ├── claude-spawn-with-prompt # Spawn + deliver prompt after ready
|
||||
│ ├── get-claude-session-info # Extract session metadata from tmux
|
||||
│ ├── open-tmux-session # Switch to terminal tab
|
||||
│ ├── open-iterm-tab # iTerm2 tab management
|
||||
│ ├── notify-session # iTerm2 notifications
|
||||
│ ├── send-to-session # Smart message delivery to sessions
|
||||
│ ├── claude-integrator-session # Example: Linear-based session manager
|
||||
│ └── claude-splitly-session # Example: GitHub Issues session manager
|
||||
├── CLAUDE.orchestrator.md # This file (orchestrator instructions)
|
||||
├── CLAUDE.md # Repo instructions for contributors
|
||||
└── README.md # Project README
|
||||
```
|
||||
|
||||
1. **Never write code** — Spawn a worker session for any implementation task.
|
||||
2. **Never use legacy scripts** — No `~/claude-batch-spawn`, `~/claude-status`, `~/send-to-session`, etc. Use `ao` CLI.
|
||||
3. **Never use raw tmux** — Don't `tmux send-keys` directly. Use `ao send`.
|
||||
4. **Never spawn for trivial tasks** — Answer questions directly. Only spawn for implementation.
|
||||
5. **Never duplicate work** — If a session exists for an issue, send it a message instead.
|
||||
## Architecture
|
||||
|
||||
### Session Lifecycle
|
||||
|
||||
```
|
||||
spawn → tmux session created → Claude started → working on ticket
|
||||
↓
|
||||
metadata file written (branch, issue, status)
|
||||
↓
|
||||
agent creates PR → metadata updated (pr=URL)
|
||||
↓
|
||||
dashboard shows PR status, CI, review state
|
||||
↓
|
||||
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
|
||||
4. **Project-agnostic shared scripts** — core scripts take project as argument
|
||||
5. **Project-specific session managers** — each project gets its own (e.g., `claude-ao-session`)
|
||||
|
||||
## Roadmap
|
||||
|
||||
1. **Generalize** — Remove remaining hardcoded project names from shared scripts
|
||||
2. **Configuration** — `orchestrator.yaml` defining projects, repos, branches, issue trackers
|
||||
3. **Installation** — Install script that symlinks scripts to `~/` or adds to PATH
|
||||
4. **Documentation** — Comprehensive README with setup guide and examples
|
||||
5. **Terminal-agnostic** — Replace iTerm2 AppleScript with generic terminal support
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Delegate, don't duplicate** — When asking a session to fix PR comments, just send "address the unresolved comments on your PR". The session has `gh` access.
|
||||
2. **Check before spawning** — `~/claude-status` to avoid duplicate sessions.
|
||||
3. **Detach, don't kill** — `Ctrl-b d` detaches from tmux. Session keeps running.
|
||||
4. **Peek without attaching** — `tmux capture-pane -t "ao-1" -p -S -30`
|
||||
5. **Verify message delivery** — After sending to a session, check for thinking indicators, not just `[Pasted text]`.
|
||||
|
||||
## Linear Integration
|
||||
|
||||
|
|
|
|||
10
SETUP.md
10
SETUP.md
|
|
@ -102,7 +102,7 @@ The wizard will prompt you for:
|
|||
|
||||
1. **Data directory** - Where to store session metadata (default: `~/.agent-orchestrator`)
|
||||
2. **Worktree directory** - Where to create isolated workspaces (default: `~/.worktrees`)
|
||||
3. **Dashboard port** - Web interface port (default: `3000`)
|
||||
3. **Dashboard port** - Web interface port (default: `9847`)
|
||||
4. **Runtime plugin** - Session runtime (default: `tmux`)
|
||||
5. **Agent plugin** - AI coding assistant (default: `claude-code`)
|
||||
6. **Workspace plugin** - Workspace isolation method (default: `worktree`)
|
||||
|
|
@ -148,7 +148,7 @@ The absolute minimum needed:
|
|||
```yaml
|
||||
dataDir: ~/.agent-orchestrator
|
||||
worktreeDir: ~/.worktrees
|
||||
port: 3000
|
||||
port: 9847
|
||||
|
||||
projects:
|
||||
my-app:
|
||||
|
|
@ -439,7 +439,7 @@ echo $LINEAR_API_KEY
|
|||
|
||||
### "Port 3000 already in use"
|
||||
|
||||
**Problem:** Another service is using port 3000.
|
||||
**Problem:** Another service is using port 9847.
|
||||
|
||||
**Solution:**
|
||||
|
||||
|
|
@ -447,7 +447,7 @@ echo $LINEAR_API_KEY
|
|||
# Change port in agent-orchestrator.yaml
|
||||
port: 3001
|
||||
|
||||
# Or find and kill the process using port 3000
|
||||
# Or find and kill the process using port 9847
|
||||
lsof -ti:3000 | xargs kill
|
||||
```
|
||||
|
||||
|
|
@ -730,7 +730,7 @@ projects:
|
|||
|
||||
Three ways:
|
||||
|
||||
1. **Dashboard** - `ao start` then visit http://localhost:3000
|
||||
1. **Dashboard** - `ao start` then visit http://localhost:9847
|
||||
2. **CLI status** - `ao status` (text-based dashboard)
|
||||
3. **Attach to session** - `ao open <session-name>` (live terminal)
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,6 @@
|
|||
|
||||
dataDir: ~/.ao-sessions
|
||||
worktreeDir: ~/.worktrees/ao
|
||||
port: 3000
|
||||
|
||||
defaults:
|
||||
runtime: tmux
|
||||
|
|
|
|||
|
|
@ -3,7 +3,6 @@
|
|||
|
||||
dataDir: ~/.agent-orchestrator
|
||||
worktreeDir: ~/.worktrees
|
||||
port: 3000
|
||||
|
||||
projects:
|
||||
my-app:
|
||||
|
|
|
|||
|
|
@ -3,7 +3,6 @@
|
|||
|
||||
dataDir: ~/.agent-orchestrator
|
||||
worktreeDir: ~/.worktrees
|
||||
port: 3000
|
||||
|
||||
defaults:
|
||||
agent: codex # Use Codex instead of Claude Code
|
||||
|
|
|
|||
|
|
@ -3,7 +3,6 @@
|
|||
|
||||
dataDir: ~/.agent-orchestrator
|
||||
worktreeDir: ~/.worktrees
|
||||
port: 3000
|
||||
|
||||
projects:
|
||||
my-app:
|
||||
|
|
|
|||
|
|
@ -3,7 +3,6 @@
|
|||
|
||||
dataDir: ~/.agent-orchestrator
|
||||
worktreeDir: ~/.worktrees
|
||||
port: 3000
|
||||
|
||||
defaults:
|
||||
runtime: tmux
|
||||
|
|
|
|||
|
|
@ -3,7 +3,6 @@
|
|||
|
||||
dataDir: ~/.agent-orchestrator
|
||||
worktreeDir: ~/.worktrees
|
||||
port: 3000
|
||||
|
||||
projects:
|
||||
my-app:
|
||||
|
|
|
|||
|
|
@ -1,243 +0,0 @@
|
|||
import { describe, it, expect, beforeEach, afterEach } from "vitest";
|
||||
import {
|
||||
mkdtempSync,
|
||||
mkdirSync,
|
||||
writeFileSync,
|
||||
existsSync,
|
||||
readFileSync,
|
||||
readdirSync,
|
||||
rmSync,
|
||||
} from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { tmpdir } from "node:os";
|
||||
import {
|
||||
readMetadata,
|
||||
writeMetadata,
|
||||
archiveMetadata,
|
||||
listSessionFiles,
|
||||
findSessionForIssue,
|
||||
} from "../../src/lib/metadata.js";
|
||||
|
||||
let tmpDir: string;
|
||||
|
||||
beforeEach(() => {
|
||||
tmpDir = mkdtempSync(join(tmpdir(), "ao-test-"));
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
describe("readMetadata", () => {
|
||||
it("returns null for non-existent file", () => {
|
||||
expect(readMetadata(join(tmpDir, "nonexistent"))).toBeNull();
|
||||
});
|
||||
|
||||
it("parses key=value format", () => {
|
||||
const file = join(tmpDir, "session-1");
|
||||
writeFileSync(
|
||||
file,
|
||||
"worktree=/home/user/.worktrees/app/session-1\nbranch=feat/INT-123\nstatus=working\nissue=INT-123\n",
|
||||
);
|
||||
const meta = readMetadata(file);
|
||||
expect(meta).not.toBeNull();
|
||||
expect(meta!.worktree).toBe("/home/user/.worktrees/app/session-1");
|
||||
expect(meta!.branch).toBe("feat/INT-123");
|
||||
expect(meta!.status).toBe("working");
|
||||
expect(meta!.issue).toBe("INT-123");
|
||||
});
|
||||
|
||||
it("handles values containing equals signs", () => {
|
||||
const file = join(tmpDir, "session-2");
|
||||
writeFileSync(file, "summary=key=value pair in desc\n");
|
||||
const meta = readMetadata(file);
|
||||
expect(meta).not.toBeNull();
|
||||
expect(meta!.summary).toBe("key=value pair in desc");
|
||||
});
|
||||
|
||||
it("ignores empty lines", () => {
|
||||
const file = join(tmpDir, "session-3");
|
||||
writeFileSync(file, "branch=main\n\nstatus=idle\n\n");
|
||||
const meta = readMetadata(file);
|
||||
expect(meta!.branch).toBe("main");
|
||||
expect(meta!.status).toBe("idle");
|
||||
});
|
||||
|
||||
it("handles PR URLs with embedded numbers", () => {
|
||||
const file = join(tmpDir, "session-4");
|
||||
writeFileSync(file, "pr=https://github.com/org/repo/pull/42\nbranch=feat/fix\n");
|
||||
const meta = readMetadata(file);
|
||||
expect(meta!.pr).toBe("https://github.com/org/repo/pull/42");
|
||||
});
|
||||
});
|
||||
|
||||
describe("writeMetadata", () => {
|
||||
it("creates metadata file with key=value pairs", () => {
|
||||
const file = join(tmpDir, "subdir", "session-1");
|
||||
writeMetadata(file, {
|
||||
worktree: "/path/to/worktree",
|
||||
branch: "feat/test",
|
||||
status: "starting",
|
||||
});
|
||||
expect(existsSync(file)).toBe(true);
|
||||
const content = readFileSync(file, "utf-8");
|
||||
expect(content).toContain("worktree=/path/to/worktree\n");
|
||||
expect(content).toContain("branch=feat/test\n");
|
||||
expect(content).toContain("status=starting\n");
|
||||
});
|
||||
|
||||
it("skips undefined and null values", () => {
|
||||
const file = join(tmpDir, "session-2");
|
||||
writeMetadata(file, {
|
||||
branch: "main",
|
||||
status: "working",
|
||||
pr: undefined,
|
||||
issue: undefined,
|
||||
});
|
||||
const content = readFileSync(file, "utf-8");
|
||||
expect(content).not.toContain("pr=");
|
||||
expect(content).not.toContain("issue=");
|
||||
expect(content).toContain("branch=main");
|
||||
});
|
||||
|
||||
it("creates parent directories if needed", () => {
|
||||
const file = join(tmpDir, "deep", "nested", "dir", "session-1");
|
||||
writeMetadata(file, { branch: "main", status: "idle" });
|
||||
expect(existsSync(file)).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("archiveMetadata", () => {
|
||||
it("moves metadata to archive dir with timestamp", () => {
|
||||
const sessionDir = join(tmpDir, "sessions");
|
||||
mkdirSync(sessionDir, { recursive: true });
|
||||
writeFileSync(join(sessionDir, "app-1"), "branch=main\n");
|
||||
|
||||
archiveMetadata(sessionDir, "app-1");
|
||||
|
||||
expect(existsSync(join(sessionDir, "app-1"))).toBe(false);
|
||||
const archiveDir = join(sessionDir, "archive");
|
||||
expect(existsSync(archiveDir)).toBe(true);
|
||||
const archived = readdirSync(archiveDir);
|
||||
expect(archived.length).toBe(1);
|
||||
expect(archived[0]).toMatch(/^app-1_\d{4}-\d{2}-\d{2}T/);
|
||||
});
|
||||
|
||||
it("does nothing for non-existent metadata", () => {
|
||||
archiveMetadata(join(tmpDir, "sessions"), "nonexistent");
|
||||
// Should not throw
|
||||
});
|
||||
});
|
||||
|
||||
describe("listSessionFiles", () => {
|
||||
it("returns empty array for non-existent directory", async () => {
|
||||
const result = await listSessionFiles(join(tmpDir, "nonexistent"));
|
||||
expect(result).toEqual([]);
|
||||
});
|
||||
|
||||
it("returns session files, excluding dotfiles and archive", async () => {
|
||||
const sessionDir = join(tmpDir, "sessions");
|
||||
mkdirSync(sessionDir);
|
||||
mkdirSync(join(sessionDir, "archive"));
|
||||
writeFileSync(join(sessionDir, "app-1"), "");
|
||||
writeFileSync(join(sessionDir, "app-2"), "");
|
||||
writeFileSync(join(sessionDir, ".hidden"), "");
|
||||
|
||||
const result = await listSessionFiles(sessionDir);
|
||||
expect(result.sort()).toEqual(["app-1", "app-2"]);
|
||||
});
|
||||
});
|
||||
|
||||
describe("findSessionForIssue", () => {
|
||||
it("finds session by issue ID match", async () => {
|
||||
const sessionDir = join(tmpDir, "sessions");
|
||||
mkdirSync(sessionDir);
|
||||
writeFileSync(join(sessionDir, "app-1"), "branch=feat/INT-100\nissue=INT-100\n");
|
||||
writeFileSync(join(sessionDir, "app-2"), "branch=feat/INT-200\nissue=INT-200\n");
|
||||
|
||||
const result = await findSessionForIssue(sessionDir, "INT-200", ["app-1", "app-2"]);
|
||||
expect(result).toBe("app-2");
|
||||
});
|
||||
|
||||
it("returns null when no match found", async () => {
|
||||
const sessionDir = join(tmpDir, "sessions");
|
||||
mkdirSync(sessionDir);
|
||||
writeFileSync(join(sessionDir, "app-1"), "branch=main\nissue=INT-100\n");
|
||||
|
||||
const result = await findSessionForIssue(sessionDir, "INT-999", ["app-1"]);
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("is case-insensitive", async () => {
|
||||
const sessionDir = join(tmpDir, "sessions");
|
||||
mkdirSync(sessionDir);
|
||||
writeFileSync(join(sessionDir, "app-1"), "issue=int-100\n");
|
||||
|
||||
const result = await findSessionForIssue(sessionDir, "INT-100", ["app-1"]);
|
||||
expect(result).toBe("app-1");
|
||||
});
|
||||
|
||||
it("only matches sessions that are in the tmux list", async () => {
|
||||
const sessionDir = join(tmpDir, "sessions");
|
||||
mkdirSync(sessionDir);
|
||||
writeFileSync(join(sessionDir, "app-1"), "issue=INT-100\n");
|
||||
writeFileSync(join(sessionDir, "app-2"), "issue=INT-200\n");
|
||||
|
||||
// app-2 is NOT in tmux sessions list
|
||||
const result = await findSessionForIssue(sessionDir, "INT-200", ["app-1"]);
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("filters by project when projectId is specified", async () => {
|
||||
const sessionDir = join(tmpDir, "sessions");
|
||||
mkdirSync(sessionDir);
|
||||
// Project A has INT-100
|
||||
writeFileSync(join(sessionDir, "app-1"), "issue=INT-100\nproject=project-a\n");
|
||||
// Project B also has INT-100 (different session)
|
||||
writeFileSync(join(sessionDir, "backend-1"), "issue=INT-100\nproject=project-b\n");
|
||||
|
||||
// Should only find project-a's session
|
||||
const resultA = await findSessionForIssue(
|
||||
sessionDir,
|
||||
"INT-100",
|
||||
["app-1", "backend-1"],
|
||||
"project-a",
|
||||
);
|
||||
expect(resultA).toBe("app-1");
|
||||
|
||||
// Should only find project-b's session
|
||||
const resultB = await findSessionForIssue(
|
||||
sessionDir,
|
||||
"INT-100",
|
||||
["app-1", "backend-1"],
|
||||
"project-b",
|
||||
);
|
||||
expect(resultB).toBe("backend-1");
|
||||
|
||||
// Without projectId filter, should find first match
|
||||
const resultAny = await findSessionForIssue(sessionDir, "INT-100", ["app-1", "backend-1"]);
|
||||
expect(resultAny).toBe("app-1");
|
||||
});
|
||||
|
||||
it("excludes sessions without project field when projectId filter is specified", async () => {
|
||||
const sessionDir = join(tmpDir, "sessions");
|
||||
mkdirSync(sessionDir);
|
||||
// Legacy session without project field
|
||||
writeFileSync(join(sessionDir, "legacy-1"), "issue=INT-100\n");
|
||||
// Current session with project field
|
||||
writeFileSync(join(sessionDir, "app-1"), "issue=INT-100\nproject=project-a\n");
|
||||
|
||||
// Should NOT find legacy session when filtering by project
|
||||
const result = await findSessionForIssue(
|
||||
sessionDir,
|
||||
"INT-100",
|
||||
["legacy-1", "app-1"],
|
||||
"project-a",
|
||||
);
|
||||
expect(result).toBe("app-1");
|
||||
|
||||
// Without projectId filter, should find one of the sessions (order not guaranteed)
|
||||
const resultAny = await findSessionForIssue(sessionDir, "INT-100", ["legacy-1", "app-1"]);
|
||||
expect(["legacy-1", "app-1"]).toContain(resultAny);
|
||||
});
|
||||
});
|
||||
|
|
@ -4,7 +4,7 @@ import { existsSync } from "node:fs";
|
|||
import chalk from "chalk";
|
||||
import type { Command } from "commander";
|
||||
import { loadConfig } from "@composio/ao-core";
|
||||
import { findWebDir } from "../lib/web-dir.js";
|
||||
import { findWebDir, buildDashboardEnv } from "../lib/web-dir.js";
|
||||
import { cleanNextCache, findRunningDashboardPid, findProcessWebDir, waitForPortFree } from "../lib/dashboard-rebuild.js";
|
||||
|
||||
export function registerDashboard(program: Command): void {
|
||||
|
|
@ -16,7 +16,7 @@ export function registerDashboard(program: Command): void {
|
|||
.option("--rebuild", "Clean stale build artifacts and rebuild before starting")
|
||||
.action(async (opts: { port?: string; open?: boolean; rebuild?: boolean }) => {
|
||||
const config = loadConfig();
|
||||
const port = opts.port ? parseInt(opts.port, 10) : config.port;
|
||||
const port = opts.port ? parseInt(opts.port, 10) : (config.port ?? 3000);
|
||||
|
||||
if (isNaN(port) || port < 1 || port > 65535) {
|
||||
console.error(chalk.red("Invalid port number. Must be 1-65535."));
|
||||
|
|
@ -62,9 +62,12 @@ export function registerDashboard(program: Command): void {
|
|||
|
||||
console.log(chalk.bold(`Starting dashboard on http://localhost:${port}\n`));
|
||||
|
||||
const env = buildDashboardEnv(port, config.configPath);
|
||||
|
||||
const child = spawn("npx", ["next", "dev", "-p", String(port)], {
|
||||
cwd: webDir,
|
||||
stdio: ["inherit", "inherit", "pipe"],
|
||||
env,
|
||||
});
|
||||
|
||||
const stderrChunks: string[] = [];
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ import {
|
|||
} from "@composio/ao-core";
|
||||
import { exec, getTmuxSessions } from "../lib/shell.js";
|
||||
import { getAgent } from "../lib/plugins.js";
|
||||
import { findWebDir } from "../lib/web-dir.js";
|
||||
import { findWebDir, buildDashboardEnv } from "../lib/web-dir.js";
|
||||
import { cleanNextCache } from "../lib/dashboard-rebuild.js";
|
||||
|
||||
/**
|
||||
|
|
@ -71,15 +71,20 @@ function resolveProject(
|
|||
* Start dashboard server in the background.
|
||||
* Returns the child process handle for cleanup.
|
||||
*/
|
||||
function startDashboard(port: number, webDir: string): ChildProcess {
|
||||
const child = spawn("npx", ["next", "dev", "-p", String(port)], {
|
||||
function startDashboard(port: number, webDir: string, configPath: string | null): ChildProcess {
|
||||
const env = buildDashboardEnv(port, configPath);
|
||||
|
||||
const child = spawn("pnpm", ["run", "dev"], {
|
||||
cwd: webDir,
|
||||
stdio: "inherit",
|
||||
detached: false,
|
||||
env,
|
||||
});
|
||||
|
||||
child.on("error", (err) => {
|
||||
console.error(chalk.red("Dashboard failed to start:"), err);
|
||||
console.error(chalk.red("Dashboard failed to start:"), err.message);
|
||||
// Emit synthetic exit so callers listening on "exit" can clean up
|
||||
child.emit("exit", 1, null);
|
||||
});
|
||||
|
||||
return child;
|
||||
|
|
@ -131,7 +136,7 @@ export function registerStart(program: Command): void {
|
|||
const config = loadConfig();
|
||||
const { projectId, project } = resolveProject(config, projectArg);
|
||||
const sessionId = `${project.sessionPrefix}-orchestrator`;
|
||||
const port = config.port;
|
||||
const port = config.port ?? 3000;
|
||||
|
||||
console.log(chalk.bold(`\nStarting orchestrator for ${chalk.cyan(project.name)}\n`));
|
||||
|
||||
|
|
@ -151,7 +156,7 @@ export function registerStart(program: Command): void {
|
|||
}
|
||||
|
||||
spinner.start("Starting dashboard");
|
||||
dashboardProcess = startDashboard(port, webDir);
|
||||
dashboardProcess = startDashboard(port, webDir, config.configPath);
|
||||
spinner.succeed(`Dashboard starting on http://localhost:${port}`);
|
||||
console.log(chalk.dim(" (Dashboard will be ready in a few seconds)\n"));
|
||||
}
|
||||
|
|
@ -317,7 +322,7 @@ export function registerStop(program: Command): void {
|
|||
const config = loadConfig();
|
||||
const { projectId: _projectId, project } = resolveProject(config, projectArg);
|
||||
const sessionId = `${project.sessionPrefix}-orchestrator`;
|
||||
const port = config.port;
|
||||
const port = config.port ?? 3000;
|
||||
const sessionsDir = getSessionsDir(config.configPath, project.path);
|
||||
|
||||
console.log(chalk.bold(`\nStopping orchestrator for ${chalk.cyan(project.name)}\n`));
|
||||
|
|
|
|||
|
|
@ -1,62 +0,0 @@
|
|||
import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from "node:fs";
|
||||
import { readdir } from "node:fs/promises";
|
||||
import { join, basename } from "node:path";
|
||||
import type { SessionMetadata } from "@composio/ao-core";
|
||||
|
||||
export function readMetadata(filePath: string): Partial<SessionMetadata> | null {
|
||||
if (!existsSync(filePath)) return null;
|
||||
const content = readFileSync(filePath, "utf-8");
|
||||
const meta: Record<string, string> = {};
|
||||
for (const line of content.split("\n")) {
|
||||
const eq = line.indexOf("=");
|
||||
if (eq > 0) {
|
||||
meta[line.slice(0, eq)] = line.slice(eq + 1);
|
||||
}
|
||||
}
|
||||
return meta as Partial<SessionMetadata>;
|
||||
}
|
||||
|
||||
export function writeMetadata(filePath: string, meta: Partial<SessionMetadata>): void {
|
||||
mkdirSync(join(filePath, ".."), { recursive: true });
|
||||
const lines = Object.entries(meta)
|
||||
.filter(([, v]) => v !== undefined && v !== null)
|
||||
.map(([k, v]) => `${k}=${v}`);
|
||||
writeFileSync(filePath, lines.join("\n") + "\n");
|
||||
}
|
||||
|
||||
export function archiveMetadata(sessionDir: string, sessionName: string): void {
|
||||
const metaFile = join(sessionDir, sessionName);
|
||||
if (!existsSync(metaFile)) return;
|
||||
const archiveDir = join(sessionDir, "archive");
|
||||
mkdirSync(archiveDir, { recursive: true });
|
||||
const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
|
||||
renameSync(metaFile, join(archiveDir, `${sessionName}_${timestamp}`));
|
||||
}
|
||||
|
||||
export async function listSessionFiles(sessionDir: string): Promise<string[]> {
|
||||
if (!existsSync(sessionDir)) return [];
|
||||
const entries = await readdir(sessionDir);
|
||||
return entries.filter((e) => !e.startsWith(".") && e !== "archive");
|
||||
}
|
||||
|
||||
export async function findSessionForIssue(
|
||||
sessionDir: string,
|
||||
issueId: string,
|
||||
tmuxSessions: string[],
|
||||
projectId?: string,
|
||||
): Promise<string | null> {
|
||||
const lower = issueId.toLowerCase();
|
||||
const files = await listSessionFiles(sessionDir);
|
||||
for (const file of files) {
|
||||
const name = basename(file);
|
||||
if (!tmuxSessions.includes(name)) continue;
|
||||
const meta = readMetadata(join(sessionDir, file));
|
||||
// Skip sessions from other projects if projectId is specified
|
||||
// Stricter check: sessions without a project field are also excluded
|
||||
if (projectId && meta?.project !== projectId) continue;
|
||||
if (meta?.issue && meta.issue.toLowerCase() === lower) {
|
||||
return name;
|
||||
}
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
|
@ -12,6 +12,26 @@ const __filename = fileURLToPath(import.meta.url);
|
|||
const __dirname = dirname(__filename);
|
||||
const require = createRequire(import.meta.url);
|
||||
|
||||
/**
|
||||
* Build environment variables for spawning the dashboard process.
|
||||
* Shared between `ao start` and `ao dashboard` to avoid duplication.
|
||||
*/
|
||||
export function buildDashboardEnv(port: number, configPath: string | null): Record<string, string> {
|
||||
const env: Record<string, string> = { ...process.env } as Record<string, string>;
|
||||
|
||||
// Pass config path so dashboard uses the same config as the CLI
|
||||
if (configPath) {
|
||||
env["AO_CONFIG_PATH"] = configPath;
|
||||
}
|
||||
|
||||
// Set ports for client-side access (Next.js requires NEXT_PUBLIC_ prefix)
|
||||
env["PORT"] = String(port);
|
||||
env["NEXT_PUBLIC_TERMINAL_PORT"] = env["TERMINAL_PORT"] ?? "3001";
|
||||
env["NEXT_PUBLIC_DIRECT_TERMINAL_PORT"] = env["DIRECT_TERMINAL_PORT"] ?? "3003";
|
||||
|
||||
return env;
|
||||
}
|
||||
|
||||
/**
|
||||
* Locate the @composio/ao-web package directory.
|
||||
* Uses createRequire for ESM-compatible require.resolve, with fallback
|
||||
|
|
|
|||
|
|
@ -0,0 +1,144 @@
|
|||
import { describe, it, expect, beforeEach, afterEach } from "vitest";
|
||||
import { mkdirSync, writeFileSync, rmSync, realpathSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { tmpdir } from "node:os";
|
||||
import { loadConfig, findConfigFile } from "../src/config.js";
|
||||
|
||||
describe("Config Loading", () => {
|
||||
let testDir: string;
|
||||
let originalCwd: string;
|
||||
let originalEnv: NodeJS.ProcessEnv;
|
||||
|
||||
beforeEach(() => {
|
||||
// Create temp test directory
|
||||
testDir = join(tmpdir(), `ao-test-${Date.now()}`);
|
||||
mkdirSync(testDir, { recursive: true });
|
||||
|
||||
// Save original state
|
||||
originalCwd = process.cwd();
|
||||
originalEnv = { ...process.env };
|
||||
|
||||
// Change to test directory
|
||||
process.chdir(testDir);
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
// Restore original state
|
||||
process.chdir(originalCwd);
|
||||
process.env = originalEnv;
|
||||
|
||||
// Cleanup test directory
|
||||
try {
|
||||
rmSync(testDir, { recursive: true, force: true });
|
||||
} catch {
|
||||
// Best effort cleanup
|
||||
}
|
||||
});
|
||||
|
||||
describe("findConfigFile", () => {
|
||||
it("should find config in current directory", () => {
|
||||
const configPath = join(testDir, "agent-orchestrator.yaml");
|
||||
writeFileSync(configPath, "projects: {}");
|
||||
|
||||
const found = findConfigFile();
|
||||
// Use realpathSync to handle macOS /var -> /private/var symlink
|
||||
expect(realpathSync(found!)).toBe(realpathSync(configPath));
|
||||
});
|
||||
|
||||
it("should prioritize AO_CONFIG_PATH env var", () => {
|
||||
// Create config in a different location
|
||||
const customDir = join(testDir, "custom");
|
||||
mkdirSync(customDir);
|
||||
const customConfig = join(customDir, "custom-config.yaml");
|
||||
writeFileSync(customConfig, "projects: {}");
|
||||
|
||||
// Create config in current directory too
|
||||
const localConfig = join(testDir, "agent-orchestrator.yaml");
|
||||
writeFileSync(localConfig, "projects: {}");
|
||||
|
||||
// Set env var to point to custom location
|
||||
process.env["AO_CONFIG_PATH"] = customConfig;
|
||||
|
||||
const found = findConfigFile();
|
||||
expect(found).toBe(customConfig);
|
||||
});
|
||||
|
||||
it("should return null if no config found", () => {
|
||||
const found = findConfigFile();
|
||||
expect(found).toBeNull();
|
||||
});
|
||||
});
|
||||
|
||||
describe("loadConfig", () => {
|
||||
it("should load config from AO_CONFIG_PATH env var", () => {
|
||||
const configPath = join(testDir, "test-config.yaml");
|
||||
writeFileSync(
|
||||
configPath,
|
||||
`
|
||||
port: 4000
|
||||
projects:
|
||||
test-project:
|
||||
repo: test/repo
|
||||
path: ${testDir}
|
||||
defaultBranch: main
|
||||
`,
|
||||
);
|
||||
|
||||
process.env["AO_CONFIG_PATH"] = configPath;
|
||||
|
||||
const config = loadConfig();
|
||||
expect(config.port).toBe(4000);
|
||||
expect(config.projects["test-project"]).toBeDefined();
|
||||
});
|
||||
|
||||
it("should load config from explicit path parameter", () => {
|
||||
const configPath = join(testDir, "explicit-config.yaml");
|
||||
writeFileSync(
|
||||
configPath,
|
||||
`
|
||||
port: 5000
|
||||
projects:
|
||||
explicit-project:
|
||||
repo: test/repo
|
||||
path: ${testDir}
|
||||
defaultBranch: main
|
||||
`,
|
||||
);
|
||||
|
||||
const config = loadConfig(configPath);
|
||||
expect(config.port).toBe(5000);
|
||||
});
|
||||
|
||||
it("should throw error if config not found", () => {
|
||||
expect(() => loadConfig()).toThrow("No agent-orchestrator.yaml found");
|
||||
});
|
||||
});
|
||||
|
||||
describe("Config Discovery Priority", () => {
|
||||
it("should use explicit path over env var", () => {
|
||||
const envConfig = join(testDir, "env-config.yaml");
|
||||
const explicitConfig = join(testDir, "explicit-config.yaml");
|
||||
|
||||
writeFileSync(envConfig, "port: 3001\nprojects: {}");
|
||||
writeFileSync(explicitConfig, "port: 3002\nprojects: {}");
|
||||
|
||||
process.env["AO_CONFIG_PATH"] = envConfig;
|
||||
|
||||
const config = loadConfig(explicitConfig);
|
||||
expect(config.port).toBe(3002); // Should use explicit, not env
|
||||
});
|
||||
|
||||
it("should use env var over default search", () => {
|
||||
const envConfig = join(testDir, "env-config.yaml");
|
||||
const localConfig = join(testDir, "agent-orchestrator.yaml");
|
||||
|
||||
writeFileSync(envConfig, "port: 3001\nprojects: {}");
|
||||
writeFileSync(localConfig, "port: 3002\nprojects: {}");
|
||||
|
||||
process.env["AO_CONFIG_PATH"] = envConfig;
|
||||
|
||||
const config = loadConfig();
|
||||
expect(config.port).toBe(3001); // Should use env, not local
|
||||
});
|
||||
});
|
||||
});
|
||||
|
|
@ -1,303 +0,0 @@
|
|||
import { describe, it, expect } from "vitest";
|
||||
import { generateOrchestratorPrompt } from "../orchestrator-prompt.js";
|
||||
import type { OrchestratorConfig, ProjectConfig } from "../types.js";
|
||||
|
||||
function makeProject(overrides?: Partial<ProjectConfig>): ProjectConfig {
|
||||
return {
|
||||
name: "My App",
|
||||
repo: "org/my-app",
|
||||
path: "/tmp/my-app",
|
||||
defaultBranch: "main",
|
||||
sessionPrefix: "myapp",
|
||||
...overrides,
|
||||
};
|
||||
}
|
||||
|
||||
function makeConfig(
|
||||
project?: Partial<ProjectConfig>,
|
||||
configOverrides?: Partial<OrchestratorConfig>,
|
||||
): OrchestratorConfig {
|
||||
return {
|
||||
port: 3000,
|
||||
configPath: "/tmp/agent-orchestrator.yaml",
|
||||
projects: { "my-app": makeProject(project) },
|
||||
...configOverrides,
|
||||
} as OrchestratorConfig;
|
||||
}
|
||||
|
||||
function generate(
|
||||
project?: Partial<ProjectConfig>,
|
||||
configOverrides?: Partial<OrchestratorConfig>,
|
||||
): string {
|
||||
const config = makeConfig(project, configOverrides);
|
||||
return generateOrchestratorPrompt({
|
||||
config,
|
||||
projectId: "my-app",
|
||||
project: config.projects["my-app"],
|
||||
});
|
||||
}
|
||||
|
||||
describe("generateOrchestratorPrompt", () => {
|
||||
describe("identity and role", () => {
|
||||
it("establishes the agent as an orchestrator", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("orchestrator agent");
|
||||
expect(prompt).toContain("My App");
|
||||
});
|
||||
|
||||
it("explicitly states the agent should NOT implement", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("you do NOT implement");
|
||||
});
|
||||
|
||||
it("describes the core responsibilities", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Spawn");
|
||||
expect(prompt).toContain("Monitor");
|
||||
expect(prompt).toContain("Intervene");
|
||||
expect(prompt).toContain("Delegate");
|
||||
expect(prompt).toContain("Clean up");
|
||||
});
|
||||
|
||||
it("warns against writing code", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Never write code");
|
||||
});
|
||||
});
|
||||
|
||||
describe("project info", () => {
|
||||
it("includes project metadata", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("My App");
|
||||
expect(prompt).toContain("org/my-app");
|
||||
expect(prompt).toContain("`main`");
|
||||
expect(prompt).toContain("`myapp`");
|
||||
expect(prompt).toContain("http://localhost:3000");
|
||||
});
|
||||
|
||||
it("shows session naming convention", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("`myapp-1`");
|
||||
expect(prompt).toContain("`myapp-2`");
|
||||
});
|
||||
|
||||
it("uses custom port from config", () => {
|
||||
const prompt = generate({}, { port: 8080 } as Partial<OrchestratorConfig>);
|
||||
expect(prompt).toContain("http://localhost:8080");
|
||||
});
|
||||
});
|
||||
|
||||
describe("CLI reference", () => {
|
||||
it("documents ao status command", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao status");
|
||||
expect(prompt).toContain("ao status");
|
||||
expect(prompt).toContain("--json");
|
||||
expect(prompt).toContain("-p my-app");
|
||||
});
|
||||
|
||||
it("documents ao spawn command", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao spawn");
|
||||
expect(prompt).toContain("ao spawn my-app");
|
||||
expect(prompt).toContain("--open");
|
||||
});
|
||||
|
||||
it("documents ao batch-spawn command", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao batch-spawn");
|
||||
expect(prompt).toContain("ao batch-spawn my-app");
|
||||
expect(prompt).toContain("Duplicate detection");
|
||||
});
|
||||
|
||||
it("documents ao send command with all flags", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao send");
|
||||
expect(prompt).toContain("ao send myapp-1");
|
||||
expect(prompt).toContain("-f");
|
||||
expect(prompt).toContain("--no-wait");
|
||||
expect(prompt).toContain("--timeout");
|
||||
});
|
||||
|
||||
it("documents ao session ls command", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao session ls");
|
||||
});
|
||||
|
||||
it("documents ao session kill command", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao session kill");
|
||||
expect(prompt).toContain("Irreversible");
|
||||
});
|
||||
|
||||
it("documents ao session cleanup command", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao session cleanup");
|
||||
expect(prompt).toContain("--dry-run");
|
||||
});
|
||||
|
||||
it("documents ao review-check command", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao review-check");
|
||||
});
|
||||
|
||||
it("documents ao open command", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao open");
|
||||
expect(prompt).toContain("-w");
|
||||
});
|
||||
|
||||
it("documents ao dashboard command", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao dashboard");
|
||||
});
|
||||
|
||||
it("documents ao start / ao stop", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("### ao start");
|
||||
expect(prompt).toContain("ao stop");
|
||||
});
|
||||
|
||||
it("warns against raw tmux send-keys", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Never use `tmux send-keys`");
|
||||
});
|
||||
});
|
||||
|
||||
describe("session lifecycle", () => {
|
||||
it("describes the full lifecycle flow", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Session Lifecycle");
|
||||
expect(prompt).toContain("Worktree created");
|
||||
expect(prompt).toContain("Feature branch");
|
||||
expect(prompt).toContain("tmux session");
|
||||
expect(prompt).toContain("Agent launched");
|
||||
expect(prompt).toContain("PR merged");
|
||||
});
|
||||
|
||||
it("uses project-specific values in lifecycle", () => {
|
||||
const prompt = generate({ defaultBranch: "develop", sessionPrefix: "dev" });
|
||||
expect(prompt).toContain("origin/develop");
|
||||
expect(prompt).toContain("dev-N");
|
||||
});
|
||||
});
|
||||
|
||||
describe("behavioral guidelines", () => {
|
||||
it("includes positive behaviors", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Check before spawning");
|
||||
expect(prompt).toContain("ao send");
|
||||
expect(prompt).toContain("Delegate, don't duplicate");
|
||||
expect(prompt).toContain("Batch when possible");
|
||||
expect(prompt).toContain("Clean up after merges");
|
||||
});
|
||||
|
||||
it("includes anti-patterns", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Never write code");
|
||||
expect(prompt).toContain("Never use legacy scripts");
|
||||
expect(prompt).toContain("Never use raw tmux");
|
||||
expect(prompt).toContain("Never spawn for trivial tasks");
|
||||
expect(prompt).toContain("Never duplicate work");
|
||||
});
|
||||
});
|
||||
|
||||
describe("workflows", () => {
|
||||
it("includes batch processing workflow", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Process a Batch of Issues");
|
||||
expect(prompt).toContain("ao batch-spawn");
|
||||
});
|
||||
|
||||
it("includes stuck worker workflow", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Handle a Stuck Worker");
|
||||
expect(prompt).toContain("capture-pane");
|
||||
});
|
||||
|
||||
it("includes PR review workflow", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Handle PR Review Comments");
|
||||
expect(prompt).toContain("ao review-check");
|
||||
});
|
||||
|
||||
it("includes cleanup workflow", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Clean Up After Merge");
|
||||
expect(prompt).toContain("--dry-run");
|
||||
});
|
||||
});
|
||||
|
||||
describe("reactions", () => {
|
||||
it("omits reactions section when no reactions configured", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).not.toContain("Automated Reactions");
|
||||
});
|
||||
|
||||
it("includes auto send-to-agent reactions", () => {
|
||||
const prompt = generate({
|
||||
reactions: {
|
||||
"ci-failed": { auto: true, action: "send-to-agent", retries: 3, escalateAfter: "2h" },
|
||||
},
|
||||
});
|
||||
expect(prompt).toContain("Automated Reactions");
|
||||
expect(prompt).toContain("ci-failed");
|
||||
expect(prompt).toContain("retries: 3");
|
||||
expect(prompt).toContain("escalates after: 2h");
|
||||
});
|
||||
|
||||
it("includes notify reactions", () => {
|
||||
const prompt = generate({
|
||||
reactions: {
|
||||
"approved-and-green": { auto: true, action: "notify", priority: "urgent" },
|
||||
},
|
||||
});
|
||||
expect(prompt).toContain("approved-and-green");
|
||||
expect(prompt).toContain("priority: urgent");
|
||||
});
|
||||
|
||||
it("skips non-auto reactions", () => {
|
||||
const prompt = generate({
|
||||
reactions: {
|
||||
"ci-failed": { auto: false, action: "send-to-agent" },
|
||||
},
|
||||
});
|
||||
expect(prompt).not.toContain("Automated Reactions");
|
||||
});
|
||||
});
|
||||
|
||||
describe("project-specific rules", () => {
|
||||
it("omits section when no orchestratorRules configured", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).not.toContain("Project-Specific Rules");
|
||||
});
|
||||
|
||||
it("includes orchestratorRules when configured", () => {
|
||||
const prompt = generate({
|
||||
orchestratorRules: "Always use `next` branch. Never push directly to main.",
|
||||
});
|
||||
expect(prompt).toContain("Project-Specific Rules");
|
||||
expect(prompt).toContain("Always use `next` branch");
|
||||
expect(prompt).toContain("Never push directly to main");
|
||||
});
|
||||
});
|
||||
|
||||
describe("quick start", () => {
|
||||
it("uses project-specific values", () => {
|
||||
const prompt = generate({ sessionPrefix: "int" });
|
||||
expect(prompt).toContain("ao spawn my-app");
|
||||
expect(prompt).toContain("ao send int-1");
|
||||
expect(prompt).toContain("ao session ls -p my-app");
|
||||
expect(prompt).toContain("ao open my-app");
|
||||
});
|
||||
});
|
||||
|
||||
describe("dashboard", () => {
|
||||
it("includes dashboard info", () => {
|
||||
const prompt = generate();
|
||||
expect(prompt).toContain("Dashboard");
|
||||
expect(prompt).toContain("http://localhost:3000");
|
||||
expect(prompt).toContain("Server-Sent Events");
|
||||
});
|
||||
});
|
||||
});
|
||||
|
|
@ -0,0 +1,87 @@
|
|||
import { describe, it, expect, afterEach } from "vitest";
|
||||
import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
|
||||
import { join } from "node:path";
|
||||
import { tmpdir } from "node:os";
|
||||
import { readLastJsonlEntry } from "../utils.js";
|
||||
|
||||
describe("readLastJsonlEntry", () => {
|
||||
let tmpDir: string;
|
||||
|
||||
afterEach(() => {
|
||||
if (tmpDir) rmSync(tmpDir, { recursive: true, force: true });
|
||||
});
|
||||
|
||||
function setup(content: string): string {
|
||||
tmpDir = mkdtempSync(join(tmpdir(), "ao-utils-test-"));
|
||||
const filePath = join(tmpDir, "test.jsonl");
|
||||
writeFileSync(filePath, content, "utf-8");
|
||||
return filePath;
|
||||
}
|
||||
|
||||
it("returns null for empty file", async () => {
|
||||
const path = setup("");
|
||||
expect(await readLastJsonlEntry(path)).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null for nonexistent file", async () => {
|
||||
expect(await readLastJsonlEntry("/tmp/nonexistent-ao-test.jsonl")).toBeNull();
|
||||
});
|
||||
|
||||
it("reads last entry type from single-line JSONL", async () => {
|
||||
const path = setup('{"type":"assistant","message":"hello"}\n');
|
||||
const result = await readLastJsonlEntry(path);
|
||||
expect(result).not.toBeNull();
|
||||
expect(result!.lastType).toBe("assistant");
|
||||
});
|
||||
|
||||
it("reads last entry from multi-line JSONL", async () => {
|
||||
const path = setup(
|
||||
'{"type":"human","text":"hi"}\n{"type":"assistant","text":"hello"}\n{"type":"result","text":"done"}\n',
|
||||
);
|
||||
const result = await readLastJsonlEntry(path);
|
||||
expect(result!.lastType).toBe("result");
|
||||
});
|
||||
|
||||
it("handles trailing newlines", async () => {
|
||||
const path = setup('{"type":"done"}\n\n\n');
|
||||
const result = await readLastJsonlEntry(path);
|
||||
expect(result!.lastType).toBe("done");
|
||||
});
|
||||
|
||||
it("returns lastType null for entry without type field", async () => {
|
||||
const path = setup('{"message":"no type"}\n');
|
||||
const result = await readLastJsonlEntry(path);
|
||||
expect(result).not.toBeNull();
|
||||
expect(result!.lastType).toBeNull();
|
||||
});
|
||||
|
||||
it("returns null for invalid JSON", async () => {
|
||||
const path = setup("not json at all\n");
|
||||
expect(await readLastJsonlEntry(path)).toBeNull();
|
||||
});
|
||||
|
||||
it("handles multi-byte UTF-8 characters in JSONL entries", async () => {
|
||||
// Create a JSONL entry with multi-byte characters (CJK, emoji)
|
||||
const entry = { type: "assistant", text: "日本語テスト 🎉 données résumé" };
|
||||
const path = setup(JSON.stringify(entry) + "\n");
|
||||
const result = await readLastJsonlEntry(path);
|
||||
expect(result!.lastType).toBe("assistant");
|
||||
});
|
||||
|
||||
it("handles multi-byte UTF-8 at chunk boundaries", async () => {
|
||||
// Create content larger than the 4096 byte chunk size with multi-byte
|
||||
// characters that could straddle a boundary. Each 🎉 is 4 bytes.
|
||||
const padding = '{"type":"padding","data":"' + "x".repeat(4080) + '"}\n';
|
||||
// The emoji-heavy last line will be at a chunk boundary
|
||||
const lastLine = { type: "final", text: "🎉".repeat(100) };
|
||||
const path = setup(padding + JSON.stringify(lastLine) + "\n");
|
||||
const result = await readLastJsonlEntry(path);
|
||||
expect(result!.lastType).toBe("final");
|
||||
});
|
||||
|
||||
it("returns modifiedAt as a Date", async () => {
|
||||
const path = setup('{"type":"test"}\n');
|
||||
const result = await readLastJsonlEntry(path);
|
||||
expect(result!.modifiedAt).toBeInstanceOf(Date);
|
||||
});
|
||||
});
|
||||
|
|
@ -279,15 +279,15 @@ function applyDefaultReactions(config: OrchestratorConfig): OrchestratorConfig {
|
|||
* Search for config file in standard locations.
|
||||
*
|
||||
* Search order:
|
||||
* 1. AO_CONFIG environment variable (if set)
|
||||
* 1. AO_CONFIG_PATH environment variable (if set)
|
||||
* 2. Search up directory tree from CWD (like git)
|
||||
* 3. Explicit startDir (if provided)
|
||||
* 4. Home directory locations
|
||||
*/
|
||||
function findConfigFile(startDir?: string): string | null {
|
||||
export function findConfigFile(startDir?: string): string | null {
|
||||
// 1. Check environment variable override
|
||||
if (process.env.AO_CONFIG) {
|
||||
const envPath = resolve(process.env.AO_CONFIG);
|
||||
if (process.env["AO_CONFIG_PATH"]) {
|
||||
const envPath = resolve(process.env["AO_CONFIG_PATH"]);
|
||||
if (existsSync(envPath)) {
|
||||
return envPath;
|
||||
}
|
||||
|
|
@ -357,6 +357,8 @@ export function findConfig(startDir?: string): string | null {
|
|||
|
||||
/** Load and validate config from a YAML file */
|
||||
export function loadConfig(configPath?: string): OrchestratorConfig {
|
||||
// Priority: 1. Explicit param, 2. Search (including AO_CONFIG_PATH env var)
|
||||
// findConfigFile handles AO_CONFIG_PATH validation, so delegate to it
|
||||
const path = configPath ?? findConfigFile();
|
||||
|
||||
if (!path) {
|
||||
|
|
|
|||
|
|
@ -15,6 +15,7 @@ export {
|
|||
validateConfig,
|
||||
getDefaultConfig,
|
||||
findConfig,
|
||||
findConfigFile,
|
||||
} from "./config.js";
|
||||
|
||||
// Plugin registry
|
||||
|
|
|
|||
|
|
@ -99,6 +99,9 @@ export function readMetadata(dataDir: string, sessionId: SessionId): SessionMeta
|
|||
project: raw["project"],
|
||||
createdAt: raw["createdAt"],
|
||||
runtimeHandle: raw["runtimeHandle"],
|
||||
dashboardPort: raw["dashboardPort"] ? Number(raw["dashboardPort"]) : undefined,
|
||||
terminalWsPort: raw["terminalWsPort"] ? Number(raw["terminalWsPort"]) : undefined,
|
||||
directTerminalWsPort: raw["directTerminalWsPort"] ? Number(raw["directTerminalWsPort"]) : undefined,
|
||||
};
|
||||
}
|
||||
|
||||
|
|
@ -138,6 +141,12 @@ export function writeMetadata(
|
|||
if (metadata.project) data["project"] = metadata.project;
|
||||
if (metadata.createdAt) data["createdAt"] = metadata.createdAt;
|
||||
if (metadata.runtimeHandle) data["runtimeHandle"] = metadata.runtimeHandle;
|
||||
if (metadata.dashboardPort !== undefined)
|
||||
data["dashboardPort"] = String(metadata.dashboardPort);
|
||||
if (metadata.terminalWsPort !== undefined)
|
||||
data["terminalWsPort"] = String(metadata.terminalWsPort);
|
||||
if (metadata.directTerminalWsPort !== undefined)
|
||||
data["directTerminalWsPort"] = String(metadata.directTerminalWsPort);
|
||||
|
||||
writeFileSync(path, serializeMetadata(data), "utf-8");
|
||||
}
|
||||
|
|
|
|||
|
|
@ -3,10 +3,6 @@
|
|||
*
|
||||
* This file is imported into CLAUDE.local.md (gitignored) in the main checkout
|
||||
* to provide orchestrator-specific context when the orchestrator agent runs.
|
||||
*
|
||||
* The generated prompt is the orchestrator agent's primary reference. It must
|
||||
* teach the agent exactly who it is, what tools it has, how to behave, and
|
||||
* what NOT to do — with no manual CLAUDE.md customization required.
|
||||
*/
|
||||
|
||||
import type { OrchestratorConfig, ProjectConfig } from "./types.js";
|
||||
|
|
@ -19,236 +15,128 @@ export interface OrchestratorPromptConfig {
|
|||
|
||||
/**
|
||||
* Generate markdown content for CLAUDE.orchestrator.md.
|
||||
*
|
||||
* The generated prompt covers:
|
||||
* 1. Identity and role — orchestrator, not a worker
|
||||
* 2. Complete CLI reference — every `ao` command with flags and examples
|
||||
* 3. Behavioral guidelines — when to spawn, delegate, monitor, intervene
|
||||
* 4. Anti-patterns — what NOT to do
|
||||
* 5. Project configuration — adapted to the specific project setup
|
||||
* Provides orchestrator agent with context about available commands,
|
||||
* session management workflows, and project configuration.
|
||||
*/
|
||||
export function generateOrchestratorPrompt(opts: OrchestratorPromptConfig): string {
|
||||
const { config, projectId, project } = opts;
|
||||
const prefix = project.sessionPrefix;
|
||||
const sections: string[] = [];
|
||||
|
||||
// =========================================================================
|
||||
// IDENTITY
|
||||
// =========================================================================
|
||||
// Header
|
||||
sections.push(`# CLAUDE.orchestrator.md - ${project.name} Orchestrator
|
||||
|
||||
sections.push(`# Orchestrator Agent — ${project.name}
|
||||
You are the **orchestrator agent** for the ${project.name} project.
|
||||
|
||||
You are the **orchestrator agent** for ${project.name}. You plan, delegate, and monitor — you do NOT implement.
|
||||
Your role is to coordinate and manage worker agent sessions. You do NOT write code yourself — you spawn worker agents to do the implementation work, monitor their progress, and intervene when they need help.`);
|
||||
|
||||
## Your Role
|
||||
// Project Info
|
||||
sections.push(`## Project Info
|
||||
|
||||
You manage a fleet of parallel worker agents that do the actual coding:
|
||||
- **Spawn** worker sessions for issues/tickets (each gets its own git worktree + tmux session)
|
||||
- **Monitor** their progress via \`ao status\` and the dashboard
|
||||
- **Intervene** when workers are stuck, CI fails, or reviewers request changes
|
||||
- **Delegate** by sending messages to workers via \`ao send\`
|
||||
- **Clean up** completed sessions after PRs are merged
|
||||
|
||||
You are NOT a coding agent. Never implement features, fix bugs, or write code yourself. If something needs implementation, spawn a worker session for it.`);
|
||||
|
||||
// =========================================================================
|
||||
// PROJECT INFO
|
||||
// =========================================================================
|
||||
|
||||
sections.push(`## Project
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| Name | ${project.name} |
|
||||
| Repository | ${project.repo} |
|
||||
| Default Branch | \`${project.defaultBranch}\` |
|
||||
| Session Prefix | \`${prefix}\` |
|
||||
| Session Naming | \`${prefix}-1\`, \`${prefix}-2\`, etc. |
|
||||
| Dashboard | http://localhost:${config.port} |`);
|
||||
|
||||
// =========================================================================
|
||||
// QUICK START
|
||||
// =========================================================================
|
||||
- **Name**: ${project.name}
|
||||
- **Repository**: ${project.repo}
|
||||
- **Default Branch**: ${project.defaultBranch}
|
||||
- **Session Prefix**: ${project.sessionPrefix}
|
||||
- **Local Path**: ${project.path}
|
||||
- **Dashboard Port**: ${config.port ?? 3000}`);
|
||||
|
||||
// Quick Start
|
||||
sections.push(`## Quick Start
|
||||
|
||||
\`\`\`bash
|
||||
ao status # See all sessions
|
||||
ao spawn ${projectId} ISSUE-123 # Spawn one session
|
||||
ao batch-spawn ${projectId} ISSUE-1 ISSUE-2 # Spawn multiple
|
||||
ao send ${prefix}-1 "fix the CI failure" # Send message to worker
|
||||
ao session ls -p ${projectId} # List sessions
|
||||
ao session cleanup -p ${projectId} # Remove merged sessions
|
||||
ao open ${projectId} # Open all in terminal tabs
|
||||
# See all sessions at a glance
|
||||
ao status
|
||||
|
||||
# Spawn sessions for issues (GitHub: #123, Linear: INT-1234, etc.)
|
||||
ao spawn ${projectId} INT-1234
|
||||
ao batch-spawn ${projectId} INT-1 INT-2 INT-3
|
||||
|
||||
# List sessions
|
||||
ao session ls -p ${projectId}
|
||||
|
||||
# Send message to a session
|
||||
ao send ${project.sessionPrefix}-1 "Your message here"
|
||||
|
||||
# Kill a session
|
||||
ao session kill ${project.sessionPrefix}-1
|
||||
|
||||
# Open all sessions in terminal tabs
|
||||
ao open ${projectId}
|
||||
\`\`\``);
|
||||
|
||||
// =========================================================================
|
||||
// CLI REFERENCE — every command with full detail
|
||||
// =========================================================================
|
||||
// Available Commands
|
||||
sections.push(`## Available Commands
|
||||
|
||||
sections.push(buildCLIReference(projectId, project, config));
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| \`ao status\` | Show all sessions with PR/CI/review status |
|
||||
| \`ao spawn <project> [issue]\` | Spawn a single worker agent session |
|
||||
| \`ao batch-spawn <project> <issues...>\` | Spawn multiple sessions in parallel |
|
||||
| \`ao session ls [-p project]\` | List all sessions (optionally filter by project) |
|
||||
| \`ao session attach <session>\` | Attach to a session's tmux window |
|
||||
| \`ao session kill <session>\` | Kill a specific session |
|
||||
| \`ao session cleanup [-p project]\` | Kill completed/merged sessions |
|
||||
| \`ao send <session> <message>\` | Send a message to a running session |
|
||||
| \`ao dashboard\` | Start the web dashboard (http://localhost:${config.port ?? 3000}) |
|
||||
| \`ao open <project>\` | Open all project sessions in terminal tabs |`);
|
||||
|
||||
// =========================================================================
|
||||
// SESSION LIFECYCLE
|
||||
// =========================================================================
|
||||
// Session Management
|
||||
sections.push(`## Session Management
|
||||
|
||||
sections.push(`## Session Lifecycle
|
||||
### Spawning Sessions
|
||||
|
||||
\`\`\`
|
||||
ao spawn ${projectId} ISSUE-123
|
||||
|
|
||||
v
|
||||
[Worktree created from origin/${project.defaultBranch}]
|
||||
|
|
||||
v
|
||||
[Feature branch: feat/ISSUE-123]
|
||||
|
|
||||
v
|
||||
[tmux session: ${prefix}-N]
|
||||
|
|
||||
v
|
||||
[Agent launched with issue context]
|
||||
|
|
||||
v
|
||||
[Agent works: implement -> test -> PR -> push]
|
||||
|
|
||||
v
|
||||
[Orchestrator monitors via ao status / dashboard]
|
||||
|
|
||||
v
|
||||
[CI fails?] --yes--> reaction auto-sends fix instructions to agent
|
||||
|no
|
||||
v
|
||||
[Review comments?] --yes--> reaction auto-forwards to agent
|
||||
|no
|
||||
v
|
||||
[PR merged] --> ao session cleanup removes session
|
||||
\`\`\`
|
||||
When you spawn a session:
|
||||
1. A git worktree is created from \`${project.defaultBranch}\`
|
||||
2. A feature branch is created (e.g., \`feat/INT-1234\`)
|
||||
3. A tmux session is started (e.g., \`${project.sessionPrefix}-1\`)
|
||||
4. The agent is launched with context about the issue
|
||||
5. Metadata is written to the project-specific sessions directory
|
||||
|
||||
Each worker session is fully isolated:
|
||||
- Own git worktree (separate working directory)
|
||||
- Own tmux session (can attach/detach independently)
|
||||
- Own feature branch (no conflicts between workers)
|
||||
- Metadata file tracking branch, PR, status, issue`);
|
||||
### Monitoring Progress
|
||||
|
||||
// =========================================================================
|
||||
// BEHAVIORAL GUIDELINES
|
||||
// =========================================================================
|
||||
Use \`ao status\` to see:
|
||||
- Current session status (working, pr_open, review_pending, etc.)
|
||||
- PR state (open/merged/closed)
|
||||
- CI status (passing/failing/pending)
|
||||
- Review decision (approved/changes_requested/pending)
|
||||
- Unresolved comments count
|
||||
|
||||
sections.push(`## How to Behave
|
||||
### Sending Messages
|
||||
|
||||
### Always Do
|
||||
|
||||
1. **Check before spawning** — Run \`ao status\` first. Never create duplicate sessions for the same issue.
|
||||
2. **Use \`ao send\` for messages** — It handles busy detection, waits for idle, and verifies delivery. Never use raw \`tmux send-keys\`.
|
||||
3. **Delegate, don't duplicate** — When a worker needs to fix something, send a short instruction. Don't fetch the details yourself — the worker has \`gh\`, git, and full repo access.
|
||||
4. **Batch when possible** — Use \`ao batch-spawn\` for multiple issues. It has built-in duplicate detection.
|
||||
5. **Monitor, don't micromanage** — Check \`ao status\` periodically. Only intervene when a session is stuck or needs input.
|
||||
6. **Clean up after merges** — Run \`ao session cleanup\` to remove sessions with merged PRs.
|
||||
7. **Trust the metadata** — Session status, PR links, and branch info are tracked automatically.
|
||||
8. **Verify message delivery** — \`ao send\` confirms delivery. If it reports uncertainty, check the session.
|
||||
|
||||
### Never Do
|
||||
|
||||
1. **Never write code** — You are the orchestrator. Spawn a worker for any implementation task.
|
||||
2. **Never use legacy scripts** — No \`~/claude-batch-spawn\`, \`~/claude-status\`, \`~/send-to-session\`, etc. Use the \`ao\` CLI exclusively.
|
||||
3. **Never use raw tmux commands** — Don't \`tmux send-keys\` directly. Use \`ao send\` which handles busy detection and delivery verification.
|
||||
4. **Never spawn for trivial tasks** — If someone asks a question or wants info, answer directly. Only spawn workers for implementation tasks.
|
||||
5. **Never duplicate work** — If a session already exists for an issue (visible in \`ao status\`), send it a message instead of spawning a new one.
|
||||
6. **Never kill working sessions** — Check \`ao status\` activity before killing. Only kill sessions that are stuck/done.`);
|
||||
|
||||
// =========================================================================
|
||||
// WORKFLOWS
|
||||
// =========================================================================
|
||||
|
||||
sections.push(`## Common Workflows
|
||||
|
||||
### Process a Batch of Issues
|
||||
Send instructions to a running agent:
|
||||
\`\`\`bash
|
||||
# 1. Check what's already running
|
||||
ao status
|
||||
|
||||
# 2. Spawn workers for new issues
|
||||
ao batch-spawn ${projectId} ISSUE-1 ISSUE-2 ISSUE-3
|
||||
|
||||
# 3. Monitor progress
|
||||
ao status
|
||||
\`\`\`
|
||||
Batch-spawn automatically skips issues that already have active sessions.
|
||||
|
||||
### Handle a Stuck Worker
|
||||
\`\`\`bash
|
||||
# 1. Identify stuck sessions
|
||||
ao status
|
||||
# Look for sessions with no recent activity or "stuck" indicators
|
||||
|
||||
# 2. Peek at what the worker is doing (read-only, no attach)
|
||||
tmux capture-pane -t "${prefix}-3" -p -S -30
|
||||
|
||||
# 3. Send help
|
||||
ao send ${prefix}-3 "You seem stuck on X. Try Y instead."
|
||||
|
||||
# 4. If unrecoverable, kill and respawn
|
||||
ao session kill ${prefix}-3
|
||||
ao spawn ${projectId} ISSUE-123
|
||||
ao send ${project.sessionPrefix}-1 "Please address the review comments on your PR"
|
||||
\`\`\`
|
||||
|
||||
### Handle PR Review Comments
|
||||
### Cleanup
|
||||
|
||||
Remove completed sessions:
|
||||
\`\`\`bash
|
||||
# Option 1: Automatic — ao review-check scans all PRs and sends fix prompts
|
||||
ao review-check ${projectId}
|
||||
|
||||
# Option 2: Manual — send targeted instruction to a specific worker
|
||||
ao send ${prefix}-2 "Address the review comments on your PR"
|
||||
\`\`\`
|
||||
Workers have full \`gh\` access. Keep messages short — don't fetch/paste review comments yourself.
|
||||
|
||||
### Clean Up After Merge
|
||||
\`\`\`bash
|
||||
# Dry run first to see what would be cleaned
|
||||
ao session cleanup -p ${projectId} --dry-run
|
||||
|
||||
# Actually clean up
|
||||
ao session cleanup -p ${projectId}
|
||||
\`\`\`
|
||||
|
||||
### Open Sessions in Terminal
|
||||
\`\`\`bash
|
||||
ao open ${projectId} # All sessions for this project
|
||||
ao open ${prefix}-3 # Specific session
|
||||
ao open all # Everything across all projects
|
||||
ao open ${projectId} -w # In a new terminal window
|
||||
ao session cleanup -p ${projectId} # Kill sessions where PR is merged or issue is closed
|
||||
\`\`\``);
|
||||
|
||||
// =========================================================================
|
||||
// DASHBOARD
|
||||
// =========================================================================
|
||||
|
||||
// Dashboard
|
||||
sections.push(`## Dashboard
|
||||
|
||||
The web dashboard at **http://localhost:${config.port}** provides:
|
||||
- Live session cards with real-time activity status
|
||||
- PR table showing CI checks, review state, and merge readiness
|
||||
- Attention zones: merge-ready, needs-response, working, done
|
||||
- One-click actions: send message, kill session, merge PR
|
||||
- Real-time updates via Server-Sent Events
|
||||
The web dashboard runs at **http://localhost:${config.port ?? 3000}**.
|
||||
|
||||
Use the dashboard for at-a-glance overview, the CLI for detailed operations.`);
|
||||
|
||||
// =========================================================================
|
||||
// REACTIONS (if configured)
|
||||
// =========================================================================
|
||||
Features:
|
||||
- Live session cards with activity status
|
||||
- PR table with CI checks and review state
|
||||
- Attention zones (merge ready, needs response, working, done)
|
||||
- One-click actions (send message, kill, merge PR)
|
||||
- Real-time updates via Server-Sent Events`);
|
||||
|
||||
// Reactions (if configured)
|
||||
if (project.reactions && Object.keys(project.reactions).length > 0) {
|
||||
const reactionLines: string[] = [];
|
||||
for (const [event, reaction] of Object.entries(project.reactions)) {
|
||||
if (reaction.auto && reaction.action === "send-to-agent") {
|
||||
reactionLines.push(
|
||||
`- **${event}**: Auto-sends fix instructions to the agent (retries: ${reaction.retries ?? "none"}, escalates after: ${reaction.escalateAfter ?? "never"})`,
|
||||
`- **${event}**: Auto-sends instruction to agent (retries: ${reaction.retries ?? "none"}, escalates after: ${reaction.escalateAfter ?? "never"})`,
|
||||
);
|
||||
} else if (reaction.auto && reaction.action === "notify") {
|
||||
reactionLines.push(
|
||||
`- **${event}**: Sends notification to human (priority: ${reaction.priority ?? "info"})`,
|
||||
`- **${event}**: Notifies human (priority: ${reaction.priority ?? "info"})`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
|
@ -256,18 +144,63 @@ Use the dashboard for at-a-glance overview, the CLI for detailed operations.`);
|
|||
if (reactionLines.length > 0) {
|
||||
sections.push(`## Automated Reactions
|
||||
|
||||
These events are handled automatically — you do NOT need to intervene unless the auto-handling fails:
|
||||
The system automatically handles these events:
|
||||
|
||||
${reactionLines.join("\n")}
|
||||
|
||||
Reactions that auto-send to agents will retry and escalate to you if the agent doesn't fix the issue within the configured window.`);
|
||||
${reactionLines.join("\n")}`);
|
||||
}
|
||||
}
|
||||
|
||||
// =========================================================================
|
||||
// PROJECT-SPECIFIC RULES (if any)
|
||||
// =========================================================================
|
||||
// Workflows
|
||||
sections.push(`## Common Workflows
|
||||
|
||||
### Bulk Issue Processing
|
||||
1. Get list of issues from tracker (GitHub/Linear/etc.)
|
||||
2. Use \`ao batch-spawn\` to spawn sessions for each issue
|
||||
3. Monitor with \`ao status\` or the dashboard
|
||||
4. Agents will fetch, implement, test, PR, and respond to reviews
|
||||
5. Use \`ao session cleanup\` when PRs are merged
|
||||
|
||||
### Handling Stuck Agents
|
||||
1. Check \`ao status\` for sessions in "stuck" or "needs_input" state
|
||||
2. Attach with \`ao session attach <session>\` to see what they're doing
|
||||
3. Send clarification or instructions with \`ao send <session> '...'\`
|
||||
4. Or kill and respawn with fresh context if needed
|
||||
|
||||
### PR Review Flow
|
||||
1. Agent creates PR and pushes
|
||||
2. CI runs automatically
|
||||
3. If CI fails: reaction auto-sends fix instructions to agent
|
||||
4. If reviewers request changes: reaction auto-sends comments to agent
|
||||
5. When approved + green: notify human to merge (unless auto-merge enabled)
|
||||
|
||||
### Manual Intervention
|
||||
When an agent needs human judgment:
|
||||
1. You'll get a notification (desktop/slack/webhook)
|
||||
2. Check the dashboard or \`ao status\` for details
|
||||
3. Attach to the session if needed: \`ao session attach <session>\`
|
||||
4. Send instructions: \`ao send <session> '...'\`
|
||||
5. Or handle it yourself (merge PR, close issue, etc.)`);
|
||||
|
||||
// Tips
|
||||
sections.push(`## Tips
|
||||
|
||||
1. **Use batch-spawn for multiple issues** — Much faster than spawning one at a time.
|
||||
|
||||
2. **Check status before spawning** — Avoid creating duplicate sessions for issues already being worked on.
|
||||
|
||||
3. **Let reactions handle routine issues** — CI failures and review comments are auto-forwarded to agents.
|
||||
|
||||
4. **Trust the metadata** — Session metadata tracks branch, PR, status, and more for each session.
|
||||
|
||||
5. **Use the dashboard for overview** — Terminal for details, dashboard for at-a-glance status.
|
||||
|
||||
6. **Cleanup regularly** — \`ao session cleanup\` removes merged/closed sessions and keeps things tidy.
|
||||
|
||||
7. **Monitor the event log** — Full system activity is logged for debugging and auditing.
|
||||
|
||||
8. **Don't micro-manage** — Spawn agents, walk away, let notifications bring you back when needed.`);
|
||||
|
||||
// Project-specific rules (if any)
|
||||
if (project.orchestratorRules) {
|
||||
sections.push(`## Project-Specific Rules
|
||||
|
||||
|
|
@ -276,194 +209,3 @@ ${project.orchestratorRules}`);
|
|||
|
||||
return sections.join("\n\n");
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
// CLI REFERENCE BUILDER
|
||||
// =============================================================================
|
||||
|
||||
/**
|
||||
* Build a comprehensive CLI reference section documenting every `ao` command
|
||||
* with all flags, options, and usage examples.
|
||||
*/
|
||||
function buildCLIReference(
|
||||
projectId: string,
|
||||
project: ProjectConfig,
|
||||
config: OrchestratorConfig,
|
||||
): string {
|
||||
const prefix = project.sessionPrefix;
|
||||
|
||||
return `## CLI Reference
|
||||
|
||||
### ao status
|
||||
|
||||
Show all sessions with branch, PR, CI, review status, and agent activity.
|
||||
|
||||
\`\`\`bash
|
||||
ao status # All projects
|
||||
ao status -p ${projectId} # Filter to this project
|
||||
ao status --json # Machine-readable JSON output
|
||||
\`\`\`
|
||||
|
||||
**Output columns**: Session, Branch, PR#, CI (pass/fail/pending), Review (approved/changes/pending), Threads (unresolved comment count), Activity (working/idle/waiting/exited), Age.
|
||||
|
||||
Each session also shows the agent's auto-generated summary of what it's working on.
|
||||
|
||||
---
|
||||
|
||||
### ao spawn
|
||||
|
||||
Spawn a single worker agent session for an issue.
|
||||
|
||||
\`\`\`bash
|
||||
ao spawn ${projectId} ISSUE-123 # Spawn with issue
|
||||
ao spawn ${projectId} # Spawn without issue (bare session)
|
||||
ao spawn ${projectId} ISSUE-123 --open # Also open in terminal tab
|
||||
\`\`\`
|
||||
|
||||
**What happens**: Creates git worktree from \`origin/${project.defaultBranch}\`, creates feature branch (\`feat/ISSUE-123\`), starts tmux session (\`${prefix}-N\`), launches agent with composed prompt, writes metadata.
|
||||
|
||||
**Issue format**: Accepts any identifier — GitHub issues (\`#42\`, \`42\`), Linear tickets (\`INT-1234\`), Jira keys (\`PROJ-567\`), etc.
|
||||
|
||||
---
|
||||
|
||||
### ao batch-spawn
|
||||
|
||||
Spawn sessions for multiple issues at once with duplicate detection.
|
||||
|
||||
\`\`\`bash
|
||||
ao batch-spawn ${projectId} ISSUE-1 ISSUE-2 ISSUE-3
|
||||
ao batch-spawn ${projectId} ISSUE-1 ISSUE-2 --open # Also open tabs
|
||||
\`\`\`
|
||||
|
||||
**Duplicate detection**: Skips issues that already have an active session (checks both existing sessions and within the current batch). Reports a summary of created/skipped/failed.
|
||||
|
||||
---
|
||||
|
||||
### ao send
|
||||
|
||||
Send a message to a running worker agent. Handles busy detection and delivery verification.
|
||||
|
||||
\`\`\`bash
|
||||
ao send ${prefix}-1 "Fix the failing test in auth.test.ts"
|
||||
ao send ${prefix}-1 -f /tmp/detailed-instructions.txt # From file
|
||||
ao send ${prefix}-1 --no-wait "Urgent: stop what you're doing" # Skip idle wait
|
||||
ao send ${prefix}-1 --timeout 120 "Take your time" # Custom timeout (seconds)
|
||||
\`\`\`
|
||||
|
||||
**How it works**:
|
||||
1. Waits for the session to become idle (default: up to 600s)
|
||||
2. Clears any partial input in the session
|
||||
3. Sends the message (multi-line messages use tmux buffer loading)
|
||||
4. Presses Enter to submit
|
||||
5. Verifies delivery by checking for agent activity indicators
|
||||
6. Retries Enter up to 3 times if delivery isn't confirmed
|
||||
|
||||
**Always use \`ao send\`** instead of raw \`tmux send-keys\`. It solves the hard problems: busy detection, input clearing, long message handling, delivery verification.
|
||||
|
||||
---
|
||||
|
||||
### ao session ls
|
||||
|
||||
List all sessions with metadata.
|
||||
|
||||
\`\`\`bash
|
||||
ao session ls # All projects
|
||||
ao session ls -p ${projectId} # Filter to this project
|
||||
\`\`\`
|
||||
|
||||
Shows: session name, age, branch, status, PR link.
|
||||
|
||||
---
|
||||
|
||||
### ao session kill
|
||||
|
||||
Kill a session, remove its worktree, and archive its metadata.
|
||||
|
||||
\`\`\`bash
|
||||
ao session kill ${prefix}-3
|
||||
\`\`\`
|
||||
|
||||
**Irreversible**: Removes the git worktree (uncommitted/unpushed work is lost). Only kill sessions that have pushed their work or are truly stuck.
|
||||
|
||||
---
|
||||
|
||||
### ao session cleanup
|
||||
|
||||
Automatically kill sessions where the PR has been merged.
|
||||
|
||||
\`\`\`bash
|
||||
ao session cleanup # All projects
|
||||
ao session cleanup -p ${projectId} # This project only
|
||||
ao session cleanup -p ${projectId} --dry-run # Preview what would be killed
|
||||
\`\`\`
|
||||
|
||||
Always run with \`--dry-run\` first when unsure.
|
||||
|
||||
---
|
||||
|
||||
### ao review-check
|
||||
|
||||
Scan all sessions with PRs for pending review comments and send fix instructions.
|
||||
|
||||
\`\`\`bash
|
||||
ao review-check # All projects
|
||||
ao review-check ${projectId} # This project only
|
||||
ao review-check ${projectId} --dry-run # Preview without sending
|
||||
\`\`\`
|
||||
|
||||
**What it does**: Finds PRs with unresolved review threads or "changes requested" decisions, then sends a fix prompt to the corresponding worker agent.
|
||||
|
||||
---
|
||||
|
||||
### ao open
|
||||
|
||||
Open session(s) in terminal tabs.
|
||||
|
||||
\`\`\`bash
|
||||
ao open ${prefix}-3 # Specific session
|
||||
ao open ${projectId} # All sessions for this project
|
||||
ao open all # All sessions across all projects
|
||||
ao open ${projectId} -w # Open in new terminal window
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
### ao dashboard
|
||||
|
||||
Start the web dashboard manually (usually started by \`ao start\`).
|
||||
|
||||
\`\`\`bash
|
||||
ao dashboard # Start on configured port (${config.port})
|
||||
ao dashboard -p 8080 # Custom port
|
||||
ao dashboard --no-open # Don't auto-open browser
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
### ao start / ao stop
|
||||
|
||||
Start or stop the orchestrator agent and dashboard.
|
||||
|
||||
\`\`\`bash
|
||||
ao start ${projectId} # Start everything
|
||||
ao start ${projectId} --no-dashboard # Skip dashboard
|
||||
ao start ${projectId} --no-orchestrator # Skip orchestrator agent
|
||||
ao stop ${projectId} # Stop everything
|
||||
\`\`\`
|
||||
|
||||
---
|
||||
|
||||
### tmux (read-only inspection)
|
||||
|
||||
For read-only inspection of sessions, you can use tmux directly:
|
||||
|
||||
\`\`\`bash
|
||||
# Peek at last 30 lines of a session (read-only, no attach)
|
||||
tmux capture-pane -t "${prefix}-3" -p -S -30
|
||||
|
||||
# List all tmux sessions
|
||||
tmux ls
|
||||
\`\`\`
|
||||
|
||||
Never use \`tmux send-keys\` — use \`ao send\` instead.`;
|
||||
}
|
||||
|
|
|
|||
|
|
@ -254,7 +254,6 @@ export interface Agent {
|
|||
* run git/gh commands. Without this, PRs created by agents never show up.
|
||||
*/
|
||||
setupWorkspaceHooks?(workspacePath: string, config: WorkspaceHooksConfig): Promise<void>;
|
||||
|
||||
}
|
||||
|
||||
export interface AgentLaunchConfig {
|
||||
|
|
@ -264,15 +263,11 @@ export interface AgentLaunchConfig {
|
|||
prompt?: string;
|
||||
permissions?: "skip" | "default";
|
||||
model?: string;
|
||||
|
||||
/**
|
||||
* System-level instructions to inject into the agent's context.
|
||||
* Used by `ao start` to give the orchestrator agent its instructions.
|
||||
*
|
||||
* Each agent plugin handles this in getLaunchCommand():
|
||||
* System prompt to pass to the agent for orchestrator context.
|
||||
* - Claude Code: --append-system-prompt
|
||||
* - Codex: --system-prompt or AGENTS.md
|
||||
* - Aider: --read flag or conventions
|
||||
* - Aider: --system-prompt flag
|
||||
* - OpenCode: equivalent mechanism
|
||||
*/
|
||||
systemPrompt?: string;
|
||||
|
|
@ -728,8 +723,8 @@ export interface OrchestratorConfig {
|
|||
*/
|
||||
configPath: string;
|
||||
|
||||
/** Web dashboard port */
|
||||
port: number;
|
||||
/** Web dashboard port (defaults to 3000) */
|
||||
port?: number;
|
||||
|
||||
/** Milliseconds before a "ready" session becomes "idle" (default: 300000 = 5 min) */
|
||||
readyThresholdMs: number;
|
||||
|
|
@ -890,6 +885,9 @@ export interface SessionMetadata {
|
|||
project?: string;
|
||||
createdAt?: string;
|
||||
runtimeHandle?: string;
|
||||
dashboardPort?: number;
|
||||
terminalWsPort?: number;
|
||||
directTerminalWsPort?: number;
|
||||
}
|
||||
|
||||
// =============================================================================
|
||||
|
|
|
|||
|
|
@ -2,11 +2,7 @@
|
|||
* Shared utility functions for agent-orchestrator plugins.
|
||||
*/
|
||||
|
||||
import { execFile } from "node:child_process";
|
||||
import { stat } from "node:fs/promises";
|
||||
import { promisify } from "node:util";
|
||||
|
||||
const execFileAsync = promisify(execFile);
|
||||
import { open, stat } from "node:fs/promises";
|
||||
|
||||
/**
|
||||
* POSIX-safe shell escaping: wraps value in single quotes,
|
||||
|
|
@ -36,9 +32,57 @@ export function validateUrl(url: string, label: string): void {
|
|||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the last line from a file by reading backwards from the end.
|
||||
* Pure Node.js — no external binaries. Handles any file size.
|
||||
*/
|
||||
async function readLastLine(filePath: string): Promise<string | null> {
|
||||
const CHUNK = 4096;
|
||||
const fh = await open(filePath, "r");
|
||||
try {
|
||||
const { size } = await fh.stat();
|
||||
if (size === 0) return null;
|
||||
|
||||
// Read backwards in chunks, accumulating raw buffers to avoid
|
||||
// corrupting multi-byte UTF-8 characters at chunk boundaries.
|
||||
const chunks: Buffer[] = [];
|
||||
let totalBytes = 0;
|
||||
let pos = size;
|
||||
|
||||
while (pos > 0) {
|
||||
const readSize = Math.min(CHUNK, pos);
|
||||
pos -= readSize;
|
||||
const chunk = Buffer.alloc(readSize);
|
||||
await fh.read(chunk, 0, readSize, pos);
|
||||
chunks.unshift(chunk);
|
||||
totalBytes += readSize;
|
||||
|
||||
// Convert all accumulated bytes to string at once (safe for multi-byte)
|
||||
const tail = Buffer.concat(chunks, totalBytes).toString("utf-8");
|
||||
|
||||
// Find the last non-empty line
|
||||
const lines = tail.split("\n");
|
||||
for (let i = lines.length - 1; i >= 0; i--) {
|
||||
const line = lines[i].trim();
|
||||
if (line) {
|
||||
// If i > 0, we have a complete line (there's a newline before it)
|
||||
// If i === 0 and pos === 0, we've read the whole file — line is complete
|
||||
// If i === 0 and pos > 0, the line may be truncated — keep reading
|
||||
if (i > 0 || pos === 0) return line;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
const tail = Buffer.concat(chunks, totalBytes).toString("utf-8");
|
||||
return tail.trim() || null;
|
||||
} finally {
|
||||
await fh.close();
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Read the last entry from a JSONL file.
|
||||
* Uses `tail -1` to efficiently read the last line, then JSON.parse in Node.
|
||||
* Reads backwards from end of file — pure Node.js, no external binaries.
|
||||
*
|
||||
* @param filePath - Path to the JSONL file
|
||||
* @returns Object containing the last entry's type and file mtime, or null if empty/invalid
|
||||
|
|
@ -47,12 +91,9 @@ export async function readLastJsonlEntry(
|
|||
filePath: string,
|
||||
): Promise<{ lastType: string | null; modifiedAt: Date } | null> {
|
||||
try {
|
||||
const [{ stdout }, fileStat] = await Promise.all([
|
||||
execFileAsync("tail", ["-1", filePath], { timeout: 5_000 }),
|
||||
stat(filePath),
|
||||
]);
|
||||
const [line, fileStat] = await Promise.all([readLastLine(filePath), stat(filePath)]);
|
||||
|
||||
|
||||
const line = stdout.trim();
|
||||
if (!line) return null;
|
||||
|
||||
const parsed: unknown = JSON.parse(line);
|
||||
|
|
|
|||
|
|
@ -0,0 +1,214 @@
|
|||
/**
|
||||
* Integration test for config discovery → metadata service flow.
|
||||
*
|
||||
* Tests the full chain from config file → hash-based directory calculation →
|
||||
* metadata operations, verifying that the service layer architecture works
|
||||
* end-to-end with real filesystem I/O.
|
||||
*/
|
||||
|
||||
import { mkdtemp, writeFile, rm } from "node:fs/promises";
|
||||
import { mkdirSync, existsSync, readdirSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { afterAll, beforeAll, describe, expect, it } from "vitest";
|
||||
import {
|
||||
getSessionsDir,
|
||||
getProjectBaseDir,
|
||||
generateConfigHash,
|
||||
writeMetadata,
|
||||
readMetadata,
|
||||
updateMetadata,
|
||||
deleteMetadata,
|
||||
listMetadata,
|
||||
validateAndStoreOrigin,
|
||||
} from "@composio/ao-core";
|
||||
|
||||
describe("config → metadata service integration (real filesystem)", () => {
|
||||
let tmpDir: string;
|
||||
let configPath: string;
|
||||
let repoPath: string;
|
||||
|
||||
beforeAll(async () => {
|
||||
tmpDir = await mkdtemp(join(tmpdir(), "ao-config-meta-integ-"));
|
||||
|
||||
repoPath = join(tmpDir, "my-repo");
|
||||
mkdirSync(repoPath, { recursive: true });
|
||||
|
||||
// Create a minimal config file
|
||||
const config = {
|
||||
port: 3000,
|
||||
defaults: {
|
||||
runtime: "tmux",
|
||||
agent: "claude-code",
|
||||
workspace: "worktree",
|
||||
notifiers: [],
|
||||
},
|
||||
projects: {
|
||||
"test-project": {
|
||||
name: "Test Project",
|
||||
repo: "org/test-repo",
|
||||
path: repoPath,
|
||||
defaultBranch: "main",
|
||||
sessionPrefix: "test",
|
||||
},
|
||||
},
|
||||
notifiers: {},
|
||||
notificationRouting: { urgent: [], action: [], warning: [], info: [] },
|
||||
reactions: {},
|
||||
};
|
||||
|
||||
configPath = join(tmpDir, "agent-orchestrator.yaml");
|
||||
await writeFile(configPath, JSON.stringify(config, null, 2));
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
// Clean up hash-based directories in ~/.agent-orchestrator
|
||||
try {
|
||||
const projectBaseDir = getProjectBaseDir(configPath, repoPath);
|
||||
if (existsSync(projectBaseDir)) {
|
||||
await rm(projectBaseDir, { recursive: true, force: true });
|
||||
}
|
||||
} catch {
|
||||
// Ignore cleanup errors
|
||||
}
|
||||
|
||||
if (tmpDir) {
|
||||
await rm(tmpDir, { recursive: true, force: true }).catch(() => {});
|
||||
}
|
||||
});
|
||||
|
||||
it("config hash is deterministic", () => {
|
||||
const hash1 = generateConfigHash(configPath);
|
||||
const hash2 = generateConfigHash(configPath);
|
||||
expect(hash1).toBe(hash2);
|
||||
expect(hash1.length).toBeGreaterThan(0);
|
||||
});
|
||||
|
||||
it("getSessionsDir returns hash-based path including project name", () => {
|
||||
const sessionsDir = getSessionsDir(configPath, repoPath);
|
||||
|
||||
expect(sessionsDir).toContain(".agent-orchestrator");
|
||||
expect(sessionsDir).toContain("my-repo");
|
||||
expect(sessionsDir).toContain("sessions");
|
||||
|
||||
const hash = generateConfigHash(configPath);
|
||||
expect(sessionsDir).toContain(hash);
|
||||
});
|
||||
|
||||
it("different repos get different session directories", () => {
|
||||
const repo2Path = join(tmpDir, "other-repo");
|
||||
mkdirSync(repo2Path, { recursive: true });
|
||||
|
||||
const dir1 = getSessionsDir(configPath, repoPath);
|
||||
const dir2 = getSessionsDir(configPath, repo2Path);
|
||||
|
||||
expect(dir1).not.toBe(dir2);
|
||||
expect(dir1).toContain("my-repo");
|
||||
expect(dir2).toContain("other-repo");
|
||||
});
|
||||
|
||||
it("full metadata lifecycle through hash-based directory", () => {
|
||||
const sessionsDir = getSessionsDir(configPath, repoPath);
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
// 1. Write metadata
|
||||
writeMetadata(sessionsDir, "lifecycle-1", {
|
||||
worktree: join(tmpDir, "worktrees", "lifecycle-1"),
|
||||
branch: "feat/TEST-100",
|
||||
status: "spawning",
|
||||
project: "test-project",
|
||||
issue: "TEST-100",
|
||||
createdAt: new Date().toISOString(),
|
||||
});
|
||||
|
||||
// 2. Read it back
|
||||
const meta = readMetadata(sessionsDir, "lifecycle-1");
|
||||
expect(meta).not.toBeNull();
|
||||
expect(meta!.branch).toBe("feat/TEST-100");
|
||||
expect(meta!.status).toBe("spawning");
|
||||
expect(meta!.project).toBe("test-project");
|
||||
expect(meta!.issue).toBe("TEST-100");
|
||||
|
||||
// 3. Update status
|
||||
updateMetadata(sessionsDir, "lifecycle-1", {
|
||||
status: "working",
|
||||
pr: "https://github.com/org/test-repo/pull/42",
|
||||
});
|
||||
|
||||
const updated = readMetadata(sessionsDir, "lifecycle-1");
|
||||
expect(updated!.status).toBe("working");
|
||||
expect(updated!.pr).toBe("https://github.com/org/test-repo/pull/42");
|
||||
expect(updated!.issue).toBe("TEST-100"); // preserved
|
||||
|
||||
// 4. List sessions
|
||||
writeMetadata(sessionsDir, "lifecycle-2", {
|
||||
worktree: join(tmpDir, "worktrees", "lifecycle-2"),
|
||||
branch: "feat/TEST-200",
|
||||
status: "idle",
|
||||
project: "test-project",
|
||||
});
|
||||
|
||||
const ids = listMetadata(sessionsDir);
|
||||
expect(ids).toContain("lifecycle-1");
|
||||
expect(ids).toContain("lifecycle-2");
|
||||
|
||||
// 5. Delete with archive
|
||||
deleteMetadata(sessionsDir, "lifecycle-1", true);
|
||||
expect(readMetadata(sessionsDir, "lifecycle-1")).toBeNull();
|
||||
|
||||
// Verify archive exists
|
||||
const archiveDir = join(sessionsDir, "archive");
|
||||
expect(existsSync(archiveDir)).toBe(true);
|
||||
const archived = readdirSync(archiveDir);
|
||||
expect(archived.some((f) => f.startsWith("lifecycle-1_"))).toBe(true);
|
||||
|
||||
// 6. Delete without archive
|
||||
deleteMetadata(sessionsDir, "lifecycle-2", false);
|
||||
expect(readMetadata(sessionsDir, "lifecycle-2")).toBeNull();
|
||||
});
|
||||
|
||||
it("origin validation stores and detects repo identity", () => {
|
||||
// validateAndStoreOrigin should not throw for a valid repo path
|
||||
// (even without a real git remote, it stores path-based identity)
|
||||
expect(() => validateAndStoreOrigin(configPath, repoPath)).not.toThrow();
|
||||
|
||||
// Calling again with the same path should succeed (same origin)
|
||||
expect(() => validateAndStoreOrigin(configPath, repoPath)).not.toThrow();
|
||||
});
|
||||
|
||||
it("multi-project isolation with shared config", () => {
|
||||
const repo2Path = join(tmpDir, "project-b-repo");
|
||||
mkdirSync(repo2Path, { recursive: true });
|
||||
|
||||
const dirA = getSessionsDir(configPath, repoPath);
|
||||
const dirB = getSessionsDir(configPath, repo2Path);
|
||||
mkdirSync(dirA, { recursive: true });
|
||||
mkdirSync(dirB, { recursive: true });
|
||||
|
||||
// Write session to project A
|
||||
writeMetadata(dirA, "projA-session-1", {
|
||||
worktree: "/a/wt",
|
||||
branch: "feat/A",
|
||||
status: "working",
|
||||
project: "project-a",
|
||||
});
|
||||
|
||||
// Write session to project B
|
||||
writeMetadata(dirB, "projB-session-1", {
|
||||
worktree: "/b/wt",
|
||||
branch: "feat/B",
|
||||
status: "idle",
|
||||
project: "project-b",
|
||||
});
|
||||
|
||||
// Sessions are isolated
|
||||
expect(listMetadata(dirA)).toContain("projA-session-1");
|
||||
expect(listMetadata(dirA)).not.toContain("projB-session-1");
|
||||
expect(listMetadata(dirB)).toContain("projB-session-1");
|
||||
expect(listMetadata(dirB)).not.toContain("projA-session-1");
|
||||
|
||||
// Cleanup
|
||||
deleteMetadata(dirA, "projA-session-1", false);
|
||||
deleteMetadata(dirB, "projB-session-1", false);
|
||||
});
|
||||
});
|
||||
|
|
@ -0,0 +1,336 @@
|
|||
/**
|
||||
* Integration test for metadata lifecycle — real filesystem operations.
|
||||
*
|
||||
* Tests the full metadata CRUD cycle (write, read, update, list, delete/archive)
|
||||
* and concurrent access patterns using @composio/ao-core metadata functions
|
||||
* with real filesystem I/O.
|
||||
*/
|
||||
|
||||
import { mkdtemp, rm } from "node:fs/promises";
|
||||
import { existsSync, readdirSync, readFileSync, mkdirSync } from "node:fs";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { afterAll, beforeAll, describe, expect, it } from "vitest";
|
||||
import {
|
||||
writeMetadata,
|
||||
readMetadata,
|
||||
readMetadataRaw,
|
||||
updateMetadata,
|
||||
deleteMetadata,
|
||||
listMetadata,
|
||||
type SessionMetadata,
|
||||
} from "@composio/ao-core";
|
||||
|
||||
describe("metadata lifecycle (real filesystem)", () => {
|
||||
let tmpDir: string;
|
||||
|
||||
beforeAll(async () => {
|
||||
tmpDir = await mkdtemp(join(tmpdir(), "ao-meta-lifecycle-"));
|
||||
});
|
||||
|
||||
afterAll(async () => {
|
||||
if (tmpDir) {
|
||||
await rm(tmpDir, { recursive: true, force: true }).catch(() => {});
|
||||
}
|
||||
});
|
||||
|
||||
it("write + read round-trip preserves all fields", () => {
|
||||
const sessionsDir = join(tmpDir, "test-roundtrip");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
const metadata: SessionMetadata = {
|
||||
worktree: "/tmp/wt/session-1",
|
||||
branch: "feat/INT-100",
|
||||
status: "working",
|
||||
tmuxName: "abc123-session-1",
|
||||
issue: "INT-100",
|
||||
pr: "https://github.com/org/repo/pull/42",
|
||||
summary: "Implementing feature INT-100",
|
||||
project: "my-project",
|
||||
createdAt: "2026-01-01T00:00:00.000Z",
|
||||
dashboardPort: 4000,
|
||||
};
|
||||
|
||||
writeMetadata(sessionsDir, "session-1", metadata);
|
||||
const result = readMetadata(sessionsDir, "session-1");
|
||||
|
||||
expect(result).not.toBeNull();
|
||||
expect(result!.worktree).toBe(metadata.worktree);
|
||||
expect(result!.branch).toBe(metadata.branch);
|
||||
expect(result!.status).toBe(metadata.status);
|
||||
expect(result!.tmuxName).toBe(metadata.tmuxName);
|
||||
expect(result!.issue).toBe(metadata.issue);
|
||||
expect(result!.pr).toBe(metadata.pr);
|
||||
expect(result!.summary).toBe(metadata.summary);
|
||||
expect(result!.project).toBe(metadata.project);
|
||||
expect(result!.createdAt).toBe(metadata.createdAt);
|
||||
expect(result!.dashboardPort).toBe(4000);
|
||||
});
|
||||
|
||||
it("readMetadataRaw returns all key-value pairs", () => {
|
||||
const sessionsDir = join(tmpDir, "test-raw");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
writeMetadata(sessionsDir, "session-raw", {
|
||||
worktree: "/w",
|
||||
branch: "main",
|
||||
status: "idle",
|
||||
project: "proj",
|
||||
});
|
||||
|
||||
const raw = readMetadataRaw(sessionsDir, "session-raw");
|
||||
expect(raw).not.toBeNull();
|
||||
expect(raw!["worktree"]).toBe("/w");
|
||||
expect(raw!["branch"]).toBe("main");
|
||||
expect(raw!["status"]).toBe("idle");
|
||||
expect(raw!["project"]).toBe("proj");
|
||||
});
|
||||
|
||||
it("read returns null for non-existent session", () => {
|
||||
const sessionsDir = join(tmpDir, "test-nonexistent");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
const result = readMetadata(sessionsDir, "no-such-session");
|
||||
expect(result).toBeNull();
|
||||
});
|
||||
|
||||
it("updateMetadata merges fields into existing file", () => {
|
||||
const sessionsDir = join(tmpDir, "test-update");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
writeMetadata(sessionsDir, "session-upd", {
|
||||
worktree: "/w",
|
||||
branch: "feat/x",
|
||||
status: "spawning",
|
||||
project: "proj",
|
||||
});
|
||||
|
||||
updateMetadata(sessionsDir, "session-upd", {
|
||||
status: "working",
|
||||
pr: "https://github.com/org/repo/pull/99",
|
||||
});
|
||||
|
||||
const result = readMetadata(sessionsDir, "session-upd");
|
||||
expect(result!.status).toBe("working");
|
||||
expect(result!.pr).toBe("https://github.com/org/repo/pull/99");
|
||||
// Original fields preserved
|
||||
expect(result!.worktree).toBe("/w");
|
||||
expect(result!.branch).toBe("feat/x");
|
||||
expect(result!.project).toBe("proj");
|
||||
});
|
||||
|
||||
it("updateMetadata removes keys set to empty string", () => {
|
||||
const sessionsDir = join(tmpDir, "test-remove-key");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
writeMetadata(sessionsDir, "session-rmk", {
|
||||
worktree: "/w",
|
||||
branch: "main",
|
||||
status: "working",
|
||||
summary: "Remove me",
|
||||
});
|
||||
|
||||
updateMetadata(sessionsDir, "session-rmk", {
|
||||
summary: "",
|
||||
});
|
||||
|
||||
const raw = readMetadataRaw(sessionsDir, "session-rmk");
|
||||
expect(raw!["summary"]).toBeUndefined();
|
||||
expect(raw!["worktree"]).toBe("/w");
|
||||
});
|
||||
|
||||
it("updateMetadata creates file if it does not exist", () => {
|
||||
const sessionsDir = join(tmpDir, "test-update-create");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
updateMetadata(sessionsDir, "session-new", {
|
||||
worktree: "/w",
|
||||
branch: "main",
|
||||
status: "spawning",
|
||||
});
|
||||
|
||||
const result = readMetadata(sessionsDir, "session-new");
|
||||
expect(result).not.toBeNull();
|
||||
expect(result!.status).toBe("spawning");
|
||||
});
|
||||
|
||||
it("listMetadata returns session IDs, excluding archive directory", () => {
|
||||
const sessionsDir = join(tmpDir, "test-list");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
writeMetadata(sessionsDir, "session-a", { worktree: "/a", branch: "a", status: "idle" });
|
||||
writeMetadata(sessionsDir, "session-b", { worktree: "/b", branch: "b", status: "working" });
|
||||
writeMetadata(sessionsDir, "session-c", { worktree: "/c", branch: "c", status: "done" });
|
||||
|
||||
const ids = listMetadata(sessionsDir);
|
||||
expect(ids).toContain("session-a");
|
||||
expect(ids).toContain("session-b");
|
||||
expect(ids).toContain("session-c");
|
||||
expect(ids).not.toContain("archive");
|
||||
});
|
||||
|
||||
it("deleteMetadata with archive=true moves file to archive/", () => {
|
||||
const sessionsDir = join(tmpDir, "test-archive");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
writeMetadata(sessionsDir, "session-del", {
|
||||
worktree: "/w",
|
||||
branch: "main",
|
||||
status: "working",
|
||||
});
|
||||
|
||||
expect(existsSync(join(sessionsDir, "session-del"))).toBe(true);
|
||||
|
||||
deleteMetadata(sessionsDir, "session-del", true);
|
||||
|
||||
// Original file removed
|
||||
expect(existsSync(join(sessionsDir, "session-del"))).toBe(false);
|
||||
|
||||
// Archive created
|
||||
const archiveDir = join(sessionsDir, "archive");
|
||||
expect(existsSync(archiveDir)).toBe(true);
|
||||
const archived = readdirSync(archiveDir);
|
||||
expect(archived.length).toBe(1);
|
||||
expect(archived[0]).toMatch(/^session-del_/);
|
||||
|
||||
// Archive content matches original
|
||||
const content = readFileSync(join(archiveDir, archived[0]), "utf-8");
|
||||
expect(content).toContain("worktree=/w");
|
||||
expect(content).toContain("branch=main");
|
||||
});
|
||||
|
||||
it("deleteMetadata with archive=false permanently removes file", () => {
|
||||
const sessionsDir = join(tmpDir, "test-permanent-delete");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
writeMetadata(sessionsDir, "session-gone", {
|
||||
worktree: "/w",
|
||||
branch: "main",
|
||||
status: "done",
|
||||
});
|
||||
|
||||
deleteMetadata(sessionsDir, "session-gone", false);
|
||||
|
||||
expect(existsSync(join(sessionsDir, "session-gone"))).toBe(false);
|
||||
expect(existsSync(join(sessionsDir, "archive"))).toBe(false);
|
||||
});
|
||||
|
||||
it("deleteMetadata is a no-op for non-existent session", () => {
|
||||
const sessionsDir = join(tmpDir, "test-delete-noop");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
// Should not throw
|
||||
deleteMetadata(sessionsDir, "no-such-session", true);
|
||||
deleteMetadata(sessionsDir, "no-such-session", false);
|
||||
});
|
||||
|
||||
it("validates session ID rejects path traversal attempts", () => {
|
||||
const sessionsDir = join(tmpDir, "test-validation");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
expect(() => readMetadata(sessionsDir, "../escape")).toThrow("Invalid session ID");
|
||||
expect(() => readMetadata(sessionsDir, "foo/bar")).toThrow("Invalid session ID");
|
||||
expect(() => readMetadata(sessionsDir, "foo bar")).toThrow("Invalid session ID");
|
||||
});
|
||||
|
||||
describe("concurrent access patterns", () => {
|
||||
it("concurrent writes to different sessions do not interfere", async () => {
|
||||
const sessionsDir = join(tmpDir, "test-concurrent-different");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
// Write 20 sessions concurrently
|
||||
const count = 20;
|
||||
const promises = Array.from({ length: count }, (_, i) =>
|
||||
Promise.resolve().then(() => {
|
||||
writeMetadata(sessionsDir, `concurrent-${i}`, {
|
||||
worktree: `/w/${i}`,
|
||||
branch: `branch-${i}`,
|
||||
status: "working",
|
||||
issue: `ISSUE-${i}`,
|
||||
});
|
||||
}),
|
||||
);
|
||||
|
||||
await Promise.all(promises);
|
||||
|
||||
// Verify all sessions were written correctly
|
||||
const ids = listMetadata(sessionsDir);
|
||||
expect(ids.length).toBe(count);
|
||||
|
||||
for (let i = 0; i < count; i++) {
|
||||
const meta = readMetadata(sessionsDir, `concurrent-${i}`);
|
||||
expect(meta).not.toBeNull();
|
||||
expect(meta!.worktree).toBe(`/w/${i}`);
|
||||
expect(meta!.branch).toBe(`branch-${i}`);
|
||||
expect(meta!.issue).toBe(`ISSUE-${i}`);
|
||||
}
|
||||
});
|
||||
|
||||
it("concurrent updates to the same session preserve last-write wins", async () => {
|
||||
const sessionsDir = join(tmpDir, "test-concurrent-same");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
// Create initial session
|
||||
writeMetadata(sessionsDir, "shared-session", {
|
||||
worktree: "/w",
|
||||
branch: "main",
|
||||
status: "spawning",
|
||||
});
|
||||
|
||||
// Rapidly update the same session from multiple "tasks"
|
||||
const updates = Array.from({ length: 10 }, (_, i) =>
|
||||
Promise.resolve().then(() => {
|
||||
updateMetadata(sessionsDir, "shared-session", {
|
||||
status: `status-${i}`,
|
||||
summary: `Update ${i}`,
|
||||
});
|
||||
}),
|
||||
);
|
||||
|
||||
await Promise.all(updates);
|
||||
|
||||
// Verify the file is valid (not corrupted)
|
||||
const result = readMetadata(sessionsDir, "shared-session");
|
||||
expect(result).not.toBeNull();
|
||||
expect(result!.worktree).toBe("/w");
|
||||
expect(result!.branch).toBe("main");
|
||||
// Status should be one of the updates (last-write-wins)
|
||||
expect(result!.status).toMatch(/^status-\d$/);
|
||||
expect(result!.summary).toMatch(/^Update \d$/);
|
||||
});
|
||||
});
|
||||
|
||||
describe("dashboardPort serialization", () => {
|
||||
it("preserves dashboardPort through write/read cycle", () => {
|
||||
const sessionsDir = join(tmpDir, "test-dashboard-port");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
writeMetadata(sessionsDir, "port-session", {
|
||||
worktree: "/w",
|
||||
branch: "main",
|
||||
status: "working",
|
||||
dashboardPort: 4567,
|
||||
});
|
||||
|
||||
const result = readMetadata(sessionsDir, "port-session");
|
||||
expect(result!.dashboardPort).toBe(4567);
|
||||
});
|
||||
|
||||
it("omits dashboardPort when undefined", () => {
|
||||
const sessionsDir = join(tmpDir, "test-no-dashboard-port");
|
||||
mkdirSync(sessionsDir, { recursive: true });
|
||||
|
||||
writeMetadata(sessionsDir, "no-port-session", {
|
||||
worktree: "/w",
|
||||
branch: "main",
|
||||
status: "working",
|
||||
});
|
||||
|
||||
const raw = readMetadataRaw(sessionsDir, "no-port-session");
|
||||
expect(raw!["dashboardPort"]).toBeUndefined();
|
||||
|
||||
const result = readMetadata(sessionsDir, "no-port-session");
|
||||
expect(result!.dashboardPort).toBeUndefined();
|
||||
});
|
||||
});
|
||||
});
|
||||
|
|
@ -730,7 +730,6 @@ function createClaudeCodeAgent(): Agent {
|
|||
const hookScriptPath = join(session.workspacePath, ".claude", "metadata-updater.sh");
|
||||
await setupHookInWorkspace(session.workspacePath, hookScriptPath);
|
||||
},
|
||||
|
||||
};
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
"type": "module",
|
||||
"scripts": {
|
||||
"dev": "concurrently \"npm:dev:next\" \"npm:dev:terminal\" \"npm:dev:direct-terminal\"",
|
||||
"dev:next": "next dev",
|
||||
"dev:next": "next dev -p ${PORT:-3000}",
|
||||
"dev:terminal": "tsx watch server/terminal-websocket.ts",
|
||||
"dev:direct-terminal": "tsx watch server/direct-terminal-ws.ts",
|
||||
"build": "next build",
|
||||
|
|
|
|||
|
|
@ -0,0 +1,42 @@
|
|||
# Integration test environment - simulates fresh developer machine
|
||||
FROM node:20-bookworm
|
||||
|
||||
# Install dependencies that a typical developer would have
|
||||
RUN apt-get update && apt-get install -y \
|
||||
git \
|
||||
tmux \
|
||||
curl \
|
||||
jq \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Install pnpm globally (typically installed by developer)
|
||||
RUN npm install -g pnpm
|
||||
|
||||
# Install GitHub CLI (common for developers working with GitHub)
|
||||
RUN curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg \
|
||||
&& chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg \
|
||||
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
|
||||
&& apt-get update \
|
||||
&& apt-get install gh -y \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Set up working directory
|
||||
WORKDIR /workspace
|
||||
|
||||
# Copy the entire repo (simulates git clone)
|
||||
COPY . /workspace/agent-orchestrator
|
||||
|
||||
# Create a test user (simulates developer's home directory)
|
||||
RUN useradd -m -s /bin/bash testuser
|
||||
|
||||
# Configure npm to use user-local prefix (no sudo needed for npm link)
|
||||
RUN mkdir -p /home/testuser/.npm-global && \
|
||||
chown -R testuser:testuser /home/testuser/.npm-global
|
||||
USER testuser
|
||||
RUN npm config set prefix '/home/testuser/.npm-global'
|
||||
ENV PATH="/home/testuser/.npm-global/bin:$PATH"
|
||||
|
||||
WORKDIR /home/testuser
|
||||
|
||||
# Entry point will be the test script
|
||||
CMD ["/bin/bash"]
|
||||
|
|
@ -0,0 +1,24 @@
|
|||
version: '3.8'
|
||||
|
||||
services:
|
||||
onboarding-test:
|
||||
build:
|
||||
context: ../..
|
||||
dockerfile: tests/integration/Dockerfile
|
||||
container_name: ao-onboarding-test
|
||||
command: /workspace/agent-orchestrator/tests/integration/onboarding-test.sh
|
||||
environment:
|
||||
- NODE_ENV=test
|
||||
- CI=true
|
||||
# Mount the repo for live development (optional)
|
||||
volumes:
|
||||
- ../..:/workspace/agent-orchestrator
|
||||
# Expose ports for debugging (optional)
|
||||
# Use 9000/9001/9003 on host to avoid conflicts with orchestrator
|
||||
# Container still uses 9000/3001/3003 internally
|
||||
ports:
|
||||
- "9000:9000" # Dashboard (host:container)
|
||||
- "9001:3001" # Terminal WebSocket (host:container)
|
||||
- "9003:3003" # DirectTerminal WebSocket (host:container)
|
||||
# Increase shared memory for browser-based tests (future)
|
||||
shm_size: 2gb
|
||||
|
|
@ -0,0 +1,207 @@
|
|||
#!/bin/bash
|
||||
# Integration test: Fresh developer onboarding experience
|
||||
# Measures time and verifies each step of the onboarding flow
|
||||
|
||||
set -e
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# Timing utilities
|
||||
start_time=$(date +%s)
|
||||
step_start=0
|
||||
|
||||
start_step() {
|
||||
echo -e "\n${BLUE}▶ $1${NC}"
|
||||
step_start=$(date +%s)
|
||||
}
|
||||
|
||||
end_step() {
|
||||
local step_end=$(date +%s)
|
||||
local duration=$((step_end - step_start))
|
||||
echo -e "${GREEN}✓ $1 (${duration}s)${NC}"
|
||||
}
|
||||
|
||||
fail_step() {
|
||||
echo -e "${RED}✗ $1${NC}"
|
||||
exit 1
|
||||
}
|
||||
|
||||
# Test starts here
|
||||
echo -e "${BLUE}╔════════════════════════════════════════════════════════╗${NC}"
|
||||
echo -e "${BLUE}║ Agent Orchestrator - Onboarding Integration Test ║${NC}"
|
||||
echo -e "${BLUE}╔════════════════════════════════════════════════════════╗${NC}"
|
||||
echo ""
|
||||
|
||||
# Step 1: Simulate git clone (already done by Docker COPY, but we cd into it)
|
||||
start_step "Step 1: Navigate to repository"
|
||||
cd /workspace/agent-orchestrator || fail_step "Repository not found"
|
||||
end_step "Step 1: Repository accessible"
|
||||
|
||||
# Step 2: Run setup script
|
||||
start_step "Step 2: Running ./scripts/setup.sh"
|
||||
if ! ./scripts/setup.sh; then
|
||||
fail_step "Step 2: Setup script failed"
|
||||
fi
|
||||
end_step "Step 2: Setup completed"
|
||||
|
||||
# Step 3: Verify ao command is available
|
||||
start_step "Step 3: Verify ao command"
|
||||
if ! command -v ao &> /dev/null; then
|
||||
fail_step "Step 3: ao command not found (npm link failed?)"
|
||||
fi
|
||||
ao --version || fail_step "Step 3: ao --version failed"
|
||||
end_step "Step 3: ao command available"
|
||||
|
||||
# Step 4: Create minimal test config
|
||||
start_step "Step 4: Create test configuration"
|
||||
mkdir -p /tmp/ao-test-project
|
||||
cd /tmp/ao-test-project
|
||||
git init
|
||||
git config user.email "test@example.com"
|
||||
git config user.name "Test User"
|
||||
|
||||
cat > agent-orchestrator.yaml << 'EOF'
|
||||
dataDir: /tmp/ao-test-data
|
||||
worktreeDir: /tmp/ao-test-worktrees
|
||||
port: 9000
|
||||
|
||||
projects:
|
||||
test-project:
|
||||
repo: test/repo
|
||||
path: /tmp/ao-test-project
|
||||
defaultBranch: main
|
||||
EOF
|
||||
|
||||
end_step "Step 4: Configuration created"
|
||||
|
||||
# Step 5: Verify config is valid
|
||||
start_step "Step 5: Validate configuration"
|
||||
# ao init would fail if run again, so we just verify the file is readable
|
||||
if [ ! -f agent-orchestrator.yaml ]; then
|
||||
fail_step "Step 5: Config file not found"
|
||||
fi
|
||||
end_step "Step 5: Configuration validated"
|
||||
|
||||
# Step 6: Start orchestrator (in background)
|
||||
start_step "Step 6: Start orchestrator"
|
||||
# Start in background and capture PID
|
||||
ao start --no-orchestrator & # Only start dashboard, not the orchestrator session
|
||||
DASHBOARD_PID=$!
|
||||
|
||||
# Wait for dashboard to be ready (max 30 seconds)
|
||||
echo " Waiting for dashboard to start..."
|
||||
for i in {1..30}; do
|
||||
if curl -s http://localhost:9000 > /dev/null 2>&1; then
|
||||
break
|
||||
fi
|
||||
if ! kill -0 $DASHBOARD_PID 2>/dev/null; then
|
||||
fail_step "Step 6: Dashboard process died"
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
|
||||
if ! curl -s http://localhost:9000 > /dev/null 2>&1; then
|
||||
fail_step "Step 6: Dashboard not responding after 30s"
|
||||
fi
|
||||
|
||||
end_step "Step 6: Dashboard started successfully"
|
||||
|
||||
# Step 7: Verify dashboard endpoints
|
||||
start_step "Step 7: Verify dashboard API"
|
||||
|
||||
# Test /api/sessions endpoint
|
||||
if ! curl -sf http://localhost:9000/api/sessions > /dev/null; then
|
||||
fail_step "Step 7: /api/sessions endpoint failed"
|
||||
fi
|
||||
|
||||
# Test SSE events endpoint (just verify it responds, don't wait for events)
|
||||
if ! timeout 2 curl -sf http://localhost:9000/api/events > /dev/null 2>&1; then
|
||||
# SSE might timeout, that's ok - we just want to verify it exists
|
||||
:
|
||||
fi
|
||||
|
||||
end_step "Step 7: Dashboard API responding"
|
||||
|
||||
# Step 8: Verify WebSocket terminal servers
|
||||
start_step "Step 8: Verify WebSocket servers"
|
||||
|
||||
# Check if direct terminal WebSocket server is running (required for terminal feature)
|
||||
echo " Checking WebSocket server on port 3003..."
|
||||
max_retries=10
|
||||
for i in $(seq 1 $max_retries); do
|
||||
if curl -sf http://localhost:3003/health > /dev/null 2>&1; then
|
||||
echo " ✓ WebSocket server responding"
|
||||
break
|
||||
fi
|
||||
if [ $i -eq $max_retries ]; then
|
||||
fail_step "Step 8: WebSocket terminal server not responding (bug: ao start didn't launch all services)"
|
||||
fi
|
||||
sleep 1
|
||||
done
|
||||
|
||||
end_step "Step 8: WebSocket servers verified"
|
||||
|
||||
# Step 9: Verify orchestrator terminal page (end-to-end test)
|
||||
start_step "Step 9: Verify orchestrator terminal feature"
|
||||
|
||||
# Create orchestrator session first (so we have something to test)
|
||||
echo " Creating test orchestrator session..."
|
||||
tmux new-session -d -s test-project-orchestrator || true
|
||||
|
||||
# Write minimal metadata
|
||||
mkdir -p /tmp/ao-test-data
|
||||
cat > /tmp/ao-test-data/test-project-orchestrator << 'EOF'
|
||||
worktree=/tmp/ao-test-project
|
||||
branch=main
|
||||
status=working
|
||||
project=test-project
|
||||
EOF
|
||||
|
||||
# Test that the session detail page loads (where terminal would be)
|
||||
if ! curl -sf http://localhost:9000/sessions/test-project-orchestrator > /dev/null; then
|
||||
fail_step "Step 9: Orchestrator session page failed to load"
|
||||
fi
|
||||
|
||||
# Cleanup test session
|
||||
tmux kill-session -t test-project-orchestrator 2>/dev/null || true
|
||||
|
||||
end_step "Step 9: Orchestrator terminal page accessible"
|
||||
|
||||
# Step 10: Cleanup
|
||||
start_step "Step 10: Cleanup"
|
||||
kill $DASHBOARD_PID 2>/dev/null || true
|
||||
# Wait for process to exit
|
||||
sleep 2
|
||||
# Force kill if still running
|
||||
kill -9 $DASHBOARD_PID 2>/dev/null || true
|
||||
|
||||
# Kill any remaining Node processes (dashboard, websocket servers)
|
||||
pkill -f "node.*next.*dev" || true
|
||||
pkill -f "tsx.*terminal" || true
|
||||
|
||||
end_step "Step 10: Cleanup completed"
|
||||
|
||||
# Calculate total time
|
||||
end_time=$(date +%s)
|
||||
total_duration=$((end_time - start_time))
|
||||
|
||||
# Summary
|
||||
echo ""
|
||||
echo -e "${GREEN}╔════════════════════════════════════════════════════════╗${NC}"
|
||||
echo -e "${GREEN}║ 🎉 All Tests Passed! ║${NC}"
|
||||
echo -e "${GREEN}╔════════════════════════════════════════════════════════╗${NC}"
|
||||
echo ""
|
||||
echo -e "${BLUE}Total onboarding time: ${total_duration}s${NC}"
|
||||
echo ""
|
||||
|
||||
# Export metrics for CI
|
||||
if [ -n "$GITHUB_ACTIONS" ]; then
|
||||
echo "onboarding_time_seconds=$total_duration" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
exit 0
|
||||
|
|
@ -0,0 +1,33 @@
|
|||
#!/bin/bash
|
||||
# Quick runner for integration tests
|
||||
|
||||
set -e
|
||||
|
||||
cd "$(dirname "$0")"
|
||||
|
||||
echo "🚀 Running Agent Orchestrator onboarding integration test..."
|
||||
echo ""
|
||||
|
||||
# Build and run
|
||||
docker-compose up --build --abort-on-container-exit --exit-code-from onboarding-test
|
||||
|
||||
# Capture exit code
|
||||
EXIT_CODE=$?
|
||||
|
||||
# Cleanup
|
||||
echo ""
|
||||
echo "🧹 Cleaning up..."
|
||||
docker-compose down -v
|
||||
|
||||
if [ $EXIT_CODE -eq 0 ]; then
|
||||
echo ""
|
||||
echo "✅ Test passed!"
|
||||
exit 0
|
||||
else
|
||||
echo ""
|
||||
echo "❌ Test failed (exit code: $EXIT_CODE)"
|
||||
echo ""
|
||||
echo "To debug:"
|
||||
echo " docker-compose run --rm onboarding-test /bin/bash"
|
||||
exit $EXIT_CODE
|
||||
fi
|
||||
Loading…
Reference in New Issue