[Phase 2.5-C] Extend ReactAgent interface to support full runtime parameters

[frankbria]

Summary

The ReactAgent currently has a minimal constructor interface compared to the existing plan-based Agent. When wiring ReactAgent into the runtime (issue #348), we deliberately chose to wrap the simpler interface rather than modify ReactAgent, but this leaves 5 runtime features unsupported when using --engine react.

Missing Parameters

Parameter	Purpose	Priority
dry_run	Preview changes without applying	High
verbose	Print detailed progress to stdout	High
on_event	Emit workspace events for monitoring	Medium
debug	Write debug log to workspace	Medium
output_logger	Enable cf work follow streaming	Medium
event_publisher	Enable SSE streaming for web UI	Low
fix_coordinator	Global fix coordination for parallel execution	Low

Acceptance Criteria

• ReactAgent constructor accepts dry_run, verbose, on_event, debug, output_logger, event_publisher, fix_coordinator parameters
• Parameters that don't apply to the ReAct loop architecture are documented as no-ops or adapted to the ReAct pattern
• runtime.py passes all parameters when engine="react" (currently only passes workspace and llm_provider)
• Tests verify ReactAgent behavior with each parameter

Implementation Notes

• The ReAct loop architecture may not map 1:1 to all plan-based Agent features (e.g., fix_coordinator assumes step-based execution)
• dry_run and verbose should be straightforward to add
• on_event callbacks may need different event types for the ReAct loop (tool calls vs plan steps)
• Consider whether ReactAgent should return AgentState directly instead of AgentStatus to remove the wrapper in runtime.py

Dependencies

• [Phase 2.5-C] Wire ReactAgent into runtime with --engine react CLI flag #348 (Wire ReactAgent into runtime) — must be merged first
• [Phase 2.5-C] Implement ReactAgent core loop with system prompt builder #347 (ReactAgent core loop)

Reference

• codeframe/core/react_agent.py — ReactAgent constructor (lines 75-85)
• codeframe/core/runtime.py — execute_agent() engine branch with TODO comment

[traycerai]

Plan

Observations

The ReactAgent currently has a minimal constructor accepting only workspace, llm_provider, max_iterations, and max_verification_retries. The plan-based Agent in file:codeframe/core/agent.py (lines 393-442) accepts 7 additional runtime parameters that enable critical features like dry-run mode, verbose output, debug logging, streaming via cf work follow, SSE events for web UI, event callbacks, and global fix coordination. The ReactAgent already has an _emit() method for events (lines 466-473) but lacks the infrastructure to support the full runtime parameter set.

Approach

Extend the ReactAgent constructor to accept all 7 missing parameters, mirroring the plan-based Agent's interface. Parameters will be stored as instance variables and integrated into the ReAct loop where applicable. Some parameters (like fix_coordinator) may not map directly to the ReAct architecture and will be documented as no-ops or adapted. The dry_run parameter will be passed to tool execution, verbose and output_logger will enable progress printing, on_event will enhance the existing _emit() method, debug will enable debug logging, and event_publisher will be passed to tool execution for SSE streaming.

Implementation Steps

1. Extend ReactAgent Constructor

File: file:codeframe/core/react_agent.py (lines 75-85)

Modify the __init__ method to accept the 7 missing parameters:

• Add dry_run: bool = False parameter
• Add verbose: bool = False parameter
• Add on_event: Optional[Callable[[str, dict], None]] = None parameter
• Add debug: bool = False parameter
• Add output_logger: Optional["RunOutputLogger"] = None parameter
• Add event_publisher: Optional["EventPublisher"] = None parameter
• Add fix_coordinator: Optional["GlobalFixCoordinator"] = None parameter

Store all parameters as instance variables (e.g., self.dry_run = dry_run, etc.)

Add TYPE_CHECKING imports at the top of the file for type hints:

• Import RunOutputLogger from codeframe.core.streaming
• Import EventPublisher from codeframe.core.streaming
• Import GlobalFixCoordinator from codeframe.core.conductor
• Import Callable from typing

2. Implement Debug Logging Support

File: file:codeframe/core/react_agent.py

Add debug logging infrastructure similar to the plan-based Agent (lines 438-442 in agent.py):

• Add _debug_log_path: Optional[Path] instance variable
• Create _setup_debug_log() method that creates a timestamped log file in the workspace (.codeframe_debug_react_<timestamp>.log)
• Create _debug_log(message: str, level: str = "INFO", data: dict = None, always: bool = False) method that writes structured log entries
• Call _setup_debug_log() in __init__ when debug=True
• Add debug logging calls at key points in the ReAct loop:
  • Start of run() method
  • Each iteration in _react_loop() (line 152)
  • Tool execution in _execute_tool_with_lint() (line 374)
  • Verification attempts in _run_final_verification() (line 234)

3. Implement Verbose Output Support

File: file:codeframe/core/react_agent.py

Add verbose printing similar to the plan-based Agent (lines 444-460 in agent.py):

• Create _verbose_print(message: str) method that:
  • Prints to stdout if self.verbose is True
  • Always writes to self.output_logger if provided (for cf work follow streaming)
• Add verbose output at key milestones:
  • Task start: "Starting task {task_id}"
  • Each iteration: "Iteration {n}/{max_iterations}"
  • Tool calls: "Calling tool: {tool_name}"
  • Verification: "Running final verification..."
  • Completion: "Task completed successfully" or "Task failed"

4. Enhance Event Emission with on_event Callback

File: file:codeframe/core/react_agent.py (lines 466-473)

Modify the _emit() method to support the on_event callback:

• After calling events.emit_for_workspace(), check if self.on_event is not None
• If provided, call self.on_event(event_type, payload) to notify the runtime
• Wrap the callback in try-except to prevent callback failures from breaking the agent
• Add debug logging when callbacks are invoked (if debug mode is enabled)

5. Integrate dry_run Mode into Tool Execution

File: file:codeframe/core/react_agent.py (line 376)

Modify _execute_tool_with_lint() to respect dry-run mode:

• Pass dry_run=self.dry_run to execute_tool() call
• Update file:codeframe/core/tools.py execute_tool() function signature to accept dry_run parameter
• For write operations (edit_file, create_file), skip actual file modifications when dry_run=True
• Return a ToolResult indicating the operation would have been performed
• Ensure lint checks are skipped in dry-run mode (no file to lint)

6. Add event_publisher Support for SSE Streaming

File: file:codeframe/core/react_agent.py

Integrate event publisher for web UI streaming:

• Store self.event_publisher in constructor
• In _execute_tool_with_lint(), pass event_publisher to tool execution if the tool supports it
• Update file:codeframe/core/tools.py to accept and use event_publisher for streaming tool outputs
• Emit SSE events for:
  • Tool execution start/complete
  • Verification start/complete
  • Iteration progress

7. Document fix_coordinator as No-Op

File: file:codeframe/core/react_agent.py

Add documentation for the fix_coordinator parameter:

• In the constructor docstring, document that fix_coordinator is accepted for interface compatibility but not used in the ReAct architecture
• Explain that the ReAct loop doesn't have step-based execution like the plan-based Agent, so global fix coordination doesn't apply
• Store the parameter but don't use it in the implementation
• Add a comment: # fix_coordinator is not used in ReAct architecture (no step-based execution)

8. Update runtime.py Integration

File: file:codeframe/core/runtime.py (around line 591)

Once issue #348 is merged, update the ReactAgent instantiation to pass all parameters:

• Locate where ReactAgent is instantiated (likely in a new execute_agent() branch for engine="react")
• Pass all 7 parameters: dry_run, verbose, on_event, debug, output_logger, event_publisher, fix_coordinator
• Remove any wrapper code that was converting between ReactAgent's AgentStatus and the runtime's expected AgentState
• Consider having ReactAgent return AgentState directly instead of AgentStatus for consistency

9. Update Tests

File: file:tests/core/test_react_agent.py

Add test coverage for each new parameter:

• Test dry_run: Verify that file operations are not performed when dry_run=True
• Test verbose: Verify that progress messages are printed to stdout when verbose=True
• Test on_event: Verify that the callback is invoked for key events (started, completed, failed)
• Test debug: Verify that debug log file is created and contains expected entries
• Test output_logger: Verify that messages are written to the logger for streaming
• Test event_publisher: Verify that SSE events are published during execution
• Test fix_coordinator: Verify that it's accepted but doesn't affect behavior (no-op)

Add integration tests:

• Test ReactAgent with all parameters enabled simultaneously
• Test that ReactAgent behavior matches plan-based Agent for common scenarios (dry-run, verbose output)

10. Update Documentation

File: file:docs/REACT_AGENT_ARCHITECTURE.md

Update the architecture documentation:

• Add section on runtime parameter support (lines 1040-1051 in Appendix C)
• Document which parameters are fully supported vs. no-ops
• Add examples of using ReactAgent with different parameter combinations
• Update the migration plan (Phase C, lines 820-846) to reflect the extended interface

Parameter Mapping Summary

Parameter	Priority	Implementation	Notes
dry_run	High	Pass to tool execution	Skip file writes, return preview
verbose	High	Add _verbose_print() method	Print to stdout + output_logger
on_event	Medium	Enhance _emit() method	Call callback after event emission
debug	Medium	Add debug logging infrastructure	Create timestamped log file
output_logger	Medium	Use in _verbose_print()	Enable cf work follow streaming
event_publisher	Low	Pass to tool execution	Enable SSE for web UI
fix_coordinator	Low	Document as no-op	Not applicable to ReAct architecture

Architecture Diagram

sequenceDiagram
    participant Runtime as runtime.py
    participant ReactAgent
    participant Tools as tools.py
    participant Events as events.py
    participant Logger as output_logger
    
    Runtime->>ReactAgent: __init__(workspace, llm_provider, dry_run, verbose, on_event, debug, output_logger, event_publisher, fix_coordinator)
    ReactAgent->>ReactAgent: Store all parameters
    alt debug=True
        ReactAgent->>ReactAgent: _setup_debug_log()
    end
    
    Runtime->>ReactAgent: run(task_id)
    ReactAgent->>Events: _emit(AGENT_STARTED)
    ReactAgent->>ReactAgent: on_event callback (if provided)
    
    loop ReAct Loop
        ReactAgent->>ReactAgent: _verbose_print("Iteration N")
        alt verbose=True
            ReactAgent->>Logger: Print to stdout
        end
        ReactAgent->>Logger: Write to output_logger
        
        ReactAgent->>Tools: execute_tool(dry_run=self.dry_run)
        alt dry_run=True
            Tools-->>ReactAgent: Preview (no actual changes)
        else
            Tools-->>ReactAgent: Actual result
        end
        
        ReactAgent->>Events: _emit(TOOL_RESULT)
        ReactAgent->>ReactAgent: on_event callback
    end
    
    ReactAgent->>Events: _emit(AGENT_COMPLETED)
    ReactAgent-->>Runtime: AgentStatus

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

The ReactAgent currently has a minimal constructor accepting only `workspace`, `llm_provider`, `max_iterations`, and `max_verification_retries`. The plan-based Agent in `file:codeframe/core/agent.py` (lines 393-442) accepts 7 additional runtime parameters that enable critical features like dry-run mode, verbose output, debug logging, streaming via `cf work follow`, SSE events for web UI, event callbacks, and global fix coordination. The ReactAgent already has an `_emit()` method for events (lines 466-473) but lacks the infrastructure to support the full runtime parameter set.

## Approach

Extend the ReactAgent constructor to accept all 7 missing parameters, mirroring the plan-based Agent's interface. Parameters will be stored as instance variables and integrated into the ReAct loop where applicable. Some parameters (like `fix_coordinator`) may not map directly to the ReAct architecture and will be documented as no-ops or adapted. The `dry_run` parameter will be passed to tool execution, `verbose` and `output_logger` will enable progress printing, `on_event` will enhance the existing `_emit()` method, `debug` will enable debug logging, and `event_publisher` will be passed to tool execution for SSE streaming.

## Implementation Steps

### 1. Extend ReactAgent Constructor

**File:** `file:codeframe/core/react_agent.py` (lines 75-85)

Modify the `__init__` method to accept the 7 missing parameters:

- Add `dry_run: bool = False` parameter
- Add `verbose: bool = False` parameter  
- Add `on_event: Optional[Callable[[str, dict], None]] = None` parameter
- Add `debug: bool = False` parameter
- Add `output_logger: Optional["RunOutputLogger"] = None` parameter
- Add `event_publisher: Optional["EventPublisher"] = None` parameter
- Add `fix_coordinator: Optional["GlobalFixCoordinator"] = None` parameter

Store all parameters as instance variables (e.g., `self.dry_run = dry_run`, etc.)

Add TYPE_CHECKING imports at the top of the file for type hints:
- Import `RunOutputLogger` from `codeframe.core.streaming`
- Import `EventPublisher` from `codeframe.core.streaming`
- Import `GlobalFixCoordinator` from `codeframe.core.conductor`
- Import `Callable` from `typing`

### 2. Implement Debug Logging Support

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

Add debug logging infrastructure similar to the plan-based Agent (lines 438-442 in agent.py):

- Add `_debug_log_path: Optional[Path]` instance variable
- Create `_setup_debug_log()` method that creates a timestamped log file in the workspace (`.codeframe_debug_react_<timestamp>.log`)
- Create `_debug_log(message: str, level: str = "INFO", data: dict = None, always: bool = False)` method that writes structured log entries
- Call `_setup_debug_log()` in `__init__` when `debug=True`
- Add debug logging calls at key points in the ReAct loop:
  - Start of `run()` method
  - Each iteration in `_react_loop()` (line 152)
  - Tool execution in `_execute_tool_with_lint()` (line 374)
  - Verification attempts in `_run_final_verification()` (line 234)

### 3. Implement Verbose Output Support

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

Add verbose printing similar to the plan-based Agent (lines 444-460 in agent.py):

- Create `_verbose_print(message: str)` method that:
  - Prints to stdout if `self.verbose` is True
  - Always writes to `self.output_logger` if provided (for `cf work follow` streaming)
- Add verbose output at key milestones:
  - Task start: "Starting task {task_id}"
  - Each iteration: "Iteration {n}/{max_iterations}"
  - Tool calls: "Calling tool: {tool_name}"
  - Verification: "Running final verification..."
  - Completion: "Task completed successfully" or "Task failed"

### 4. Enhance Event Emission with on_event Callback

**File:** `file:codeframe/core/react_agent.py` (lines 466-473)

Modify the `_emit()` method to support the `on_event` callback:

- After calling `events.emit_for_workspace()`, check if `self.on_event` is not None
- If provided, call `self.on_event(event_type, payload)` to notify the runtime
- Wrap the callback in try-except to prevent callback failures from breaking the agent
- Add debug logging when callbacks are invoked (if debug mode is enabled)

### 5. Integrate dry_run Mode into Tool Execution

**File:** `file:codeframe/core/react_agent.py` (line 376)

Modify `_execute_tool_with_lint()` to respect dry-run mode:

- Pass `dry_run=self.dry_run` to `execute_tool()` call
- Update `file:codeframe/core/tools.py` `execute_tool()` function signature to accept `dry_run` parameter
- For write operations (`edit_file`, `create_file`), skip actual file modifications when `dry_run=True`
- Return a ToolResult indicating the operation would have been performed
- Ensure lint checks are skipped in dry-run mode (no file to lint)

### 6. Add event_publisher Support for SSE Streaming

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

Integrate event publisher for web UI streaming:

- Store `self.event_publisher` in constructor
- In `_execute_tool_with_lint()`, pass `event_publisher` to tool execution if the tool supports it
- Update `file:codeframe/core/tools.py` to accept and use `event_publisher` for streaming tool outputs
- Emit SSE events for:
  - Tool execution start/complete
  - Verification start/complete
  - Iteration progress

### 7. Document fix_coordinator as No-Op

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

Add documentation for the `fix_coordinator` parameter:

- In the constructor docstring, document that `fix_coordinator` is accepted for interface compatibility but not used in the ReAct architecture
- Explain that the ReAct loop doesn't have step-based execution like the plan-based Agent, so global fix coordination doesn't apply
- Store the parameter but don't use it in the implementation
- Add a comment: `# fix_coordinator is not used in ReAct architecture (no step-based execution)`

### 8. Update runtime.py Integration

**File:** `file:codeframe/core/runtime.py` (around line 591)

Once issue #348 is merged, update the ReactAgent instantiation to pass all parameters:

- Locate where ReactAgent is instantiated (likely in a new `execute_agent()` branch for `engine="react"`)
- Pass all 7 parameters: `dry_run`, `verbose`, `on_event`, `debug`, `output_logger`, `event_publisher`, `fix_coordinator`
- Remove any wrapper code that was converting between ReactAgent's `AgentStatus` and the runtime's expected `AgentState`
- Consider having ReactAgent return `AgentState` directly instead of `AgentStatus` for consistency

### 9. Update Tests

**File:** `file:tests/core/test_react_agent.py`

Add test coverage for each new parameter:

- **Test dry_run**: Verify that file operations are not performed when `dry_run=True`
- **Test verbose**: Verify that progress messages are printed to stdout when `verbose=True`
- **Test on_event**: Verify that the callback is invoked for key events (started, completed, failed)
- **Test debug**: Verify that debug log file is created and contains expected entries
- **Test output_logger**: Verify that messages are written to the logger for streaming
- **Test event_publisher**: Verify that SSE events are published during execution
- **Test fix_coordinator**: Verify that it's accepted but doesn't affect behavior (no-op)

Add integration tests:
- Test ReactAgent with all parameters enabled simultaneously
- Test that ReactAgent behavior matches plan-based Agent for common scenarios (dry-run, verbose output)

### 10. Update Documentation

**File:** `file:docs/REACT_AGENT_ARCHITECTURE.md`

Update the architecture documentation:

- Add section on runtime parameter support (lines 1040-1051 in Appendix C)
- Document which parameters are fully supported vs. no-ops
- Add examples of using ReactAgent with different parameter combinations
- Update the migration plan (Phase C, lines 820-846) to reflect the extended interface

## Parameter Mapping Summary

| Parameter | Priority | Implementation | Notes |
|-----------|----------|----------------|-------|
| `dry_run` | High | Pass to tool execution | Skip file writes, return preview |
| `verbose` | High | Add `_verbose_print()` method | Print to stdout + output_logger |
| `on_event` | Medium | Enhance `_emit()` method | Call callback after event emission |
| `debug` | Medium | Add debug logging infrastructure | Create timestamped log file |
| `output_logger` | Medium | Use in `_verbose_print()` | Enable `cf work follow` streaming |
| `event_publisher` | Low | Pass to tool execution | Enable SSE for web UI |
| `fix_coordinator` | Low | Document as no-op | Not applicable to ReAct architecture |

## Architecture Diagram

```mermaid
sequenceDiagram
    participant Runtime as runtime.py
    participant ReactAgent
    participant Tools as tools.py
    participant Events as events.py
    participant Logger as output_logger
    
    Runtime->>ReactAgent: __init__(workspace, llm_provider, dry_run, verbose, on_event, debug, output_logger, event_publisher, fix_coordinator)
    ReactAgent->>ReactAgent: Store all parameters
    alt debug=True
        ReactAgent->>ReactAgent: _setup_debug_log()
    end
    
    Runtime->>ReactAgent: run(task_id)
    ReactAgent->>Events: _emit(AGENT_STARTED)
    ReactAgent->>ReactAgent: on_event callback (if provided)
    
    loop ReAct Loop
        ReactAgent->>ReactAgent: _verbose_print("Iteration N")
        alt verbose=True
            ReactAgent->>Logger: Print to stdout
        end
        ReactAgent->>Logger: Write to output_logger
        
        ReactAgent->>Tools: execute_tool(dry_run=self.dry_run)
        alt dry_run=True
            Tools-->>ReactAgent: Preview (no actual changes)
        else
            Tools-->>ReactAgent: Actual result
        end
        
        ReactAgent->>Events: _emit(TOOL_RESULT)
        ReactAgent->>ReactAgent: on_event callback
    end
    
    ReactAgent->>Events: _emit(AGENT_COMPLETED)
    ReactAgent-->>Runtime: AgentStatus
```

---

Execution Information

Branch: main
Commit: 5a13562

---

💡 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

#37 - feat: Multi-agent per project architecture (Phases 1-5) [merged]
#361 - feat: ReactAgent core loop with system prompt builder [closed]

---

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