Преглед на файлове

docs: plan event kernel boundary hardening

Problem: the first kernel implementation left schema, failure normalization, raw-argument, async-handler, and concurrency gaps at the shared execution boundary.

Risk: standard JSON Schema validation adds a dependency and may reject malformed schemas that the previous partial validator tolerated.
zhenyu.hu преди 2 седмици
родител
ревизия
9a53531016
променени са 2 файла, в които са добавени 67 реда и са изтрити 0 реда
  1. 66 0
      docs/plans/todo-45.1-event-kernel-boundary-hardening.md
  2. 1 0
      docs/plans/todos.md

+ 66 - 0
docs/plans/todo-45.1-event-kernel-boundary-hardening.md

@@ -0,0 +1,66 @@
+# Todo 45.1 Event Kernel Boundary Hardening Plan
+
+**Status:** in_progress
+
+## 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`

+ 1 - 0
docs/plans/todos.md

@@ -75,6 +75,7 @@
 | 44 | done | `docs/plans/todo-44-provider-tool-transcript.md` | Add provider-compatible assistant tool-call and tool-result message serialization plus explicit tool-choice behavior. | Focused transcript tests pass (`97 passed`); full suite passes (`108 passed`, one existing warning). |
 | 44.1 | done | `docs/plans/todo-44.1-tool-transcript-hardening.md` | Harden transcript identity, reserved payload fields, EventAgent history projection, and public pre-message boundaries. | Duplicate IDs, invalid choices, reserved overrides, projected history, and pre-message boundaries are covered; full suite passes. |
 | 45 | in_progress | `docs/plans/todo-45-generic-event-kernel.md` | Build a generic event kernel with definition metadata, deterministic-first resolution, policies, execution ports, and result aggregation. | Kernel contract tests prove orchestration contains no built-in event-name branches and plugins share one pipeline. |
+| 45.1 | in_progress | `docs/plans/todo-45.1-event-kernel-boundary-hardening.md` | Harden JSON Schema validation, normalized failures, fallback raw arguments, async handlers, and existing EventAgent concurrency. | Standard schema tests and failure-path regressions pass; async handlers work through the kernel without sync-facade warnings. |
 | 46 | pending | `docs/plans/todo-46-configurable-tool-invocation-mode.md` | Add `dual_agent` and `chat_agent_tools` runtime modes on the shared event kernel. | Runtime tests prove mode-specific requests, direct execution, valid provider history, and dual-mode regression safety. |
 | 47 | pending | `docs/plans/todo-47-built-in-event-plugins.md` | Add terminate-session, device-volume, schedule, and web-search as built-in plugins on the generic event kernel. | Plugin contract tests cover valid, ambiguous, invalid, idempotent, and failure results for all four events. |
 | 48 | pending | `docs/plans/todo-48-parallel-event-batches.md` | Execute multiple flat events with bounded parallelism, failure isolation, aggregation, and a terminal barrier. | Runtime tests prove independent concurrency, stable result order, isolated failures, and termination after sibling completion or timeout. |