- Remove developer-specific paths from JSDoc comments in integration tests
- Remove unused sessionExists and capturePane helper exports
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: implement agent plugins (claude-code, codex, aider)
Implement the Agent interface from @agent-orchestrator/core for three
AI coding tools, enabling the orchestrator to launch, detect activity,
and introspect agent sessions.
Claude Code plugin (full implementation):
- JSONL session introspection (summary, session ID, cost, last message type)
- Activity detection via terminal output pattern matching
- Process detection via tmux pane TTY → ps lookup chain
- Launch command generation with permissions/model/prompt support
Codex and Aider plugins (functional stubs):
- Launch command generation with tool-specific flags
- Process detection via TTY lookup
- Stub introspection (no JSONL support yet)
Closes INT-1329
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: address PR review — shell escaping, activity detection, tests
- Replace JSON.stringify with POSIX shell escaping (single quotes) for
all agent launch commands to prevent command injection
- Remove `unset CLAUDECODE &&` shell syntax from getLaunchCommand (breaks
execFile); moved to getEnvironment as empty string
- Fix detectActivity returning "exited" for empty pane when process is
confirmed alive — now returns "idle"
- Tighten BLOCKED_PATTERNS to specific error framing (^Error:, ENOENT:,
APIError:, etc.) to avoid false positives on code output
- Check blocked patterns before input patterns to prevent "EACCES:
permission denied" matching INPUT_PATTERNS on the word "permission"
- Remove pgrep fallback in findClaudeProcess (could match wrong session)
- Fix extractCost double-counting: prefer costUSD, fall back to
estimatedCostUsd only when costUSD is absent
- Trim ACTIVE_PATTERNS to stable indicators only
- Add comprehensive vitest tests (127 tests across 3 plugins)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: address Codex review + lint fixes
- Use `ps -eo pid,tty,args` instead of `comm` for process detection so
CLI wrappers (node, python) are correctly identified
- Coerce PID from handle.data with Number() + isFinite() to handle
string-serialized PIDs
- Fix token double-counting: prefer `usage` object, only fall back to
flat `inputTokens`/`outputTokens` when `usage` is absent
- Add `--` before Codex prompt to prevent prompts starting with `-`
from being parsed as CLI flags
- Check blocked patterns before input patterns so "EACCES: permission
denied" isn't misclassified as waiting_input
- Fix lint: merge duplicate imports, strict equality, remove non-null
assertions
- Format with prettier
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: multi-pane tmux, EPERM handling, strict process matching
Codex review iteration 1 fixes:
- Iterate all tmux pane TTYs instead of only the first — prevents
false "exited" in multi-pane sessions
- Handle EPERM from process.kill(pid, 0) as "process exists" — EPERM
means the process is alive but we lack permission to signal it
- Use word-boundary regex for process name matching — prevents false
positives on similar names like "claude-code" or paths containing
the substring
- Add tests for EPERM handling, multi-pane detection, and strict
name matching (134 tests total)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: exclude next-env.d.ts from eslint
Auto-generated Next.js type file triggers triple-slash-reference rule.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: address Bugbot review — JSON.parse guard, detectActivity pattern priority
- Guard parseJsonlFile against non-object JSON values (null, arrays,
primitives) that would cause TypeError in downstream extractors
- Split null output (non-tmux → "active") from empty output (tmux → "idle")
so non-tmux runtimes don't falsely report idle
- Reorder pattern matching: idle before blocked so stale errors in the
tmux scrollback don't mask an idle prompt
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: extract shellEscape to @agent-orchestrator/core
Move the duplicated POSIX shell-escaping utility from all three agent
plugins into packages/core/src/utils.ts and re-export from the package
entry point. Plugins now import { shellEscape } from the shared package.
Addresses Bugbot review comment on PR #5.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: add execFileAsync timeouts, use satisfies for plugin exports
- Add { timeout: 30_000 } to all execFileAsync calls (tmux, ps) per
CLAUDE.md convention to prevent hanging on stuck processes
- Replace `const plugin: PluginModule<Agent>` with inline
`export default { ... } satisfies PluginModule<Agent>` to preserve
narrow literal types on manifest fields
Addresses Bugbot review comments on PR #5.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* refactor: rename introspect → getSessionInfo, detectActivity uses JSONL
- Rename Agent.introspect() → getSessionInfo(), AgentIntrospection → AgentSessionInfo
- Claude Code detectActivity: replace tmux screen-scraping with JSONL-based
detection (file mtime + last entry type)
- Remove terminal pattern constants (ACTIVE_PATTERNS, IDLE_PATTERNS, etc.)
- Update all tests: JSONL-based activity tests, renamed introspect blocks
- waiting_input/blocked states deferred to hooks-based implementation (#16)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add OpenCode agent plugin, integration tests, and CI workflow
- Add agent-opencode plugin with getLaunchCommand, detectActivity,
isProcessRunning, getSessionInfo (27 unit tests)
- Add integration test suite for all 4 agents (claude-code, codex,
aider, opencode) using real binaries in tmux sessions
- Add GitHub Actions CI workflow for integration tests
- Add test:integration script to root package.json
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: update core test mocks — introspect → getSessionInfo + isProcessing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: address Bugbot review — Windows paths, bytesRead, hardcoded paths
- toClaudeProjectPath: handle Windows backslashes and drive letters
- readLastJsonlEntry: use bytesRead to avoid null character corruption
- Remove duplicate next-env.d.ts eslint ignore entry
- Remove hardcoded developer-specific binary paths from integration tests
- Add isProcessing limitation comments with issue references (#17-19)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
listMetadata() now validates filenames against VALID_SESSION_ID regex
before returning them, preventing readMetadataRaw() from throwing on
unexpected files in the sessions directory.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- tmux sendKeys: write temp files with mode 0o600 instead of default umask
- config: validate sessionPrefix matches [a-zA-Z0-9_-]+ (Zod schema)
- config: sanitize derived prefix from project ID to match metadata ID rules
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
When a send-to-agent reaction was configured (e.g. for ci-failed), the
reactionHandledNotify flag stayed false, causing checkSession() to also
call notifyHuman() immediately — bypassing the retry/escalation workflow.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Two bugs fixed:
1. Transitions with non-info priority (e.g. merge.completed,
review.approved, session.errored) now call notifyHuman() directly
when no reaction config handles notification. Before, these
transitions updated state silently with no human notification.
2. When agent.detectActivity() throws, sessions in stuck/needs_input
state now preserve that state instead of being coerced to "working"
by the fallback at the bottom of determineStatus().
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The event bus was over-engineered for a system with ~50 sessions. The
dashboard can read metadata files + poll GitHub directly. Remove the
EventBus interface, event-bus.ts module, and all emit/subscribe wiring
from session-manager and lifecycle-manager. The reaction engine (the
valuable part) stays — executeReaction now takes sessionId/projectId
directly instead of going through OrchestratorEvent.
Also fix listMetadata() to filter out directories (not just the
"archive" dir by name) so readMetadataRaw() can't crash on non-file
entries.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add -l flag to tmux send-keys for short messages so key-like payloads
(e.g. "Enter", "Escape") are sent as text, not interpreted as keypresses
- Prune states and reactionTrackers maps in pollAll() for sessions that
no longer appear in the session list, preventing unbounded memory growth
and stale retry counters from applying to reused session IDs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Reactions with action: "notify" bypass the auto: false gate so
merge-ready notifications fire for approved-and-green config
- All spawn failure paths now delete the reserved session metadata file
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- kill() and send() prefer handle.runtimeName over project defaults
- spawn() uses O_EXCL atomic file creation to prevent concurrent ID collisions
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- kill() uses handle.runtimeName to find the correct runtime plugin
- postCreate cleanup skips destroy when workspacePath is project root
- checkSession reads persisted metadata status on first poll after restart
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- stuck/needs_input sessions recover to working when agent is active
- Project reaction overrides merge with global defaults (not replace)
- summary.all_complete events get info priority (not action)
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- summary.all_complete reactions now execute in pollAll() after emission
- workspace.postCreate errors trigger workspace cleanup to prevent leaks
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Review fixes:
- metadata: sessionId validation to prevent path traversal
- event-bus: guard appendFileSync, remove unused import
- lifecycle-manager: fix reaction retry counting (track attempts,
clear on status transition), allow retry on send failure instead
of immediate escalation, detect killed sessions in polling loop,
map session.killed to agent-exited reaction
- session-manager: validate status against union, clean up runtime
and workspace on spawn failure, kill with default plugins when
project config is missing
Lint/format fixes:
- Remove unused imports across all test files
- Replace `Function` type with typed callback in tmux tests
- Replace require() with dynamic import() in tests
- Replace dynamic delete with object spread in metadata
- Apply prettier formatting to all files
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- metadata: validate sessionId against ^[a-zA-Z0-9_-]+$ to prevent
path traversal attacks
- lifecycle-manager: fix reaction retry/escalation to count attempts
(not just successes), escalate after maxRetries attempts; map
session.killed to agent-exited reaction (was unreachable session.exited)
- session-manager: validate status against known SessionStatus union
(default to "spawning" for unknown values); clean up workspace on
runtime creation failure to prevent resource leaks
- event-bus: guard appendFileSync in try/catch so disk errors don't
crash event emitters
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- session-manager: replace readMetadata with readMetadataRaw (no unsafe casts),
add safeJsonParse for JSON.parse guards, escapeRegex for session prefix,
explicit branch priority, convert from this-based to closure-based methods
- tmux: named buffers (load-buffer -b / paste-buffer -b -d) to prevent
global paste buffer race on concurrent sendKeys; send Escape before text
to clear partial input
- lifecycle-manager: concurrent polling with Promise.allSettled instead of
sequential for-of await, allCompleteEmitted guard to prevent repeated
summary.all_complete events, polling re-entrancy guard, safe reaction
config handling with action/auto checks
- tests: update tmux tests for Escape-first and named buffer changes
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Implement the 5 core service modules in packages/core/src/:
- metadata.ts: Flat-file key=value session metadata read/write matching
existing bash script format. Supports read, write, update, delete
(with archive), and list operations.
- event-bus.ts: In-process pub/sub with JSONL append-only persistence.
Supports typed and wildcard listeners, priority inference from event
type, filtered history queries, and a createEvent() helper.
- tmux.ts: Async wrappers around tmux commands using child_process.execFile
(no shell injection). Handles long/multiline messages via load-buffer/
paste-buffer. Covers list, create, send-keys, capture-pane, kill, and
pane TTY discovery.
- session-manager.ts: Session CRUD that orchestrates Runtime + Agent +
Workspace plugins. Full spawn pipeline (workspace → runtime → agent),
list with live runtime checks, kill with cleanup, batch cleanup checking
PR state + issue state + runtime liveness, and message delivery.
- lifecycle-manager.ts: State machine per session with configurable polling
interval. Detects status transitions, emits events, triggers configured
reactions (send-to-agent, notify, auto-merge) with retry counting and
time-based escalation. Routes notifications by priority to configured
notifier plugins.
All services implement interfaces defined in types.ts. Updated index.ts
to export all new modules.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: CI workflow handles Next.js build separately, fix web tsconfig rootDir
- Remove rootDir from web tsconfig (conflicts with Next.js generated .next/types)
- Include .next/types/**/*.ts in web tsconfig
- CI: build non-web packages first, web build allowed to soft-fail
- CI: typecheck excludes web (typechecked by next build)
- CI: test excludes web build dependency
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: remove || true from web build — bugbot caught it, web errors should fail CI
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* fix: override rootDir in web tsconfig to "." for Next.js compat
Next.js generates .next/types/ files that must be under rootDir.
Base tsconfig sets rootDir to "src", web needs "." to include both
src/ and .next/types/.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Phase 0 complete. Establishes:
- pnpm workspace with 18 packages (core, cli, web, 15 plugins)
- Complete type definitions in packages/core/src/types.ts defining
all 8 plugin slot interfaces (Runtime, Agent, Workspace, Tracker,
SCM, Notifier, Terminal) + core service interfaces
- YAML config loader with Zod validation and sensible defaults
- Plugin registry with built-in discovery
- CLAUDE.md with conventions for spawned agents
All agents can now branch from main and implement their assigned
packages against the interfaces defined in types.ts.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Maps dependency graph, identifies 7 truly independent work streams
after Phase 0 (scaffold + types), with Linear tickets and spawn
commands ready to go.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The human never polls. The system notifies the human. Two-tier event
handling: auto-handle routine issues silently, push notifications only
when human judgment is required. Escalation chains, priority-based
routing, and the dashboard is a drill-down tool, not the primary interface.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Comprehensive analysis of 16+ competing agent orchestration tools
(Gas Town, OpenHands, SWE-ReX, Par, claude-flow, etc.) and detailed
architecture design with 8-slot plugin system, session lifecycle state
machine, and human attention optimization patterns.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This file contains the shared orchestrator instructions that ship with
the repo. It's loaded explicitly via --append-system-prompt-file when
launching an orchestrator session, rather than auto-discovered as a
CLAUDE.local.md. Users can still have their own CLAUDE.local.md for
personal overrides.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Import all 18 production orchestrator scripts from ~/. These are direct
copies with hardcoded paths — generalization is the next step. Includes
CLAUDE.local.md with project overview, architecture notes, and roadmap.
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
Prateek