# 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`