feat: add multi-agent support with CLI and MCP integration (v0.5.0)

[dean0x]

Summary

Adds complete multi-agent support to Backbeat (v0.5.0), enabling task delegation to Claude, Codex, Gemini, and Aider through both the MCP protocol and CLI.

Phase 1: Core Agent Abstraction Layer

• AgentProvider type system with AGENT_PROVIDERS constant and isAgentProvider type guard
• AgentAdapter interface with per-agent implementations (Claude, Codex, Gemini, Aider)
• InMemoryAgentRegistry for adapter lifecycle management
• ProcessSpawnerAdapter for backward compatibility
• Database migration adding agent column to tasks table
• Worker pool routing through AgentRegistry instead of direct spawning
• Task manager preserving agent field through retry and resume flows

Phase 2: CLI/MCP Surface and Tests

• MCP: agent field on DelegateTask, ScheduleTask, CreatePipeline schemas; new ListAgents tool
• CLI: --agent/-a flag on beat run; beat agents list command; agent in beat status output
• Propagation: Agent field flows through schedule templates and pipeline steps
• Bootstrap: All 4 agent adapters registered in production; AgentRegistry passed to MCP adapter
• Tests: 53 new tests covering agent types, registry, adapters, MCP integration, CLI parsing, and domain model

Files Changed

Area	Files
Core types	src/core/agents.ts, src/core/domain.ts
Adapters	src/implementations/claude-adapter.ts, codex-adapter.ts, gemini-adapter.ts, aider-adapter.ts
Registry	src/implementations/agent-registry.ts
MCP	src/adapters/mcp-adapter.ts
CLI	src/cli.ts, src/cli/commands/agents.ts, run.ts, status.ts, help.ts
Services	src/services/schedule-manager.ts, src/bootstrap.ts
Persistence	src/implementations/database.ts, task-repository.ts
Worker pool	src/implementations/event-driven-worker-pool.ts
Task manager	src/services/task-manager.ts

Test plan

• npm run test:core -- 345 passed (includes agents.test.ts, domain.test.ts additions)
• npm run test:adapters -- 48 passed (includes MCP adapter agent tests)
• npm run test:implementations -- 284 passed, 3 skipped (includes agent-registry, agent-adapters)
• npm run test:cli -- 122 passed (includes agent flag parsing, agents list, status display)
• npm run test:handlers -- 84 passed
• npm run test:services -- 131 passed
• npm run test:repositories -- 109 passed
• npm run test:integration -- 54 passed
• Total: 1177 tests passing, 0 failures
• Build clean with no TypeScript errors

[greptile-apps]

Greptile Summary

This PR adds comprehensive multi-agent support (v0.5.0) enabling task delegation to Claude, Codex, Gemini, and Aider through a clean abstraction layer. The implementation follows excellent architectural patterns with proper separation of concerns.

Key Changes:

• Core Abstraction: Introduced AgentProvider type, AgentAdapter interface, and AgentRegistry for pluggable agent backends
• Four Agent Adapters: Claude (with nesting prevention), Codex (--quiet --full-auto), Gemini (-sandbox false), and Aider (--yes-always --no-git)
• Database Migration: Added agent column with DEFAULT 'claude' for backward compatibility
• Field Propagation: Agent field flows through Task → WorkerPool → Retry/Resume → Schedules → Pipelines
• MCP Integration: Added agent parameter to DelegateTask/ScheduleTask/CreatePipeline tools and new ListAgents tool
• CLI Integration: Added --agent/-a flag to beat run and new beat agents list command
• Test Coverage: 1177 tests passing with comprehensive coverage of agent types, registry, adapters, MCP, CLI, and domain model

Architecture Highlights:

• Strategy pattern for swappable agent implementations without changing callers
• Result types for error handling throughout
• Dependency injection via AgentRegistry
• Backward compatible (undefined agent defaults to 'claude' at runtime)
• Environment variable stripping prevents agent nesting issues
• Proper resource cleanup via dispose methods

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation demonstrates exceptional quality: clean abstractions with proper interfaces, comprehensive test suite (1177 passing tests covering all new functionality), backward compatibility via sensible defaults, proper field propagation through all layers, no security vulnerabilities, excellent documentation, and consistent architectural patterns throughout. The code follows Result types for error handling, uses dependency injection, and includes proper resource cleanup. All changes are additive and non-breaking.
• No files require special attention - all implementations are clean and well-tested

Important Files Changed

Filename	Overview
src/core/agents.ts	Defines clean agent abstraction with AgentProvider type, AgentAdapter interface, and AgentRegistry interface - foundational types are well-designed with proper documentation
src/implementations/agent-registry.ts	Clean implementation of AgentRegistry with Map-based storage, proper error handling via Result types, and resource cleanup in dispose
src/implementations/claude-adapter.ts	Extracts Claude-specific spawn logic into AgentAdapter pattern - properly strips CLAUDECODE env vars to prevent nesting issues
src/implementations/codex-adapter.ts	Codex CLI adapter with --quiet and --full-auto flags for non-interactive mode - consistent with other adapters
src/implementations/gemini-adapter.ts	Gemini CLI adapter with -sandbox false flag for auto-accept - follows same pattern as other adapters
src/implementations/aider-adapter.ts	Aider adapter with --yes-always and --no-git flags - prevents direct git commits, consistent adapter pattern
src/implementations/event-driven-worker-pool.ts	Updated to use AgentRegistry for adapter resolution per task - properly defaults to claude when agent not specified
src/bootstrap.ts	Registers all 4 agent adapters in production, properly passes AgentRegistry to WorkerPool and MCPAdapter
src/adapters/mcp-adapter.ts	Adds agent field to DelegateTask, ScheduleTask, CreatePipeline schemas and new ListAgents tool - proper MCP integration
src/cli/commands/agents.ts	New listAgents command displays available agents with descriptions and CLI commands - simple and clear implementation
src/implementations/database.ts	Migration 7 adds agent column with DEFAULT 'claude' - ensures backward compatibility for existing tasks
src/implementations/task-repository.ts	Properly persists and loads agent field in SQL operations - includes in all SELECT/INSERT/UPDATE statements
src/services/task-manager.ts	Preserves agent field through retry and resume flows - ensures agent consistency across task lifecycle
src/services/schedule-manager.ts	Propagates agent field from schedule template to task request and through pipeline steps

Class Diagram

%%{init: {'theme': 'neutral'}}%%
classDiagram
    class AgentRegistry {
        <<interface>>
        +get(provider) Result~AgentAdapter~
        +has(provider) boolean
        +list() AgentProvider[]
        +dispose() void
    }
    
    class AgentAdapter {
        <<interface>>
        +provider: AgentProvider
        +spawn(prompt, workingDir, taskId) Result
        +kill(pid) Result
        +dispose() void
    }
    
    class InMemoryAgentRegistry {
        -adapters: Map
        +get(provider)
        +has(provider)
        +list()
        +dispose()
    }
    
    class ClaudeAdapter {
        +provider: "claude"
        +spawn()
        +kill()
        +dispose()
    }
    
    class CodexAdapter {
        +provider: "codex"
        +spawn()
        +kill()
        +dispose()
    }
    
    class GeminiAdapter {
        +provider: "gemini"
        +spawn()
        +kill()
        +dispose()
    }
    
    class AiderAdapter {
        +provider: "aider"
        +spawn()
        +kill()
        +dispose()
    }
    
    class EventDrivenWorkerPool {
        -agentRegistry: AgentRegistry
        +spawn(task)
        +kill(workerId)
    }
    
    class Task {
        +agent?: AgentProvider
        +prompt: string
        +status: TaskStatus
    }
    
    class MCPAdapter {
        -agentRegistry?: AgentRegistry
        +handleDelegateTask()
        +handleListAgents()
    }
    
    AgentRegistry <|.. InMemoryAgentRegistry
    AgentAdapter <|.. ClaudeAdapter
    AgentAdapter <|.. CodexAdapter
    AgentAdapter <|.. GeminiAdapter
    AgentAdapter <|.. AiderAdapter
    InMemoryAgentRegistry o-- AgentAdapter
    EventDrivenWorkerPool --> AgentRegistry
    EventDrivenWorkerPool --> Task
    MCPAdapter --> AgentRegistry
    Task --> AgentAdapter : routes via agent field

Loading

_{Last reviewed commit: d125b77}