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

Todo 16 Tool Error Isolation Plan

Status: in_progress

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

Expected result:

• Direct EventAgent tests prove structured tool errors.
• Runtime tests prove the WebSocket stream contract stays structured.
• Full suite passes.