Răsfoiți Sursa

docs: plan event kernel quality boundary fixes

Problem: final quality review reproduced five gaps affecting EventAgent configuration, composed-schema fallback, mutation isolation, registry encapsulation, and JSON-safe handler results.

Risk: fixes must preserve explicit empty overrides and avoid broadening fallback for complete-invalid arguments.
zhenyu.hu 2 săptămâni în urmă
părinte
comite
16b52da4ae

+ 63 - 0
docs/plans/todo-45.4-event-kernel-quality-boundaries.md

@@ -0,0 +1,63 @@
+# Todo 45.4 Event Kernel Quality Boundaries Plan
+
+**Status:** in_progress
+
+## Goal
+
+Close five reproducible quality-review gaps before treating the generic event kernel as the stable foundation for runtime modes and built-in plugins.
+
+## Scope
+
+- Preserve configured `EventAgent.params.extra_body` when a call does not provide an override.
+- Detect missing required arguments nested under composed JSON Schemas such as `anyOf` and `oneOf`, so eligible incomplete input can use fallback.
+- Isolate nested resolved arguments from handler mutation and preserve consistent result/audit values.
+- Stop exposing the registry's mutable internal validator object.
+- Reject handler dictionaries that are not strict JSON-serializable and normalize them to `HANDLER_ERROR`.
+
+## Boundaries
+
+- Do not add direct ChatAgent tool mode, built-in event plugins, batch scheduling, or new UI behavior.
+- Preserve `extra_body={}` as an explicit override; only `None` means use the configured default.
+- Do not broaden fallback to complete-invalid input; only recursively discovered missing-required errors qualify.
+- Keep event payloads as dictionaries and reject, rather than coerce, sets, arbitrary objects, NaN, or Infinity.
+
+## Files
+
+- Modify: `src/agent_lab/application/event_agent.py`
+- Modify: `src/agent_lab/application/events/kernel.py`
+- Modify: `src/agent_lab/application/events/registry.py`
+- Modify: `tests/test_event_agent.py`
+- Modify: `tests/test_event_kernel.py`
+
+## Requirement Execution Loop
+
+### Plan
+
+1. Add one RED regression per reviewed issue and verify each fails for the reported reason.
+2. Fix configuration propagation and composed-schema error classification without changing valid call behavior.
+3. Deep-copy arguments at handler/result boundaries and encapsulate validator usage inside the registry.
+4. Validate handler payloads with the same strict JSON rules used for arguments.
+5. Run focused tests, full tests, diff checks, and renewed specification/quality reviews.
+
+### Act
+
+- Call `EventAgent.handle()` without `extra_body` while constructor params contain a marker; assert the provider receives the marker. Also assert explicit `{}` remains `{}`.
+- Use `anyOf`/`oneOf` branches containing `required`; assert missing data invokes fallback once, while nested complete-invalid data does not.
+- Mutate a nested handler argument; assert the original request, `EventResult.arguments`, and `raw_arguments` remain consistent and unchanged.
+- Replace public validator retrieval with a registry-owned validation operation; prove callers cannot mutate future validation behavior.
+- Return payloads containing `object()`, `set`, NaN, and Infinity; assert stable `HANDLER_ERROR` and no downstream `json.dumps()` failure.
+
+### Observe
+
+Confirm the kernel remains generic and deterministic-first while all externally observable results are JSON-safe, immutable from plugin side effects, and consistent for audit/comparison metrics.
+
+### Update
+
+- Re-run final Todo 45 specification and quality reviews.
+- Mark Todos 45 through 45.4 done only after fresh full verification.
+
+## Verification
+
+- `UV_CACHE_DIR=.uv-cache uv run pytest tests/test_event_kernel.py tests/test_event_agent.py -q`
+- `UV_CACHE_DIR=.uv-cache uv run pytest`
+- `git diff --check`

+ 1 - 0
docs/plans/todos.md

@@ -78,6 +78,7 @@
 | 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. |
 | 45.2 | in_progress | `docs/plans/todo-45.2-event-fallback-semantics.md` | Restrict fallback to incomplete resolution, enforce JSON-type-sensitive raw consistency, and distinguish definition failures. | Complete-invalid arguments skip LLM; raw/parsed mismatch and broken schema references produce stable non-user-error results. |
 | 45.3 | in_progress | `docs/plans/todo-45.3-sync-resolution-completeness.md` | Make synchronous kernel execution reject explicitly incomplete deterministic resolution instead of invoking the handler. | A structured incomplete result with an optional-only schema returns `INVALID_ARGUMENTS`; the handler is not called and async behavior remains aligned. |
+| 45.4 | in_progress | `docs/plans/todo-45.4-event-kernel-quality-boundaries.md` | Close reviewed configuration, composed-schema fallback, mutation isolation, registry encapsulation, and payload-serialization gaps. | Default EventAgent config survives omitted overrides; nested required errors can fall back; handlers and callers cannot corrupt audit arguments; validators stay private; non-JSON payloads become `HANDLER_ERROR`. |
 | 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. |