agent-lab/docs/plans/todo-45.6-mixed-validation-and-handler-snapshot.md

Todo 45.6 Mixed Validation and Handler Snapshot Plan

Status: in_progress

Goal

Close the final reviewed cost and error-isolation gaps: mixed validation failures must never trigger LLM fallback, and arbitrary exceptions while snapshotting a handler payload must become normalized handler failures.

Scope

• Treat validation as fallback-eligible only when every reported top-level failure classifies as missing-only.
• Cover required fields combined with enum, type, additional-property, and composed-schema substantive errors.
• Catch any normal exception raised while producing a strict JSON snapshot of a handler payload in async and sync execution.
• Verify ToolRegistry and EventAgent receive normalized error payloads rather than exceptions.

Boundaries

• Preserve fallback for pure missing-only input, including the unique viable composed branch from Todo 45.5.
• Do not catch BaseException subclasses such as cancellation or process-exit signals.
• Keep strict JSON rejection behavior; do not coerce unusual dictionary subclasses or values.

Files

• Modify: src/agent_lab/application/events/kernel.py
• Modify: tests/test_event_kernel.py
• Modify: tests/test_event_agent.py

Requirement Execution Loop

Plan

1. Add RED tests for required plus enum/type/additionalProperties and required plus composed substantive errors; fallback count must remain zero.
2. Add RED tests whose handler returns a dictionary subclass raising RuntimeError during JSON serialization.
3. Require all validation issues to be missing-only before setting missing_required=True.
4. Normalize strict payload snapshot exceptions to HANDLER_ERROR in sync and async paths.
5. Verify the behavior through EventKernel, ToolRegistry, and EventAgent, then run full reviews.

Act

• Assert mixed invalid input reports INVALID_ARGUMENTS, used_fallback=False, and zero fallback calls.
• Assert pure missing input still falls back exactly once.
• Assert exploding payload snapshots return event handler returned non-JSON payload without escaping from kernel, ToolRegistry, or EventAgent.

Observe

Confirm fallback counts represent only missing information and every ordinary plugin payload failure remains isolated inside the event result pipeline.

Update

• Re-run final Todo 45 specification and quality reviews.
• Mark Todos 45 through 45.6 done only after fresh verification.

Verification

• UV_CACHE_DIR=.uv-cache uv run pytest tests/test_event_kernel.py tests/test_event_agent.py -q
• UV_CACHE_DIR=.uv-cache uv run pytest
• git diff --check