|
|
@@ -0,0 +1,97 @@
|
|
|
+# Todo 45 Generic Event Kernel Plan
|
|
|
+
|
|
|
+**Status:** in_progress
|
|
|
+
|
|
|
+## 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`
|
zhenyu.hu