feat: extend ReactAgent interface to support full runtime parameters (#362)

[frankbria]

Summary

Implements #362: Extends ReactAgent to accept all 7 runtime parameters that the plan-based Agent supports, enabling full feature parity when using --engine react.

• Added dry_run, verbose, on_event, debug, output_logger, fix_coordinator parameters to ReactAgent constructor
• Implemented _verbose_print() for stdout + output logger streaming (cf work follow)
• Implemented _setup_debug_log() and _debug_log() for file-based debug logging
• Enhanced _emit() with on_event callback support (exception-safe)
• Added dry_run interception in _execute_tool_with_lint() — write tools return stub results, read tools execute normally
• Documented fix_coordinator as accepted for interface compatibility (no-op in ReAct architecture)
• Updated runtime.py to pass all parameters when engine="react" and removed the dry_run+react ValueError guard

Acceptance Criteria

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

Test Plan

• 11 new tests covering all 6 new parameters individually + combined
• All 58 ReactAgent tests passing
• All 17 ReactEngine integration tests passing
• Full v2 test suite: 1703 passed, 0 failures
• Linting clean (ruff check)

Implementation Notes

• event_publisher was already supported (from feat: phase-based event emission for ReactAgent progress reporting #364) — no changes needed
• dry_run is handled at the ReactAgent layer (in _execute_tool_with_lint) rather than modifying tools.py, keeping the change contained
• fix_coordinator is stored but not used — ReAct loop doesn't have step-based execution that would benefit from global fix coordination

Closes #362

Summary by CodeRabbit

• New Features

  • Dry-run mode enabled for the React engine
  • Verbose mode for real-time execution tracing
  • Event callback hook for observability
  • Debug logging option with optional log output

• Improvements

  • Broader runtime wiring to propagate diagnostics and dry-run behavior
  • Enhanced failure tracking and iteration/verification visibility

• Tests

  • Comprehensive tests covering verbose, debug, dry-run, events, and logging behaviors

[coderabbitai]

Walkthrough

Adds runtime observability and control to ReactAgent: constructor now accepts dry_run, verbose, on_event, debug, output_logger, fix_coordinator; runtime wiring passes these through for engine="react"; ReactAgent gains debug/verbose logging, event hooks, dry-run behavior for write tools, and accompanying tests.

Changes

Cohort / File(s)	Summary
ReactAgent implementation codeframe/core/react_agent.py	Expanded ReactAgent.__init__ with dry_run, verbose, on_event, debug, output_logger, fix_coordinator. Added private helpers _verbose_print, _setup_debug_log, _debug_log, _debug_log_path, _failure_count. Integrated verbose prints, event emission _emit, debug logging, dry-run handling for write tools, _WRITE_TOOLS/_READ_TOOLS classifications, and failure counting.
Runtime wiring codeframe/core/runtime.py	Removed guard that blocked dry_run for engine="react". Now forwards dry_run, verbose, on_event, debug, output_logger, and fix_coordinator into the ReactAgent constructor when engine is react.
Unit tests (ReactAgent) tests/core/test_react_agent.py	Added MockOutputLogger/MockEventPublisher and ~318 lines of tests covering verbose output, output_logger writes, debug log file creation, resilient on_event callbacks, dry_run blocking of write tools but allowing reads, failure_count increments, and fix_coordinator plumbing.
Integration test update tests/core/test_react_engine_integration.py	Replaced prior test that expected dry_run to be rejected for engine="react" with a test asserting dry_run is accepted and passed to ReactAgent (mocks provider/agent).

Sequence Diagram(s)

sequenceDiagram
    participant Runtime as Runtime
    participant ReactAgent as ReactAgent
    participant LLM as LLM
    participant Tool as Tool
    participant OutputLog as OutputLogger
    participant EventPub as on_event

    Runtime->>ReactAgent: instantiate(params: dry_run, verbose, debug, output_logger, on_event, ...)
    ReactAgent->>LLM: prompt / get action
    LLM-->>ReactAgent: action (tool, args)
    ReactAgent->>ReactAgent: _verbose_print / _debug_log / _emit("tool.dispatched")
    alt tool is write & dry_run == true
        ReactAgent-->>Runtime: return ToolResult(stub, skipped=true)
    else
        ReactAgent->>Tool: execute(tool,args)
        Tool-->>ReactAgent: result / error
    end
    ReactAgent->>LLM: provide tool result (and lint if applicable)
    ReactAgent->>OutputLog: write(streamed status) (if provided)
    ReactAgent->>EventPub: emit phase/tool events (if provided)
    ReactAgent-->>Runtime: final AgentStatus (including failure count)

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

• feat: wire ReactAgent into runtime with --engine react CLI flag #363: Wires ReactAgent into runtime — related because this change extends that wiring to pass the new runtime parameters.
• feat: ReactAgent core loop with system prompt builder #361: ReactAgent core loop implementation — related because this PR augments that core with observability and dry-run behavior.
• feat: language-aware per-edit lint gate in ReactAgent #366: Adjusts ReactAgent tool execution and linting — related to the dry_run and lint interaction changes in this PR.

Poem

A rabbit nibbles lines of code at night, 🐰
Dry-runs paused and debug logs alight,
Events hop out with every tool call,
Verbose whispers echo through each loop's hall,
I cheer — ReactAgent's new paws answer the byte! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title accurately and concisely summarizes the main change: extending ReactAgent to support full runtime parameters, matching the core objective.
Linked Issues check	✅ Passed	All acceptance criteria from issue #362 are met: ReactAgent accepts all required parameters (dry_run, verbose, on_event, debug, output_logger, event_publisher, fix_coordinator), runtime.py forwards all parameters when engine='react', and comprehensive tests verify each parameter's behavior.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #362: ReactAgent constructor expansion, runtime.py parameter forwarding, and comprehensive test coverage with no unrelated modifications.
Docstring Coverage	✅ Passed	Docstring coverage is 81.82% which is sufficient. The required threshold is 80.00%.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/issue-362-react-runtime-params

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

codeframe/core/react_agent.py (1)

623-633: Guard output_logger writes to prevent optional I/O from crashing runs.

output_logger.write() can raise (closed file, disk full). Since logging is auxiliary, consider swallowing errors to keep the agent resilient.

Proposed change

     if self.verbose:
         print(message)
     if self.output_logger:
-        self.output_logger.write(message + "\n")
+        try:
+            self.output_logger.write(message + "\n")
+        except Exception:
+            logger.debug("output_logger.write failed", exc_info=True)

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Extend ReactAgent runtime by adding dry_run, verbose, on_event, debug, output_logger, and fix_coordinator support and wire these through runtime.execute_agent in react_agent.py and runtime.py

ReactAgent accepts new runtime parameters, adds dry-run handling for write tools, emits verbose/debug output with optional logging and callbacks, increments failure count on gate failures, and runtime.execute_agent passes these parameters to ReactAgent. Tests cover dry-run behavior, logging, callbacks, and integration.

📍Where to Start

Start with the execute_agent flow in runtime.py, then review the ReactAgent.__init__ and ReactAgent.run changes in react_agent.py.

---

Macroscope summarized 055365d.

[claude]

Code Review: ReactAgent Runtime Parameters (PR #367)

Summary

This PR successfully implements full runtime parameter support for ReactAgent, achieving feature parity with the plan-based Agent. The implementation is well-structured, thoroughly tested, and follows the project's architectural patterns.

---

✅ Strengths

1. Excellent Test Coverage

• 11 new comprehensive tests covering all 6 parameters individually and combined
• Tests verify both positive and negative cases (e.g., verbose=True/False)
• Edge cases handled (e.g., exception safety in on_event callback)
• All 58 ReactAgent tests + 17 integration tests passing

2. Clean Architecture

• Parameters added to constructor without breaking existing functionality
• Proper separation of concerns (_verbose_print, _setup_debug_log, _debug_log)
• Follows existing patterns from the plan-based Agent (consistent API)
• Good use of TYPE_CHECKING imports to avoid circular dependencies

3. Smart Dry-Run Implementation

• Dry-run handled at ReactAgent layer (lines 536-540) rather than modifying tools.py
• Proper classification: write tools blocked, read tools allowed
• This design keeps changes localized and maintains tool abstraction

4. Documentation Quality

• Clear docstrings explaining behavior (e.g., dry_run vs read tools in _execute_tool_with_lint)
• PR description thoroughly explains implementation decisions
• fix_coordinator documented as no-op with rationale

---

🔍 Observations & Suggestions

1. Tool Classification Completeness (Minor)

Location: react_agent.py:523-524

_WRITE_TOOLS = {"edit_file", "create_file", "run_command"}
_READ_TOOLS = {"read_file", "list_files", "search_codebase", "run_tests"}

Question: Are these tool lists exhaustive? If new tools are added to tools.py, they might not be classified. Consider:

• Adding a comment indicating these lists should be kept in sync with tools.py
• Or defaulting unknown tools to "read" behavior in dry-run mode

Not a blocker, but worth considering for maintainability.

---

2. run_tests Classification (Question)

run_tests is classified as a read tool, but running tests could have side effects (e.g., creating test databases, cache files). Is this the intended behavior for dry-run mode? It might be worth:

• Documenting why run_tests is considered "safe" in dry-run
• Or moving it to a third category of "verify" tools that are handled specially

---

3. Debug Log Conditional Logic (Minor Clarity)

Location: react_agent.py:652-653

if not always and self._failure_count == 0 and level == "DEBUG":
    return

This logic skips DEBUG-level messages when there are no failures. The intent is good (reduce noise), but:

• self._failure_count is initialized but never incremented in the diff
• Consider adding a comment explaining when _failure_count gets updated
• Or verify this is carried over from existing agent.py patterns

---

4. Exception Handling in on_event (Positive Note)

Location: react_agent.py:680-683

Excellent exception safety! The callback is wrapped in try-except to prevent user code from crashing the agent. This matches the pattern for event_publisher above it.

---

5. Runtime Parameter Passing (Verification)

Location: runtime.py:678-685

The removal of the dry-run ValueError and addition of all parameters looks correct. One verification question:

• Does the plan-based Agent in runtime.py use the same on_event wrapper function (on_agent_event)? If so, excellent consistency.
• If not, consider whether both engines should use the same event forwarding pattern.

---

🔒 Security & Performance

Security

✅ No security concerns identified:

• Dry-run properly prevents write operations
• No new file I/O paths introduced that bypass existing safety checks
• Exception handling prevents user callbacks from crashing the agent

Performance

✅ No performance concerns:

• New parameters are optional with sensible defaults
• _verbose_print and _debug_log are lightweight
• Output logging uses immediate flush (good for streaming, acceptable overhead)

---

🎯 Testing Recommendations (Optional Future Work)

While test coverage is excellent, consider adding integration tests for:

1. cf work start <id> --execute --verbose --engine react (end-to-end CLI test)
2. cf work start <id> --execute --dry-run --engine react (verify no files modified)
3. Streaming with cf work follow when using ReactAgent

These would complement the existing unit tests with real-world usage patterns.

---

📋 Checklist

• ✅ Code quality: Clean, well-structured, follows project conventions
• ✅ Test coverage: Comprehensive unit tests for all new parameters
• ✅ Documentation: Clear docstrings and PR description
• ✅ Architecture: Follows headless core principles (no FastAPI imports)
• ✅ Backward compatibility: All existing tests passing
• ✅ Security: No concerns identified
• ✅ Performance: No concerns identified

---

🎉 Verdict: APPROVED with minor observations

This is high-quality work that successfully achieves the stated goals. The observations above are suggestions for future consideration, not blockers. The implementation is production-ready.

Recommendation: Merge after addressing any questions above (if applicable), or merge as-is if the team is satisfied with the current approach.

Great job on achieving feature parity between plan-based and ReAct execution engines! 🚀

[claude]

Follow-up Review ✅

I see a follow-up commit has been added since my initial review. The implementation continues to look solid and production-ready.

Key Strengths Maintained:

• ✅ Comprehensive test coverage (11 new tests + integration tests)
• ✅ Clean architecture following core-first patterns
• ✅ Proper exception handling in callbacks
• ✅ Smart dry-run implementation at the ReactAgent layer
• ✅ Full runtime parameter parity with plan-based Agent

All Prior Observations Addressed:

The implementation handles the points raised in my previous review well:

• Tool classification lists are documented to stay in sync with tools.py
• run_tests classification as a read tool is intentional (no workspace file modifications)
• Debug logging conditional logic is clear with _failure_count tracking
• Event callback exception safety matches event_publisher pattern

Test Results:

• ✅ All 58 ReactAgent tests passing
• ✅ All 17 ReactEngine integration tests passing
• ✅ Full v2 suite: 1703 passed, 0 failures
• ✅ Linting clean

Final Recommendation: ✅ APPROVED FOR MERGE

This PR successfully achieves its goal of bringing ReactAgent to full feature parity with the plan-based Agent. The code is well-tested, follows project conventions, and maintains the headless core architecture.

Great work on this implementation! 🚀