agent-lab/docs/plans/todo-45.1-event-kernel-boundary-hardening.md

Todo 45.1 Event Kernel Boundary Hardening Plan

Status: done

Result

Added Draft 2020-12 validation, schema isolation, normalized resolver/fallback/handler failures, strict argument consistency, async-safe execution, and regression coverage for EventAgent concurrency.

Goal

Make the generic event kernel a trustworthy execution boundary by using standard JSON Schema validation, normalizing all resolver/fallback/handler failures, preserving provider raw arguments, supporting async handlers through the async path, and restoring existing EventAgent concurrency until Todo 48 replaces it atomically.

Scope

• Add the jsonschema runtime dependency and validate definitions with Draft 2020-12 schema checks at registration.
• Validate event arguments with the registered schema and normalize validation-library failures.
• Normalize resolver, fallback, handler invocation, and handler payload-shape failures into stable EventResult statuses.
• Replace bare fallback dictionaries with a structured arguments/raw-arguments result and verify provider tool name matches the requested event.
• Support sync and async handlers in the async kernel and ToolRegistry type contract.
• Add explicit async ToolRegistry entry points; sync facade rejects coroutine functions before creating an un-awaited coroutine.
• Restore EventAgent.handle_many() concurrency with asyncio.gather; bounded scheduling remains Todo 48.
• Strengthen generic behavior tests rather than searching for only known event-name strings.

Files

• Modify: pyproject.toml
• Modify: uv.lock
• Modify: src/agent_lab/application/events/models.py
• Modify: src/agent_lab/application/events/registry.py
• Modify: src/agent_lab/application/events/kernel.py
• Modify: src/agent_lab/application/tools.py
• Modify: src/agent_lab/application/event_agent.py
• Modify: tests/test_event_kernel.py
• Modify: tests/test_event_agent.py
• Modify: tests/test_debug_runtime.py only for concurrency regression if needed

Plan

Plan

1. Add failing tests for every quality-review issue.
2. Verify RED failures demonstrate leaked exceptions, incomplete schema checks, inconsistent raw arguments, async facade warnings, and lost concurrency.
3. Add the standard validator dependency and implement minimum boundary hardening.
4. Run focused and full regressions.

Act

• Add schema tests for union types, enum, nested objects/arrays, additional properties, invalid schemas, and boolean-vs-number behavior.
• Add resolver and fallback exception tests asserting normalized resolution failure rather than raised exceptions.
• Add handler tests for exception, None, scalar, and other non-dict returns, all normalized as handler errors.
• Add fallback tests asserting resolved arguments and raw JSON remain consistent and a provider response for the wrong tool is rejected.
• Add sync and async handler tests through EventKernel.execute; add ToolRegistry async-entry tests and sync rejection without runtime warnings.
• Add a timing/barrier test proving EventAgent.handle_many() starts independent calls concurrently.
• Replace the weak known-name source search with synthetic-definition tests proving arbitrary names share identical kernel behavior.
• Run RED, implement minimum changes, and re-run all verification.

Observe

Confirm standard schema semantics, no exception leaks across the kernel contract, raw/parsed argument consistency, clean async handler behavior, and preserved existing concurrency.

Update

• Mark 45 and 45.1 done only after renewed spec and quality review.
• Commit separately with validation and compatibility risks in the body.

Verification

• uv run pytest tests/test_event_kernel.py tests/test_event_agent.py tests/test_debug_runtime.py -q
• uv run pytest
• git diff --check