agent-lab/docs/plans/todo-45-generic-event-kernel.md

Todo 45 Generic Event Kernel Plan

Status: done

Result

Implemented a name-agnostic event kernel with registry metadata, deterministic-first resolution, optional asynchronous fallback, policy-bearing results, sync/async handlers, and ToolRegistry/EventAgent compatibility. Final full verification: 203 passed, one existing Starlette deprecation warning; bounded specification and quality gates passed.

Goal

Extract a generic, event-name-agnostic execution kernel so text events and future native ChatAgent tool calls share deterministic resolution, bounded LLM fallback, validation, execution, and normalized results before built-in plugins are added.

Architecture

Create a focused agent_lab.application.events package:

• models.py: event source, result/continuation policies, definition metadata, execution request/context, normalized result.
• registry.py: flat definition registration, catalog/schema lookup, enabled-name filtering, and compatibility validation.
• kernel.py: deterministic-first resolution, optional injected argument fallback, schema-required-field validation, handler isolation, and normalized result creation.

Keep application/tools.py as a compatibility facade during migration. Existing Runtime and EventAgent APIs continue working, but their resolution/execution delegates to the kernel. The kernel must not compare built-in event names.

Scope

• Add generic definition metadata and namespaced-event support without adding the four production plugins yet.
• Deterministic resolver runs first.
• LLM fallback is called only when deterministic output is incomplete and the definition allows fallback.
• Provider-resolved arguments are validated/executed without another fallback call.
• Normalize unknown, disabled, invalid, handler-failure, and success outcomes.
• Introduce generic continuation/result policies as metadata; Runtime application of those policies remains for Todo 48.
• Preserve current mock tool names and public registry APIs through adapters.
• Do not add parallel scheduling or direct ChatAgent tools in this todo.

Files

• Create: src/agent_lab/application/events/__init__.py
• Create: src/agent_lab/application/events/models.py
• Create: src/agent_lab/application/events/registry.py
• Create: src/agent_lab/application/events/kernel.py
• Modify: src/agent_lab/application/tools.py
• Modify: src/agent_lab/application/event_agent.py
• Modify: src/agent_lab/application/runtime.py only for dependency construction/types if required
• Create: tests/test_event_kernel.py
• Modify: tests/test_event_agent.py
• Modify: tests/test_debug_runtime.py only for regression compatibility

Plan

Plan

1. Define desired kernel contracts through focused failing tests.
2. Verify RED failures for missing package/types and current EventAgent always-LLM behavior.
3. Implement minimal models, flat registry, and sequential kernel.
4. Adapt existing ToolRegistry/EventAgent through compatibility boundaries.
5. Run focused and full regressions.

Act

Follow TDD in these slices:

1. Registry contract RED
   • Register two synthetic definitions and assert catalog/schema lookup, enabled filtering, duplicate-name rejection, and no event-name-specific knowledge.
2. Deterministic resolution RED
   • Definition resolver returns complete required arguments; assert handler executes and fallback mock has zero calls.
3. Fallback RED
   • Resolver returns incomplete required arguments; assert one fallback call supplies arguments and handler executes.
   • Definition with fallback disabled returns normalized invalid-arguments result without calling fallback.
4. Provider-resolved RED
   • Request marked provider-resolved with complete arguments executes directly without resolver/fallback rewriting.
   • Missing/invalid provider arguments return normalized invalid result.
5. Failure isolation RED
   • Unknown, disabled, handler exception, duplicate definition, and malformed arguments return or raise the documented normalized contract.
6. Metadata RED
   • Assert result policy, confirmation policy, risk level, idempotency/concurrency metadata, timeout, and terminal flag survive registration and result creation.
7. Compatibility RED
   • Existing ToolRegistry.available_tools(), chat_event_system_message(), tool_schema(), handle(), and execute() retain their observable behavior through the new registry/kernel.
   • EventAgent deterministic mock tools skip its LLM; ambiguous synthetic definition invokes exactly one EventAgent provider fallback.
8. Run RED tests, implement minimum code, then run focused and full verification.

Observe

Confirm that:

• the kernel has no built-in event-name branches;
• existing Runtime behavior remains green;
• deterministic tools reduce EventAgent model calls;
• provider-resolved arguments are not rewritten;
• policies are data on definitions/results rather than Runtime conditionals;
• no direct-tools mode or parallel engine is introduced early.

Update

• Mark todo 45 done only after spec and quality reviews pass.
• Add 45.1 directly below todo 45 for any post-commit repair.
• Re-evaluate Todo 46 against the final kernel API before writing its detailed plan.

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