feat: multi-agent support with registry, adapters, and CLI/MCP integration (v0.5.0)

[dean0x]

Summary

Implements pluggable multi-agent support for Backbeat (closes #67). Tasks can now be executed by different AI coding agents instead of only Claude Code.

• Agent Registry: InMemoryAgentRegistry with AgentAdapter interface for pluggable agent backends
• 3 Built-in Adapters: Claude Code, Codex CLI, Gemini CLI — each with correct CLI args, auto-accept flags, and env var handling
• BaseAgentAdapter: Abstract base class eliminates duplication across adapters (Template Method pattern)
• MCP Tools: DelegateTask accepts agent field, new ListAgents tool, agent support in ScheduleTask and CreatePipeline
• CLI: --agent/-a flag on beat run, beat schedule create, beat pipeline create; new beat agents list command
• Database: Migration v7 adds agent TEXT DEFAULT 'claude' column — backward compatible
• Task Lifecycle: Agent preserved through retry, resume, and schedule execution
• Error Handling: AGENT_NOT_FOUND and AGENT_MISCONFIGURED error codes with descriptive messages

Architecture

AgentRegistry (interface)
  └─ InMemoryAgentRegistry
       ├─ ClaudeAdapter  (claude --print --dangerously-skip-permissions --output-format json)
       ├─ CodexAdapter   (codex --quiet --full-auto)
       └─ GeminiAdapter  (gemini -sandbox false)

WorkerPool.spawn(task)
  → registry.get(task.agent ?? 'claude')
  → adapter.spawn(prompt, workingDir, taskId)

Key Design Decisions

• AgentProvider is a string union type validated at boundaries (Zod + type guard)
• Agent field is optional everywhere — defaults to 'claude' for full backward compatibility
• Each adapter encapsulates its own command, args, env filtering, and prompt transformation
• Only Claude strips nesting env vars (CLAUDECODE, CLAUDE_CODE_*) — other agents preserve their API keys
• ProcessSpawnerAdapter wraps legacy ProcessSpawner interface for test backward compat

Test plan

• Build passes (npm run build)
• Type check passes (npx tsc --noEmit)
• All 7 test groups pass (1,157+ tests, 0 failures)
• New test coverage: agent registry, all 3 adapters, domain agent field, MCP agent tools, CLI agent commands
• Backward compatibility: all pre-existing tests pass without modification
• Agent preserved through retry/resume/schedule lifecycle
• Schedule repository correctly parses agent from task_template JSON

[greptile-apps]

Confidence Score: 4/5

• Safe to merge with minor documentation/usability improvements recommended; both findings are non-blocking design notes rather than critical bugs.
• The PR architecture is solid and well-tested (1,157+ passing tests). The two findings are both low-severity: (1) a missing security warning in the MCP tool description (style/documentation), and (2) a design inconsistency where a domain field is never populated by callers but the fallback still functions correctly. Neither finding blocks functionality or introduces runtime risk. Database migration and agent resolution logic are correct. Tests cover the new agent infrastructure thoroughly.
• src/adapters/mcp-adapter.ts (add security warning to ConfigureAgent.apiKey description), src/services/schedule-manager.ts (clarify or resolve PipelineCreateRequest.agent design pattern)

Comments Outside Diff (2)

1. src/adapters/mcp-adapter.ts, line 160 (link)

   API key exposed in MCP protocol messages

   The ConfigureAgent tool's apiKey field description (here and in the OpenAPI spec around line 663) lacks a security warning. Unlike the CLI implementation (which warns users that keys passed as command-line arguments are stored in shell history), there is no equivalent notice for the MCP case where the API key will be:

   1. Visible as plaintext in MCP protocol-level logs
   2. Exposed to the calling LLM (visible in the tool's request arguments)
   3. Observable in any middleware or proxy monitoring the MCP message stream

   While the response is correctly masked (line 1531), the concern is the request body. Consider updating the description to surface this risk:

   "API key to store. Warning: the key will be visible in plain text in MCP protocol logs and to the calling model."
   

2. src/services/schedule-manager.ts, line 331 (link)

   PipelineCreateRequest.agent field is never populated by callers

   PipelineCreateRequest declares an agent field (in domain.ts line 383) intended as a pipeline-level default for steps that don't specify their own agent. However, neither the CLI nor the MCP adapter populates this field:

   • CLI (pipeline.ts line 49): steps.map((prompt) => ({ prompt, agent })) — the --agent flag is pre-baked into each step
   • MCP (mcp-adapter.ts lines 1375–1380): steps.map((s) => ({ ..., agent: (s.agent ?? data.agent) })) — pipeline-level data.agent is flattened into each step

   As a result, request.agent is always undefined when createPipeline is called in this file (line 331), making the step.agent ?? request.agent fallback unreachable in practice. The two-level hierarchy exists in the domain model but is collapsed at the caller boundaries.

   This isn't a runtime bug (the code works today), but it creates a maintenance hazard: a future caller relying only on request.agent would unknowingly bypass the per-step agents without realizing the fallback isn't guaranteed.

   Consider either:

   1. Propagating the pipeline-level agent to request.agent in callers (instead of pre-baking it into steps), or
   2. Documenting that callers must always set the agent per-step and should not rely on the request-level fallback

_{Last reviewed commit: 75ff638}

[greptile-apps]

z.enum(AGENT_PROVIDERS_TUPLE).nullable() will throw a Zod validation error for any row with an unrecognized agent value (e.g., a task created by a future version of backbeat with a new provider, or manually inserted). This makes those tasks permanently unreadable from the repository.

A more forward-compatible approach gracefully falls back to null:

Suggested change

	agent: z.enum(AGENT_PROVIDERS_TUPLE).nullable(),
	agent: z.enum(AGENT_PROVIDERS_TUPLE).nullable().catch(null),

This preserves strict typing for known providers while avoiding catastrophic parse failures on unknown values.

[dean0x]

Greptile Review Response

Addressed in bff47cd + bff518c

1. Biome formatting — auto-fixed array .join(), filter predicate collapse, trailing blank line
2. Unused imports — removed AgentRegistry import from mock fixture
3. Unnecessary null coalescing — killGracePeriodMs ?? 5000 → killGracePeriodMs (Zod default guarantees value)
4. resolveAuth() binary mismatch — now uses this.command consistently with spawn()
5. Loose key parameter — typed as 'apiKey' literal; runtime validation moved to CLI boundary
6. API key file permissions — 0o700 for dirs, 0o600 for files on all config writes
7. Help text — added agents check, agents config set/show/reset subcommands

Intentionally unchanged

z.enum() for agent column in TaskRowSchema — Strict enum validation is deliberate (commit 663a4f8). It catches data corruption early. A future agent addition would update the enum value alongside the new adapter. Weakening to .string().nullable() would bypass boundary validation.

Deferred to v0.6.0

CLI-in-PATH false positive for Gemini/Codex auth — checkAgentAuth() returns ready: true when CLI binary is found, but CLI installed ≠ authenticated for Gemini/Codex. Display already shows "CLI installed (auth not verified)". Proper per-agent auth verification (checking credential files) belongs in v0.6.0 Agent Failover scope.

[greptile-apps]

Zod enum will fail for unknown future agent values in stored JSON

z.enum(AGENT_PROVIDERS_TUPLE).optional() will throw a Zod validation error if the task_template JSON stored in the database contains an agent value that isn't in the current AGENT_PROVIDERS_TUPLE (e.g., a schedule created by a future version of Backbeat with a new provider). This will make the schedule permanently unreadable from the repository.

A safer approach is to fall back gracefully to undefined for unrecognized values:

Suggested change

	agent: z.enum(AGENT_PROVIDERS_TUPLE).optional(),
	agent: z.enum(AGENT_PROVIDERS_TUPLE).optional().catch(undefined),

Using .catch(undefined) preserves strict typing for known providers while silently falling back on unrecognized values, preventing catastrophic parse failures for schedules from newer Backbeat versions.

[greptile-apps]

which command is Unix-only — will silently break on Windows

spawnSync('which', [command]) is only available on Unix/macOS. On Windows, which does not exist — it's where. This means isCommandInPath will always return false on Windows, causing all agent adapters to fail with AGENT_MISCONFIGURED during spawn, even when the CLI binary is properly installed.

The codebase already handles Windows-specific logic elsewhere (database.ts checks process.platform === 'win32'). Consider using the same pattern here:

export function isCommandInPath(command: string): boolean {
  const isWindows = process.platform === 'win32';
  const result = spawnSync(isWindows ? 'where' : 'which', [command], { stdio: 'ignore' });
  return result.status === 0;
}

[greptile-apps]

checkAgents mixes ui.step for header and data rows

ui.step is used both for the section header ('Agent Auth Status') and for each individual row of the table. Depending on how ui.step renders (e.g. with a spinner or special prefix), the table rows will be visually indistinguishable from a step status, which may look odd. Consider using ui.info for data rows and reserving ui.step for progress indicators, consistent with how other commands structure output.

_{Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!}

[dean0x]

Greptile Round 2 — Addressed & Non-Issues

Pushed 8e02cbd with fixes for the 4 valid comments. Here's the full breakdown:

Fixed

1. Prompt flag injection (-- separator) — Claude and Codex adapters now use -- before the positional prompt arg. Prevents prompts like "--help" from being parsed as flags by the child CLI's argv parser. Gemini was already safe (uses --prompt <value>).

2. writeFileSync mode only on creation — Added chmodSync(_configFilePath, 0o600) after write to enforce permissions on pre-existing config files that may have been created with looser permissions.

3. isCommandInPath called twice per spawn — Removed the redundant check in resolveAuth(). spawn() already verifies CLI binary exists at line 94 before calling resolveAuth(), so step 3 now assumes login-based auth directly.

4. Gemini --yolo Docker sandbox — Added additionalEnv hook to BaseAgentAdapter. GeminiAdapter overrides it to inject GEMINI_SANDBOX=false, so Docker/Podman isn't required. Users who want sandbox can set GEMINI_SANDBOX=true in their environment.

Non-Issues (no action taken)

5. which is Unix-only — Project targets macOS/Linux only. No Windows support planned. Adding where.exe fallback for an unsupported platform isn't warranted.

6. ProcessSpawnerAdapter kill bypasses SIGTERM→SIGKILL — Intentional backward-compat shim (documented in file header). Delegates to injected ProcessSpawner.kill(). Will be removed when all tests migrate to mock AgentAdapters.

7. ui.step mixing header/rows — ui.step is a generic structured output line. Using it for both header and data rows is intentional and consistent with CLI output patterns.

8. agents namespace bypasses schema — Agent configs are intentionally decoupled from ConfigurationSchema. They live under agents.<provider> in config.json with their own load/save/validation. Merging into the Zod schema would couple agent extensibility to the core config system.