[Phase 4] Aider Engine Adapter

[frankbria]

Summary

Implement an AgentAdapter for Aider, allowing CodeFrame to use Aider's established code editing capabilities as an execution engine.

Parent issue: #408

Motivation

Aider is a mature, open-source AI coding assistant with strong file editing capabilities and multi-model support. It has a different interaction model (message + explicit file list) that complements CodeFrame's orchestration.

Scope

New module: core/engines/aider.py

1. AiderAdapter implementing AgentAdapter:

class AiderAdapter:
    name = "aider"
    requires_api_key = {}  # Aider manages its own API keys
    
    def execute(self, task_prompt, workspace_path, context, timeout_ms):
        # 1. Build file list from context
        # 2. Launch: aider --message <prompt> --yes-always <files>
        #    with cwd=workspace_path
        # 3. Capture output
        # 4. Parse results into AgentResult
        ...

2. Aider CLI invocation:

   • --message: task prompt from context packager
   • --yes-always: auto-confirm for automated execution
   • --no-auto-commits: let CodeFrame manage git (important!)
   • File list from context.relevant_files
   • --model: configurable (default: whatever Aider's default is)

3. Output parsing:

   • Parse Aider's output for success/failure indicators
   • Detect modified files from Aider's output or git diff
   • Extract summary from Aider's completion message

4. Configuration:

   • aider_path: path to Aider binary (default: aider)
   • aider_model: LLM model to use (optional override)
   • aider_flags: additional CLI flags

Key Design Decisions

• --no-auto-commits: Critical — CodeFrame owns the git workflow, not Aider. Aider should modify files but not commit.
• File list management: CodeFrame's context packager identifies relevant files; Aider receives them explicitly. This avoids Aider's own repo-scanning which might conflict with CodeFrame's context.
• Model agnostic: Aider supports Claude, GPT-4, etc. Let users configure which model Aider uses independently.

Acceptance Criteria

• AiderAdapter implements AgentAdapter protocol
• Aider launched with --message, --yes-always, --no-auto-commits
• Relevant files passed as arguments
• Timeout enforced
• Modified files detected after execution
• Works with cf work start <id> --execute --engine aider
• Integration test with mock Aider binary

Dependencies

• Depends on [Phase 4] Agent Adapter Protocol Definition #409 (AgentAdapter protocol)
• Depends on [Phase 4] Task Context Packager for External Agents #410 (context packager for file list)
• Requires Aider installed (pip install aider-chat)

[traycerai]

Plan

Observations

The codebase uses a clean engine-dispatch pattern in file:codeframe/core/runtime.py's execute_agent() function: an engine string parameter selects between "react" (ReactAgent) and "plan" (Agent). The valid_engines tuple is the single registration point. The --engine flag flows from file:codeframe/cli/app.py → runtime.execute_agent() → engine instantiation. No AgentAdapter protocol exists yet — the ticket references a future abstraction (#409), which isn't merged. The codebase manages subprocess.Popen directly in file:codeframe/core/executor.py, file:codeframe/core/conductor.py, and file:codeframe/core/agent.py. TaskContext.relevant_files is a list[FileInfo] from file:codeframe/core/context.py.

Approach

Since the AgentAdapter protocol (#409) is not yet in the codebase, AiderAdapter will follow the same ad-hoc engine-dispatch pattern already used for "react" and "plan" engines. A new module codeframe/core/engines/aider.py houses the adapter class; runtime.execute_agent() dispatches to it when engine="aider" is passed; and the CLI's --engine help text is updated. This keeps the diff minimal, consistent with existing patterns, and avoids speculative abstraction.

Implementation Steps

1. Create file:codeframe/core/engines/__init__.py

Create an empty __init__.py to make codeframe/core/engines/ a proper Python package.

---

2. Create file:codeframe/core/engines/aider.py — AiderAdapter

Define a class AiderAdapter with the following responsibilities:

• Constructor: Accept workspace, verbose, on_event, and output_logger parameters matching the pattern used by ReactAgent in runtime.execute_agent(). Add optional config parameters: aider_path (str, default "aider"), aider_model (str, optional), aider_flags (list[str], default empty).

  Read aider_path, aider_model, and aider_flags from environment variables (CODEFRAME_AIDER_PATH, CODEFRAME_AIDER_MODEL, CODEFRAME_AIDER_EXTRA_FLAGS) as fallbacks, following the same env-override pattern used by ModelSelector in file:codeframe/adapters/llm/base.py.

• run(task_id: str) -> AgentStatus: Main entry point matching ReactAgent.run()'s signature.

  1. Load TaskContext via ContextLoader (already used by both existing engines) to get the task prompt via context.to_prompt_context() and the file list from context.relevant_files.
  2. Build the Aider CLI command:
     • Binary: resolved via shutil.which(aider_path) — raise a clear RuntimeError with install instructions if not found.
     • Flags: --message <prompt>, --yes-always, --no-auto-commits.
     • Optionally append --model <aider_model> when configured.
     • Append any aider_flags extras.
     • Append the list of relative file paths from context.relevant_files (using FileInfo.path).
  3. Enforce timeout_ms (derived from the run's context or a default): use subprocess.Popen with cwd=workspace.repo_path. Call process.wait(timeout=timeout_seconds). On subprocess.TimeoutExpired, terminate the process and return AgentStatus.FAILED.
  4. Capture combined stdout/stderr via PIPE and write lines to output_logger (matching ReactAgent's logging pattern).
  5. Parse result: Inspect return code and output for success/failure indicators. Aider exits 0 on success. Scan output for known failure strings (e.g., "Aider was unable", "Error:") to distinguish hard failures. Return AgentStatus.COMPLETED on success, AgentStatus.FAILED otherwise.
  6. Emit agent events via on_event callback at start/completion (matching the pattern in execute_agent()).

---

3. Update file:codeframe/core/runtime.py — Register "aider" engine

In execute_agent():

• Expand valid_engines tuple: ("plan", "react", "aider").
• Remove the ANTHROPIC_API_KEY guard when engine == "aider" (Aider manages its own API keys). Restructure the key check to only apply for "plan" and "react".
• Add an elif engine == "aider": branch that imports and instantiates AiderAdapter from codeframe.core.engines.aider, calls .run(run.task_id), and wraps the returned AgentStatus in an AgentState(status=...) — identical to the "react" branch wrapping pattern.

sequenceDiagram
    participant CLI as cli/app.py work_start
    participant RT as runtime.execute_agent()
    participant AA as AiderAdapter.run()
    participant AiderCLI as aider (subprocess)

    CLI->>RT: execute_agent(workspace, run, engine="aider")
    RT->>AA: AiderAdapter(...).run(task_id)
    AA->>AA: ContextLoader.load(task_id) → TaskContext
    AA->>AiderCLI: Popen([aider, --message, ..., --yes-always, --no-auto-commits, <files>], cwd=workspace.repo_path)
    AiderCLI-->>AA: stdout/stderr + returncode
    AA-->>RT: AgentStatus.COMPLETED / FAILED
    RT-->>CLI: AgentState(status=...)

---

4. Update file:codeframe/cli/app.py — Extend --engine help text

In work_start(), update the --engine option's help string from the current two-option description to include 'aider' as a valid third option. No other CLI changes are required — the value propagates unchanged to runtime.execute_agent().

---

5. Update file:codeframe/core/conductor.py — Propagate "aider" in batch execution

In _execute_task_subprocess(), the command built as ["cf", "work", "start", task_id, "--execute", "--engine", engine] already passes the engine string through transparently — no code change needed there. However, verify the docstring on start_batch() lists "aider" as a valid engine value to keep documentation accurate.

---

6. Update file:codeframe/ui/routers/tasks_v2.py — Allow "aider" in API engine field

The Literal["plan", "react"] type annotation on the engine field in the batch/start request models must be updated to Literal["plan", "react", "aider"] so the FastAPI server accepts it without a 422 validation error.

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase uses a clean engine-dispatch pattern in `file:codeframe/core/runtime.py`'s `execute_agent()` function: an `engine` string parameter selects between `"react"` (`ReactAgent`) and `"plan"` (`Agent`). The `valid_engines` tuple is the single registration point. The `--engine` flag flows from `file:codeframe/cli/app.py` → `runtime.execute_agent()` → engine instantiation. No `AgentAdapter` protocol exists yet — the ticket references a future abstraction (#409), which isn't merged. The codebase manages `subprocess.Popen` directly in `file:codeframe/core/executor.py`, `file:codeframe/core/conductor.py`, and `file:codeframe/core/agent.py`. `TaskContext.relevant_files` is a `list[FileInfo]` from `file:codeframe/core/context.py`.

## Approach

Since the `AgentAdapter` protocol (#409) is not yet in the codebase, `AiderAdapter` will follow the same ad-hoc engine-dispatch pattern already used for `"react"` and `"plan"` engines. A new module `codeframe/core/engines/aider.py` houses the adapter class; `runtime.execute_agent()` dispatches to it when `engine="aider"` is passed; and the CLI's `--engine` help text is updated. This keeps the diff minimal, consistent with existing patterns, and avoids speculative abstraction.

## Implementation Steps

### 1. Create `file:codeframe/core/engines/__init__.py`

Create an empty `__init__.py` to make `codeframe/core/engines/` a proper Python package.

---

### 2. Create `file:codeframe/core/engines/aider.py` — `AiderAdapter`

Define a class `AiderAdapter` with the following responsibilities:

- **Constructor**: Accept `workspace`, `verbose`, `on_event`, and `output_logger` parameters matching the pattern used by `ReactAgent` in `runtime.execute_agent()`. Add optional config parameters: `aider_path` (str, default `"aider"`), `aider_model` (str, optional), `aider_flags` (list[str], default empty).

  Read `aider_path`, `aider_model`, and `aider_flags` from environment variables (`CODEFRAME_AIDER_PATH`, `CODEFRAME_AIDER_MODEL`, `CODEFRAME_AIDER_EXTRA_FLAGS`) as fallbacks, following the same env-override pattern used by `ModelSelector` in `file:codeframe/adapters/llm/base.py`.

- **`run(task_id: str) -> AgentStatus`**: Main entry point matching `ReactAgent.run()`'s signature.
  1. Load `TaskContext` via `ContextLoader` (already used by both existing engines) to get the task prompt via `context.to_prompt_context()` and the file list from `context.relevant_files`.
  2. Build the Aider CLI command:
     - Binary: resolved via `shutil.which(aider_path)` — raise a clear `RuntimeError` with install instructions if not found.
     - Flags: `--message <prompt>`, `--yes-always`, `--no-auto-commits`.
     - Optionally append `--model <aider_model>` when configured.
     - Append any `aider_flags` extras.
     - Append the list of relative file paths from `context.relevant_files` (using `FileInfo.path`).
  3. Enforce `timeout_ms` (derived from the run's context or a default): use `subprocess.Popen` with `cwd=workspace.repo_path`. Call `process.wait(timeout=timeout_seconds)`. On `subprocess.TimeoutExpired`, terminate the process and return `AgentStatus.FAILED`.
  4. Capture combined stdout/stderr via `PIPE` and write lines to `output_logger` (matching `ReactAgent`'s logging pattern).
  5. **Parse result**: Inspect return code and output for success/failure indicators. Aider exits 0 on success. Scan output for known failure strings (e.g., `"Aider was unable"`, `"Error:"`) to distinguish hard failures. Return `AgentStatus.COMPLETED` on success, `AgentStatus.FAILED` otherwise.
  6. Emit agent events via `on_event` callback at start/completion (matching the pattern in `execute_agent()`).

---

### 3. Update `file:codeframe/core/runtime.py` — Register `"aider"` engine

In `execute_agent()`:

- Expand `valid_engines` tuple: `("plan", "react", "aider")`.
- Remove the `ANTHROPIC_API_KEY` guard when `engine == "aider"` (Aider manages its own API keys). Restructure the key check to only apply for `"plan"` and `"react"`.
- Add an `elif engine == "aider":` branch that imports and instantiates `AiderAdapter` from `codeframe.core.engines.aider`, calls `.run(run.task_id)`, and wraps the returned `AgentStatus` in an `AgentState(status=...)` — identical to the `"react"` branch wrapping pattern.

```
sequenceDiagram
    participant CLI as cli/app.py work_start
    participant RT as runtime.execute_agent()
    participant AA as AiderAdapter.run()
    participant AiderCLI as aider (subprocess)

    CLI->>RT: execute_agent(workspace, run, engine="aider")
    RT->>AA: AiderAdapter(...).run(task_id)
    AA->>AA: ContextLoader.load(task_id) → TaskContext
    AA->>AiderCLI: Popen([aider, --message, ..., --yes-always, --no-auto-commits, <files>], cwd=workspace.repo_path)
    AiderCLI-->>AA: stdout/stderr + returncode
    AA-->>RT: AgentStatus.COMPLETED / FAILED
    RT-->>CLI: AgentState(status=...)
```

---

### 4. Update `file:codeframe/cli/app.py` — Extend `--engine` help text

In `work_start()`, update the `--engine` option's `help` string from the current two-option description to include `'aider'` as a valid third option. No other CLI changes are required — the value propagates unchanged to `runtime.execute_agent()`.

---

### 5. Update `file:codeframe/core/conductor.py` — Propagate `"aider"` in batch execution

In `_execute_task_subprocess()`, the command built as `["cf", "work", "start", task_id, "--execute", "--engine", engine]` already passes the engine string through transparently — **no code change needed** there. However, verify the docstring on `start_batch()` lists `"aider"` as a valid engine value to keep documentation accurate.

---

### 6. Update `file:codeframe/ui/routers/tasks_v2.py` — Allow `"aider"` in API engine field

The `Literal["plan", "react"]` type annotation on the `engine` field in the batch/start request models must be updated to `Literal["plan", "react", "aider"]` so the FastAPI server accepts it without a 422 validation error.

---

Execution Information

Branch: main
Commit: 705b160

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[coderabbitai]

🔗 Related PRs

#31 - Create SDK migration implementation plan [merged]
#125 - Implement WorkerAgent execute_task method [merged]
#126 - Add token tracking to WorkerAgent execute_task method [merged]
#356 - fix: agent execution resilience + Phase 2.5 architecture research [merged]
#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[frankbria]

Replaced by OpenCode (#416) and Kilocode (#417) adapters per project direction. Aider adapter not needed.