Просмотр исходного кода

docs: plan plugin normalization hardening

Problem: built-in plugins can mis-handle negated or oversized volume input, accept invalid schedules or blank searches, diverge across invocation modes, and return stale cached results for reused short IDs.

Risk: provider normalization must remain deterministic and no-fallback; format checking and adapter keys must not introduce event-name logic into the generic kernel.
zhenyu.hu 2 недель назад
Родитель
Сommit
f0818a7304

+ 4 - 0
docs/plans/todo-47-built-in-event-plugins.md

@@ -2,6 +2,10 @@
 
 **Status:** in_progress
 
+## Review Update
+
+The initial plugin implementation remains open pending Todo 47.1 corrections for shared deterministic normalization, strict calendar/query validation, safe volume parsing, and adapter idempotency scope.
+
 ## Goal
 
 Add four namespaced built-in plugins on the generic event kernel without introducing event-name branches in Runtime or the kernel:

+ 53 - 0
docs/plans/todo-47.1-plugin-normalization-and-validation.md

@@ -0,0 +1,53 @@
+# Todo 47.1 Plugin Normalization and Validation Plan
+
+**Status:** in_progress
+
+## Goal
+
+Close review-confirmed plugin safety gaps while preserving the generic kernel and identical built-in behavior across `dual_agent` and `chat_agent_tools`.
+
+## Scope
+
+- Add an optional generic event argument normalizer that runs after text-event resolution and on provider-resolved arguments, before validation and execution.
+- Keep provider-resolved arguments ineligible for EventAgent LLM fallback; normalization is deterministic only.
+- Move canonical volume/search structured normalization into this shared hook.
+- Treat negated volume commands as incomplete/invalid and capture full numeric tokens so values such as `1000` are rejected rather than truncated to `100`.
+- Enforce real RFC3339 date-time validity and real IANA timezone validity through generic JSON Schema format checking.
+- Reject blank/whitespace-only search queries and blank schedule titles.
+- Prevent in-memory adapters from returning stale results when short parser event IDs collide with different normalized arguments.
+
+## Idempotency Decision
+
+The lab adapters will cache by event ID plus canonical normalized arguments, not event ID alone. This preserves same-call replay behavior while preventing `event_1` with a different operation from returning an earlier result. Runtime-scoped deduplication and production session/turn idempotency remain Todo 48/service integration responsibilities.
+
+## Files
+
+- Modify: `src/agent_lab/application/events/models.py`
+- Modify: `src/agent_lab/application/events/kernel.py`
+- Modify: `src/agent_lab/application/events/registry.py`
+- Modify: `src/agent_lab/application/events/__init__.py`
+- Modify: `src/agent_lab/application/events/builtin_plugins.py`
+- Modify: `src/agent_lab/application/tools.py` only to preserve ToolDefinition compatibility with the new optional normalizer
+- Modify: `tests/test_event_kernel.py`
+- Modify: `tests/test_builtin_event_plugins.py`
+
+## Requirement Execution Loop
+
+### Plan
+
+1. Add RED generic-kernel tests proving normalizers run for both sources, preserve provider raw arguments, and never enable provider LLM fallback.
+2. Add RED plugin parity tests for canonicalization through text and provider sources.
+3. Add RED safety tests for English/Chinese negation, `1000`, invalid dates, invalid IANA zones, blank query/title, and no port calls.
+4. Add RED adapter tests for same short ID with different arguments and replay with identical arguments.
+5. Implement generic format checking and the smallest plugin normalizers/validators.
+6. Run focused/full verification and renewed reviews.
+
+### Observe / Update
+
+Close Todo 47 only when all four plugins reject unsafe inputs before ports, both invocation modes share deterministic normalization, and no event-name logic enters generic orchestration.
+
+## Verification
+
+- `UV_CACHE_DIR=.uv-cache uv run pytest tests/test_event_kernel.py tests/test_builtin_event_plugins.py -q`
+- `UV_CACHE_DIR=.uv-cache uv run pytest`
+- `git diff --check`

+ 1 - 0
docs/plans/todos.md

@@ -85,6 +85,7 @@
 | 46 | done | `docs/plans/todo-46-configurable-tool-invocation-mode.md` | Add `dual_agent` and `chat_agent_tools` runtime modes on the shared event kernel. | Both modes share registry/kernel/results while preserving mode-specific protocol and valid transcripts; full suite passes (`217 passed`, one existing warning). |
 | 46.1 | done | `docs/plans/todo-46.1-mode-parity-and-duplicate-call-safety.md` | Reject repeated provider call IDs before side effects, align direct multi-call concurrency with dual mode, and enforce the same event budget in both modes. | Duplicate IDs are rejected before side effects; direct batches overlap with stable order; dual/direct budgets are symmetric; final gates pass. |
 | 47 | in_progress | `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. |
+| 47.1 | in_progress | `docs/plans/todo-47.1-plugin-normalization-and-validation.md` | Share plugin normalization across invocation modes and harden negation, numeric, date/timezone, query, and adapter idempotency boundaries. | Direct/dual canonical results match; negated/oversized volume never executes; invalid calendar/timezone and blank query are rejected; short ID collisions cannot return stale results. |
 | 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. |
 | 49 | pending | `docs/plans/todo-49-tool-mode-ui-session-restore.md` | Add UI mode selection, workspace/session restoration, and clear EventAgent applicability feedback. | Static/WebSocket tests prove requests, snapshots, loaded sessions, and audit context preserve the selected mode. |
 | 50 | pending | `docs/plans/todo-50-comparable-model-tool-metrics.md` | Record mode-aware model/tool spans and include EventAgent usage so both architectures can be compared fairly. | Persistence/API tests report agent, call kind, tokens, TTFT, tool latency, fallback usage, and total turn wall time without double counting. |