agent-lab/docs/plans/todo-16-tool-error-isolation.md

Todo 16 Tool Error Isolation Plan

Status: done

Goal

Convert EventAgent tool handler exceptions into structured tool-result errors instead of aborting or hanging the debug session.

Why

Dynamic EventAgent tools will eventually call real code. A single tool exception should be visible to the ChatAgent as a tool reply, not break the WebSocket session or leave the runtime waiting forever for a tool response.

Scope

This todo covers:

• Catch Exception from registry tool handlers.
• Return a ChatMessage(role="tool") containing a JSON error payload.
• Prove runtime continues to the next ChatAgent call after a failing tool.

This todo does not cover:

• Retry policies.
• Tool timeout controls.
• Full traceback exposure.

Files

• Modify: src/agent_lab/application/event_agent.py
• Modify: tests/test_event_agent.py
• Modify: tests/test_debug_runtime.py
• Modify: docs/plans/todos.md
• Modify: this plan

Steps

1. Add failing EventAgent test for a registry handler that raises RuntimeError("boom").
2. Add failing runtime test proving a failing handler emits tool_result and reaches done.

3. Catch handler exceptions in EventAgent.handle() and return payload:

   {"tool": "handoff_note", "error": "tool handler failed: boom"}
   

4. Run:

   uv run pytest tests/test_event_agent.py tests/test_debug_runtime.py
   uv run pytest
   

5. Update this plan and docs/plans/todos.md, then commit.

Verification

Result:

• Red run passed as expected: direct EventAgent raised RuntimeError("boom"), and runtime output collection timed out waiting for a missing tool reply.
• uv run pytest tests/test_event_agent.py tests/test_debug_runtime.py passed: 14 tests.
• uv run pytest passed: 37 tests, 1 existing Starlette deprecation warning.

Evaluation

• EventAgent.handle() now catches tool handler Exception and returns a structured tool reply with {"tool": name, "error": "tool handler failed: ..."}.
• Runtime receives that reply through the input queue, emits tool_result, and continues to the next ChatAgent call.