[Phase 2.5] Stall Detection: ReAct Agent and Runtime Integration

[frankbria]

Summary

Wire the stall detector into the ReAct agent's tool-use loop and the runtime's task execution flow.

Parent issue: #399

Scope

Changes to core/react_agent.py

1. Initialize StallDetector at the start of ReactAgent.run()
2. Call stall_detector.record_activity() after each successful tool execution
3. Check stall_detector.is_stalled() at the top of each iteration loop
4. On stall detection:
   • Log warning with elapsed time and last tool call context
   • Based on configured StallAction:
     • RETRY: raise StallDetectedError (runtime handles retry)
     • BLOCKER: create blocker with stall context, return BLOCKED
     • FAIL: return FAILED with stall reason

Changes to core/runtime.py

5. Catch StallDetectedError in execute_agent()
6. If retry configured: re-invoke agent (respecting max retry count)
7. If blocker configured: create blocker with diagnostic context:
   • Time since last activity
   • Last tool call and result
   • Current iteration count
   • Token usage so far

Changes to CLI

8. Add --stall-timeout flag to cf work start (default: 300s, 0 to disable)
9. Pass through to runtime/agent

Acceptance Criteria

• Stall detected during ReAct loop triggers configured recovery action
• --stall-timeout 120 sets custom timeout via CLI
• --stall-timeout 0 disables stall detection
• Retry action re-invokes agent with context about the stall
• Blocker action creates informative blocker
• Stall detection works correctly during batch execution
• Integration test: mock a stalled agent, verify recovery

Dependencies

• Depends on [Phase 2.5] Stall Detection: Monitor Module #400 (stall detector module)

[traycerai]

Plan

Observations

• StallDetector, StallDetectedError, and StallAction are not yet in the codebase — they're deliverables from the parent issue [Phase 2.5] Stall Detection: Monitor Module #400. This plan assumes those symbols will exist at codeframe/core/stall_detector.py.
• ReactAgent._react_loop() already tracks iterations, collects tool_results, and returns AgentStatus. The stall detector slots in cleanly around the existing per-iteration flow.
• execute_agent() in file:codeframe/core/runtime.py already instantiates ReactAgent and calls react_agent.run(), wraps the result in AgentState. It's the right place to catch StallDetectedError.
• work_start in file:codeframe/cli/app.py already accepts several typer.Option flags (--execute, --dry-run, --debug, --verbose, --engine) passed into runtime.execute_agent().
• ReactAgent.__init__ in file:codeframe/core/react_agent.py accepts named keyword arguments — adding stall_timeout follows the same pattern.

Approach

Add stall_timeout as a top-to-bottom parameter: CLI → execute_agent() → ReactAgent.__init__() → ReactAgent.run() / _react_loop(). The stall detector is initialized once in run(), updated after each successful tool round, and checked at the top of each loop iteration. execute_agent() catches StallDetectedError and dispatches the configured StallAction. No new modules or abstractions are introduced beyond what #400 defines.

---

Implementation Steps

1. Add stall_timeout parameter to ReactAgent.__init__() — file:codeframe/core/react_agent.py

In the ReactAgent.__init__() constructor (lines 104–142), add:

• A new keyword argument stall_timeout: int = 300 (seconds; 0 = disabled) after the existing parameters.
• Store it as self.stall_timeout = stall_timeout.

2. Integrate StallDetector into ReactAgent.run() — file:codeframe/core/react_agent.py

At the top of run() (just before calling _react_loop()), after the adaptive budget calculation:

• Import StallDetector, StallDetectedError, StallAction from codeframe.core.stall_detector.
• If self.stall_timeout > 0, instantiate stall_detector = StallDetector(timeout=self.stall_timeout), otherwise set to None.
• Pass stall_detector as an argument to _react_loop().

3. Integrate stall detection inside _react_loop() — file:codeframe/core/react_agent.py

Update the signature of _react_loop() to accept stall_detector: Optional[StallDetector] = None.

Inside the while iterations < self.max_iterations: loop:

A — At the top of each iteration (before the LLM call):

• If stall_detector is not None, call stall_detector.is_stalled().
• If stalled:
  • Gather diagnostic context: elapsed time, iterations, last tool call name/args (track last_tool_context: Optional[dict] as a local variable updated each iteration).
  • Log a logger.warning(...) with the elapsed time and last_tool_context.
  • Read stall_detector.action (or equivalent attribute from [Phase 2.5] Stall Detection: Monitor Module #400) and branch:
    • StallAction.RETRY → raise StallDetectedError(context=last_tool_context, iteration=iterations).
    • StallAction.BLOCKER → call self._create_text_blocker(...) with the stall context message, then return AgentStatus.BLOCKED.
    • StallAction.FAIL → return AgentStatus.FAILED.

B — After all tool results are collected (after the for tc in response.tool_calls: loop that populates tool_results), and before the loop-detection block:

• If stall_detector is not None, call stall_detector.record_activity().
• Update last_tool_context = {"tool_name": ..., "iteration": iterations} using the last tool call in response.tool_calls.

4. Catch StallDetectedError in execute_agent() — file:codeframe/core/runtime.py

The ReactAgent is invoked via react_status = react_agent.run(run.task_id) (line 687). Currently run() catches all exceptions internally. The StallDetectedError needs to propagate as a specific case.

Change ReactAgent.run() to not catch StallDetectedError inside its generic except Exception handler — let it bubble up.

In execute_agent(), wrap the react_agent.run(run.task_id) call in a targeted except StallDetectedError as exc: block:

• Log the stall details: exc.context (last tool call), elapsed time, iteration count from the exception.
• Emit an appropriate event (e.g., EventType.AGENT_FAILED with reason="stall_detected").
• Determine retry vs. blocker from exc or StallAction:
  • Retry — re-instantiate ReactAgent (same pattern as the supervisor retry for the plan engine, lines 816–828) and call react_agent.run() again, respecting a max_stall_retries count (default 1, derived from StallDetectedError or a local counter).
  • Blocker — import codeframe.core.blockers, call blockers.create(workspace, task_id=run.task_id, question=<stall context message>), then wrap into AgentState(status=AgentStatus.BLOCKED).
  • Fail — return AgentState(status=AgentStatus.FAILED).

The blocker context message should include: time since last activity, last tool call and result summary, current iteration count, and token usage (self._total_tokens_used).

5. Thread stall_timeout through execute_agent() — file:codeframe/core/runtime.py

Add stall_timeout: int = 300 to the execute_agent() signature (after engine). Pass it to ReactAgent(...) instantiation on line 676–686 as stall_timeout=stall_timeout.

6. Add --stall-timeout flag to work_start — file:codeframe/cli/app.py

In the work_start function (line 1960–2111), add a new typer.Option parameter:

stall_timeout: int = typer.Option(
    300,
    "--stall-timeout",
    help="Seconds without tool activity before stall is detected (0 to disable)",
)

Pass it into runtime.execute_agent(...) at the call site (line 2063–2066) as stall_timeout=stall_timeout.

Update the docstring for work_start to document the new flag:

codeframe work start abc123 --execute --stall-timeout 120
codeframe work start abc123 --execute --stall-timeout 0

7. Thread stall_timeout through batch execution — file:codeframe/core/conductor.py

The conductor calls cf work start <task_id> --execute --engine <engine> as a subprocess (line 1720–1725). Add --stall-timeout to the command list it builds, reading from the batch configuration or defaulting to 300.

---

Data Flow Summary

sequenceDiagram
    participant CLI as cf work start
    participant Runtime as execute_agent()
    participant Agent as ReactAgent.run()
    participant Loop as _react_loop()
    participant Detector as StallDetector

    CLI->>Runtime: stall_timeout=120
    Runtime->>Agent: ReactAgent(stall_timeout=120)
    Agent->>Detector: StallDetector(timeout=120)
    Agent->>Loop: _react_loop(stall_detector)
    loop Each iteration
        Loop->>Detector: is_stalled()?
        alt Stalled
            Detector-->>Loop: True
            Loop->>Loop: raise StallDetectedError / BLOCKED / FAILED
        else Not stalled
            Loop->>Loop: LLM call + tool execution
            Loop->>Detector: record_activity()
        end
    end
    Loop-->>Agent: AgentStatus / StallDetectedError
    Agent-->>Runtime: AgentStatus / StallDetectedError
    Runtime->>Runtime: catch StallDetectedError → retry / blocker / fail
    Runtime-->>CLI: AgentState

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

- `StallDetector`, `StallDetectedError`, and `StallAction` are **not yet in the codebase** — they're deliverables from the parent issue #400. This plan assumes those symbols will exist at `codeframe/core/stall_detector.py`.
- `ReactAgent._react_loop()` already tracks `iterations`, collects `tool_results`, and returns `AgentStatus`. The stall detector slots in cleanly around the existing per-iteration flow.
- `execute_agent()` in `file:codeframe/core/runtime.py` already instantiates `ReactAgent` and calls `react_agent.run()`, wraps the result in `AgentState`. It's the right place to catch `StallDetectedError`.
- `work_start` in `file:codeframe/cli/app.py` already accepts several `typer.Option` flags (`--execute`, `--dry-run`, `--debug`, `--verbose`, `--engine`) passed into `runtime.execute_agent()`.
- `ReactAgent.__init__` in `file:codeframe/core/react_agent.py` accepts named keyword arguments — adding `stall_timeout` follows the same pattern.

## Approach

Add `stall_timeout` as a top-to-bottom parameter: CLI → `execute_agent()` → `ReactAgent.__init__()` → `ReactAgent.run()` / `_react_loop()`. The stall detector is initialized once in `run()`, updated after each successful tool round, and checked at the top of each loop iteration. `execute_agent()` catches `StallDetectedError` and dispatches the configured `StallAction`. No new modules or abstractions are introduced beyond what #400 defines.

---

## Implementation Steps

### 1. Add `stall_timeout` parameter to `ReactAgent.__init__()` — `file:codeframe/core/react_agent.py`

In the `ReactAgent.__init__()` constructor (lines 104–142), add:

- A new keyword argument `stall_timeout: int = 300` (seconds; `0` = disabled) after the existing parameters.
- Store it as `self.stall_timeout = stall_timeout`.

### 2. Integrate `StallDetector` into `ReactAgent.run()` — `file:codeframe/core/react_agent.py`

At the top of `run()` (just before calling `_react_loop()`), after the adaptive budget calculation:

- Import `StallDetector`, `StallDetectedError`, `StallAction` from `codeframe.core.stall_detector`.
- If `self.stall_timeout > 0`, instantiate `stall_detector = StallDetector(timeout=self.stall_timeout)`, otherwise set to `None`.
- Pass `stall_detector` as an argument to `_react_loop()`.

### 3. Integrate stall detection inside `_react_loop()` — `file:codeframe/core/react_agent.py`

Update the signature of `_react_loop()` to accept `stall_detector: Optional[StallDetector] = None`.

Inside the `while iterations < self.max_iterations:` loop:

**A — At the top of each iteration (before the LLM call):**
- If `stall_detector` is not `None`, call `stall_detector.is_stalled()`.
- If stalled:
  - Gather diagnostic context: elapsed time, `iterations`, last tool call name/args (track `last_tool_context: Optional[dict]` as a local variable updated each iteration).
  - Log a `logger.warning(...)` with the elapsed time and `last_tool_context`.
  - Read `stall_detector.action` (or equivalent attribute from #400) and branch:
    - `StallAction.RETRY` → `raise StallDetectedError(context=last_tool_context, iteration=iterations)`.
    - `StallAction.BLOCKER` → call `self._create_text_blocker(...)` with the stall context message, then `return AgentStatus.BLOCKED`.
    - `StallAction.FAIL` → `return AgentStatus.FAILED`.

**B — After all tool results are collected** (after the `for tc in response.tool_calls:` loop that populates `tool_results`), and before the loop-detection block:
- If `stall_detector` is not `None`, call `stall_detector.record_activity()`.
- Update `last_tool_context = {"tool_name": ..., "iteration": iterations}` using the last tool call in `response.tool_calls`.

### 4. Catch `StallDetectedError` in `execute_agent()` — `file:codeframe/core/runtime.py`

The `ReactAgent` is invoked via `react_status = react_agent.run(run.task_id)` (line 687). Currently `run()` catches all exceptions internally. The `StallDetectedError` needs to propagate as a specific case.

Change `ReactAgent.run()` to **not** catch `StallDetectedError` inside its generic `except Exception` handler — let it bubble up.

In `execute_agent()`, wrap the `react_agent.run(run.task_id)` call in a targeted `except StallDetectedError as exc:` block:
- Log the stall details: `exc.context` (last tool call), elapsed time, iteration count from the exception.
- Emit an appropriate event (e.g., `EventType.AGENT_FAILED` with `reason="stall_detected"`).
- Determine retry vs. blocker from `exc` or `StallAction`:
  - **Retry** — re-instantiate `ReactAgent` (same pattern as the supervisor retry for the plan engine, lines 816–828) and call `react_agent.run()` again, respecting a `max_stall_retries` count (default 1, derived from `StallDetectedError` or a local counter).
  - **Blocker** — import `codeframe.core.blockers`, call `blockers.create(workspace, task_id=run.task_id, question=<stall context message>)`, then wrap into `AgentState(status=AgentStatus.BLOCKED)`.
  - **Fail** — return `AgentState(status=AgentStatus.FAILED)`.

The blocker context message should include: time since last activity, last tool call and result summary, current iteration count, and token usage (`self._total_tokens_used`).

### 5. Thread `stall_timeout` through `execute_agent()` — `file:codeframe/core/runtime.py`

Add `stall_timeout: int = 300` to the `execute_agent()` signature (after `engine`). Pass it to `ReactAgent(...)` instantiation on line 676–686 as `stall_timeout=stall_timeout`.

### 6. Add `--stall-timeout` flag to `work_start` — `file:codeframe/cli/app.py`

In the `work_start` function (line 1960–2111), add a new `typer.Option` parameter:

```
stall_timeout: int = typer.Option(
    300,
    "--stall-timeout",
    help="Seconds without tool activity before stall is detected (0 to disable)",
)
```

Pass it into `runtime.execute_agent(...)` at the call site (line 2063–2066) as `stall_timeout=stall_timeout`.

Update the docstring for `work_start` to document the new flag:
```
codeframe work start abc123 --execute --stall-timeout 120
codeframe work start abc123 --execute --stall-timeout 0
```

### 7. Thread `stall_timeout` through batch execution — `file:codeframe/core/conductor.py`

The conductor calls `cf work start <task_id> --execute --engine <engine>` as a subprocess (line 1720–1725). Add `--stall-timeout` to the command list it builds, reading from the batch configuration or defaulting to `300`.

---

## Data Flow Summary

```mermaid
sequenceDiagram
    participant CLI as cf work start
    participant Runtime as execute_agent()
    participant Agent as ReactAgent.run()
    participant Loop as _react_loop()
    participant Detector as StallDetector

    CLI->>Runtime: stall_timeout=120
    Runtime->>Agent: ReactAgent(stall_timeout=120)
    Agent->>Detector: StallDetector(timeout=120)
    Agent->>Loop: _react_loop(stall_detector)
    loop Each iteration
        Loop->>Detector: is_stalled()?
        alt Stalled
            Detector-->>Loop: True
            Loop->>Loop: raise StallDetectedError / BLOCKED / FAILED
        else Not stalled
            Loop->>Loop: LLM call + tool execution
            Loop->>Detector: record_activity()
        end
    end
    Loop-->>Agent: AgentStatus / StallDetectedError
    Agent-->>Runtime: AgentStatus / StallDetectedError
    Runtime->>Runtime: catch StallDetectedError → retry / blocker / fail
    Runtime-->>CLI: AgentState
```

---

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

#363 - feat: wire ReactAgent into runtime with --engine react CLI flag [merged]
#364 - feat: phase-based event emission for ReactAgent progress reporting [merged]
#365 - feat: integrate fix_tracker escalation and blocker detection into ReactAgent [merged]
#369 - test: add CLI integration tests for ReactAgent runtime parameters [merged]
#384 - feat: adaptive iteration budget, autofix, and loop detection for ReactAgent [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!