[Phase 2.5-C] Wire ReactAgent into runtime with --engine react CLI flag

[frankbria]

Summary

Connect the ReactAgent to CodeFRAME's existing runtime and CLI so users can opt in via cf work start <task-id> --execute --engine react.

Acceptance Criteria

• codeframe/core/runtime.py updated:
  • execute_agent() accepts engine parameter: "plan" (default, existing Agent) or "react" (new ReactAgent)
  • When engine="react", instantiates and runs ReactAgent instead of Agent
  • All existing runtime behavior (run lifecycle, state transitions, event emission) preserved
• codeframe/cli/app.py updated:
  • cf work start accepts --engine option (default: "plan")
  • --engine react passes through to runtime
  • Help text documents the option
• Integration test: cf work start <task-id> --execute --engine react creates a run, invokes ReactAgent, and completes
• Backward compatibility: all existing CLI behavior unchanged when --engine not specified
• All existing tests pass

Implementation Notes

• Minimal changes to runtime.py — just an if engine == "react": use ReactAgent else: use Agent branch
• The --engine flag should also work with cf work batch run (pass engine to conductor)
• Runtime's run lifecycle (start_task_run, complete_run, fail_run, block_run) is reused as-is

Dependencies

• Phase C core: [Phase 2.5-C] Implement ReactAgent core loop with system prompt builder #347 (ReactAgent must exist)

Reference

• docs/AGENT_V3_UNIFIED_PLAN.md (Architecture → High-Level Design)
• docs/REACT_AGENT_ARCHITECTURE.md (Section 7, Phase C)

[traycerai]

Plan

Observations

The codebase has a well-structured runtime and CLI architecture. The file:codeframe/core/runtime.py module contains execute_agent() which currently instantiates the plan-based Agent class. The CLI command cf work start in file:codeframe/cli/app.py calls this runtime function. For batch execution, file:codeframe/core/conductor.py spawns subprocesses that invoke cf work start --execute. The ReactAgent from issue #347 doesn't exist yet but will follow the same interface as the existing Agent (constructor parameters and run() method).

Approach

The implementation follows a minimal branching strategy: add an engine parameter that flows from CLI → runtime → agent instantiation. When engine="react", instantiate ReactAgent instead of Agent; otherwise use the existing Agent (default "plan"). This preserves all existing behavior while enabling opt-in to the new engine. The --engine flag will be added to both cf work start and cf work batch run commands, with the batch conductor passing it through to subprocess invocations.

Implementation Steps

1. Update Runtime to Support Engine Selection

File: file:codeframe/core/runtime.py

Modify the execute_agent() function (lines 591-840):

• Add engine: str = "plan" parameter to the function signature
• Add validation to ensure engine is either "plan" or "react"
• Add conditional import and instantiation logic:
  • If engine == "react": import ReactAgent from codeframe.core.react_agent and instantiate it
  • If engine == "plan": use existing Agent instantiation (default behavior)
• Ensure both agent types receive the same constructor parameters: workspace, llm_provider, dry_run, on_event, debug, verbose, fix_coordinator, output_logger, event_publisher
• Both agents should call the same run() method and return AgentState
• Preserve all existing supervisor retry logic (lines 676-802) for both engines
• Update the run logger to include engine type in the initial log entry

Key considerations:

• The ReactAgent interface must match the existing Agent interface (same constructor parameters and run() method signature)
• Error handling should remain identical for both engines
• The supervisor intervention logic applies to both engines

2. Update CLI Work Start Command

File: file:codeframe/cli/app.py

Modify the work_start command (lines 1957-2091):

• Add new CLI option:

  engine: str = typer.Option(
      "plan",
      "--engine",
      help="Agent engine: 'plan' (default) or 'react'",
  )

• Add validation to ensure engine is either "plan" or "react"
• Pass engine parameter to runtime.execute_agent() call (line 2048)
• Update help text and command docstring to document the --engine option
• Add example usage: codeframe work start abc123 --execute --engine react

3. Update Conductor for Batch Execution

File: file:codeframe/core/conductor.py

3.1 Update start_batch() function (lines 462-597)

• Add engine: str = "plan" parameter to function signature
• Store engine in the BatchRun dataclass (requires schema update - see step 3.3)
• Pass engine to _execute_serial() and _execute_parallel() functions

3.2 Update execution functions

_execute_serial() (lines 1144-1281):

• Add engine: str = "plan" parameter
• Pass engine to _execute_task_subprocess() calls (line 1189, 1197)

_execute_parallel() (lines 1283-1412):

• Add engine: str = "plan" parameter
• Pass engine to _execute_single_task() and _execute_group_parallel() calls

_execute_single_task() (lines 1414-1442+):

• Add engine: str = "plan" parameter
• Pass engine to _execute_task_subprocess() call

_execute_group_parallel() (location TBD, referenced at line 1349):

• Add engine: str = "plan" parameter
• Pass engine to _execute_task_subprocess() calls

_execute_task_subprocess() (lines 1606-1687):

• Add engine: str = "plan" parameter
• Modify command construction (lines 1624-1627) to include --engine flag:

  cmd = [
      sys.executable, "-m", "codeframe.cli.app",
      "work", "start", task_id, "--execute",
      "--engine", engine
  ]

_execute_retries() (lines 864-1142):

• Add engine: str = "plan" parameter
• Pass engine through to execution functions

resume_batch() (lines 783-863):

• Retrieve engine from the stored BatchRun object
• Pass engine to _execute_serial_resume() and other execution functions

3.3 Update BatchRun dataclass

Add engine: str = "plan" field to the BatchRun dataclass (around line 408-459)

Update database schema:

• Add engine column to batch_runs table (migration needed)
• Update _save_batch() function (lines 1689-1726) to persist engine field
• Update _row_to_batch() function (lines 1728-1741) to read engine field from database

4. Update CLI Batch Run Command

File: file:codeframe/cli/app.py

Modify the batch_run command (lines 2780-2977):

• Add new CLI option:

  engine: str = typer.Option(
      "plan",
      "--engine",
      help="Agent engine: 'plan' (default) or 'react'",
  )

• Pass engine parameter to conductor.start_batch() call (line 2917)
• Update help text and docstring to document the --engine option
• Add example usage: codeframe work batch run --all-ready --engine react

5. Database Migration

Create a migration script to add the engine column to the batch_runs table:

• Add engine TEXT DEFAULT 'plan' column to batch_runs table
• Ensure existing records default to 'plan' for backward compatibility
• Update any database initialization code to include the new column

6. Integration Testing

Create integration test: file:tests/core/test_react_engine_integration.py

Test scenarios:

1. Single task with ReactAgent: cf work start <task-id> --execute --engine react creates a run and invokes ReactAgent
2. Batch execution with ReactAgent: cf work batch run <task-ids> --engine react passes engine to all tasks
3. Backward compatibility: Commands without --engine flag use plan-based Agent (default behavior)
4. Invalid engine: Commands with invalid --engine value show appropriate error
5. Mixed execution: Verify that different batches can use different engines independently
6. Resume batch: Verify that resumed batches preserve the original engine setting

Test structure:

• Mock ReactAgent to verify it's instantiated with correct parameters
• Verify subprocess commands include --engine react flag
• Verify database persistence of engine field
• Verify all existing tests continue to pass (backward compatibility)

7. Documentation Updates

Update help text and examples:

• cf work start --help should show --engine option
• cf work batch run --help should show --engine option
• Add examples demonstrating both engines

Visual Overview

sequenceDiagram
    participant CLI as CLI (app.py)
    participant Runtime as Runtime (runtime.py)
    participant Conductor as Conductor (conductor.py)
    participant Agent as Agent/ReactAgent
    
    Note over CLI: User runs: cf work start --execute --engine react
    CLI->>Runtime: execute_agent(workspace, run, engine="react")
    Runtime->>Runtime: Validate engine parameter
    alt engine == "react"
        Runtime->>Agent: ReactAgent(workspace, llm_provider, ...)
    else engine == "plan"
        Runtime->>Agent: Agent(workspace, llm_provider, ...)
    end
    Agent->>Agent: run(task_id)
    Agent-->>Runtime: AgentState
    Runtime-->>CLI: AgentState
    
    Note over CLI: User runs: cf work batch run --engine react
    CLI->>Conductor: start_batch(workspace, task_ids, engine="react")
    Conductor->>Conductor: Store engine in BatchRun
    loop For each task
        Conductor->>CLI: subprocess: cf work start --execute --engine react
        CLI->>Runtime: execute_agent(workspace, run, engine="react")
        Runtime->>Agent: ReactAgent(...)
        Agent-->>Runtime: AgentState
        Runtime-->>CLI: AgentState
        CLI-->>Conductor: Exit code
    end
    Conductor-->>CLI: BatchRun

Loading

Dependencies

• Issue [Phase 2.5-C] Implement ReactAgent core loop with system prompt builder #347: ReactAgent implementation must exist at file:codeframe/core/react_agent.py
• ReactAgent must implement the same interface as Agent:
  • Constructor accepting: workspace, llm_provider, dry_run, on_event, debug, verbose, fix_coordinator, output_logger, event_publisher
  • run(task_id: str) -> AgentState method
  • Return AgentState with same structure as existing Agent

Backward Compatibility

All changes maintain full backward compatibility:

• Default engine="plan" preserves existing behavior
• All existing CLI commands work without modification
• All existing tests pass without changes
• Database migration adds column with default value
• Existing batch runs without engine field default to "plan"

Import In IDE

🤖 Prompt for AI Agents

## Observations

The codebase has a well-structured runtime and CLI architecture. The `file:codeframe/core/runtime.py` module contains `execute_agent()` which currently instantiates the plan-based `Agent` class. The CLI command `cf work start` in `file:codeframe/cli/app.py` calls this runtime function. For batch execution, `file:codeframe/core/conductor.py` spawns subprocesses that invoke `cf work start --execute`. The ReactAgent from issue #347 doesn't exist yet but will follow the same interface as the existing Agent (constructor parameters and `run()` method).

## Approach

The implementation follows a minimal branching strategy: add an `engine` parameter that flows from CLI → runtime → agent instantiation. When `engine="react"`, instantiate ReactAgent instead of Agent; otherwise use the existing Agent (default `"plan"`). This preserves all existing behavior while enabling opt-in to the new engine. The `--engine` flag will be added to both `cf work start` and `cf work batch run` commands, with the batch conductor passing it through to subprocess invocations.

## Implementation Steps

### 1. Update Runtime to Support Engine Selection

**File:** `file:codeframe/core/runtime.py`

Modify the `execute_agent()` function (lines 591-840):

- Add `engine: str = "plan"` parameter to the function signature
- Add validation to ensure `engine` is either `"plan"` or `"react"`
- Add conditional import and instantiation logic:
  - If `engine == "react"`: import `ReactAgent` from `codeframe.core.react_agent` and instantiate it
  - If `engine == "plan"`: use existing `Agent` instantiation (default behavior)
- Ensure both agent types receive the same constructor parameters: `workspace`, `llm_provider`, `dry_run`, `on_event`, `debug`, `verbose`, `fix_coordinator`, `output_logger`, `event_publisher`
- Both agents should call the same `run()` method and return `AgentState`
- Preserve all existing supervisor retry logic (lines 676-802) for both engines
- Update the run logger to include engine type in the initial log entry

**Key considerations:**
- The ReactAgent interface must match the existing Agent interface (same constructor parameters and `run()` method signature)
- Error handling should remain identical for both engines
- The supervisor intervention logic applies to both engines

### 2. Update CLI Work Start Command

**File:** `file:codeframe/cli/app.py`

Modify the `work_start` command (lines 1957-2091):

- Add new CLI option:
  ```python
  engine: str = typer.Option(
      "plan",
      "--engine",
      help="Agent engine: 'plan' (default) or 'react'",
  )
  ```
- Add validation to ensure `engine` is either `"plan"` or `"react"`
- Pass `engine` parameter to `runtime.execute_agent()` call (line 2048)
- Update help text and command docstring to document the `--engine` option
- Add example usage: `codeframe work start abc123 --execute --engine react`

### 3. Update Conductor for Batch Execution

**File:** `file:codeframe/core/conductor.py`

#### 3.1 Update `start_batch()` function (lines 462-597)

- Add `engine: str = "plan"` parameter to function signature
- Store `engine` in the `BatchRun` dataclass (requires schema update - see step 3.3)
- Pass `engine` to `_execute_serial()` and `_execute_parallel()` functions

#### 3.2 Update execution functions

**`_execute_serial()`** (lines 1144-1281):
- Add `engine: str = "plan"` parameter
- Pass `engine` to `_execute_task_subprocess()` calls (line 1189, 1197)

**`_execute_parallel()`** (lines 1283-1412):
- Add `engine: str = "plan"` parameter
- Pass `engine` to `_execute_single_task()` and `_execute_group_parallel()` calls

**`_execute_single_task()`** (lines 1414-1442+):
- Add `engine: str = "plan"` parameter
- Pass `engine` to `_execute_task_subprocess()` call

**`_execute_group_parallel()`** (location TBD, referenced at line 1349):
- Add `engine: str = "plan"` parameter
- Pass `engine` to `_execute_task_subprocess()` calls

**`_execute_task_subprocess()`** (lines 1606-1687):
- Add `engine: str = "plan"` parameter
- Modify command construction (lines 1624-1627) to include `--engine` flag:
  ```python
  cmd = [
      sys.executable, "-m", "codeframe.cli.app",
      "work", "start", task_id, "--execute",
      "--engine", engine
  ]
  ```

**`_execute_retries()`** (lines 864-1142):
- Add `engine: str = "plan"` parameter
- Pass `engine` through to execution functions

**`resume_batch()`** (lines 783-863):
- Retrieve `engine` from the stored `BatchRun` object
- Pass `engine` to `_execute_serial_resume()` and other execution functions

#### 3.3 Update BatchRun dataclass

Add `engine: str = "plan"` field to the `BatchRun` dataclass (around line 408-459)

Update database schema:
- Add `engine` column to `batch_runs` table (migration needed)
- Update `_save_batch()` function (lines 1689-1726) to persist `engine` field
- Update `_row_to_batch()` function (lines 1728-1741) to read `engine` field from database

### 4. Update CLI Batch Run Command

**File:** `file:codeframe/cli/app.py`

Modify the `batch_run` command (lines 2780-2977):

- Add new CLI option:
  ```python
  engine: str = typer.Option(
      "plan",
      "--engine",
      help="Agent engine: 'plan' (default) or 'react'",
  )
  ```
- Pass `engine` parameter to `conductor.start_batch()` call (line 2917)
- Update help text and docstring to document the `--engine` option
- Add example usage: `codeframe work batch run --all-ready --engine react`

### 5. Database Migration

Create a migration script to add the `engine` column to the `batch_runs` table:

- Add `engine TEXT DEFAULT 'plan'` column to `batch_runs` table
- Ensure existing records default to `'plan'` for backward compatibility
- Update any database initialization code to include the new column

### 6. Integration Testing

Create integration test: `file:tests/core/test_react_engine_integration.py`

Test scenarios:
1. **Single task with ReactAgent**: `cf work start <task-id> --execute --engine react` creates a run and invokes ReactAgent
2. **Batch execution with ReactAgent**: `cf work batch run <task-ids> --engine react` passes engine to all tasks
3. **Backward compatibility**: Commands without `--engine` flag use plan-based Agent (default behavior)
4. **Invalid engine**: Commands with invalid `--engine` value show appropriate error
5. **Mixed execution**: Verify that different batches can use different engines independently
6. **Resume batch**: Verify that resumed batches preserve the original engine setting

Test structure:
- Mock ReactAgent to verify it's instantiated with correct parameters
- Verify subprocess commands include `--engine react` flag
- Verify database persistence of engine field
- Verify all existing tests continue to pass (backward compatibility)

### 7. Documentation Updates

Update help text and examples:
- `cf work start --help` should show `--engine` option
- `cf work batch run --help` should show `--engine` option
- Add examples demonstrating both engines

## Visual Overview

```mermaid
sequenceDiagram
    participant CLI as CLI (app.py)
    participant Runtime as Runtime (runtime.py)
    participant Conductor as Conductor (conductor.py)
    participant Agent as Agent/ReactAgent
    
    Note over CLI: User runs: cf work start --execute --engine react
    CLI->>Runtime: execute_agent(workspace, run, engine="react")
    Runtime->>Runtime: Validate engine parameter
    alt engine == "react"
        Runtime->>Agent: ReactAgent(workspace, llm_provider, ...)
    else engine == "plan"
        Runtime->>Agent: Agent(workspace, llm_provider, ...)
    end
    Agent->>Agent: run(task_id)
    Agent-->>Runtime: AgentState
    Runtime-->>CLI: AgentState
    
    Note over CLI: User runs: cf work batch run --engine react
    CLI->>Conductor: start_batch(workspace, task_ids, engine="react")
    Conductor->>Conductor: Store engine in BatchRun
    loop For each task
        Conductor->>CLI: subprocess: cf work start --execute --engine react
        CLI->>Runtime: execute_agent(workspace, run, engine="react")
        Runtime->>Agent: ReactAgent(...)
        Agent-->>Runtime: AgentState
        Runtime-->>CLI: AgentState
        CLI-->>Conductor: Exit code
    end
    Conductor-->>CLI: BatchRun
```

## Dependencies

- **Issue #347**: ReactAgent implementation must exist at `file:codeframe/core/react_agent.py`
- ReactAgent must implement the same interface as Agent:
  - Constructor accepting: `workspace`, `llm_provider`, `dry_run`, `on_event`, `debug`, `verbose`, `fix_coordinator`, `output_logger`, `event_publisher`
  - `run(task_id: str) -> AgentState` method
  - Return `AgentState` with same structure as existing Agent

## Backward Compatibility

All changes maintain full backward compatibility:
- Default `engine="plan"` preserves existing behavior
- All existing CLI commands work without modification
- All existing tests pass without changes
- Database migration adds column with default value
- Existing batch runs without `engine` field default to `"plan"`

---

Execution Information

Branch: main
Commit: 99f0ea9

---

💡 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]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Related PRs

#125 - Implement WorkerAgent execute_task method [merged]
#246 - feat(agents): trigger multi-agent execution after task approval [merged]

---

🧪 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!