docs: plan built-in event plugins

Problem: the generic kernel and comparison modes have no production-shaped terminate, volume, schedule, or web-search definitions to exercise.

Risk: plugin contracts must remain name-agnostic to Runtime/kernel and keep real side effects behind injectable service ports; schedule parsing must not guess ambiguous times.

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

@@ -0,0 +1,103 @@
+# Todo 47 Built-in Event Plugins Plan
+
+**Status:** in_progress
+
+## Goal
+
+Add four namespaced built-in plugins on the generic event kernel without introducing event-name branches in Runtime or the kernel:
+
+- `session.terminate`
+- `device.volume.adjust`
+- `calendar.schedule.create`
+- `knowledge.web.search`
+
+## Architecture
+
+- Keep the registry flat.
+- Each plugin definition owns its name, concise description, JSON Schema, deterministic resolver, fallback policy, handler adapter, result/confirmation/risk policy, idempotency metadata, concurrency/conflict metadata, timeout, and terminal flag.
+- Put production side effects behind injectable application ports. The lab default uses deterministic in-memory/mock adapters; `mituan-service` integration remains a separate repository task.
+- `build_default_tool_registry()` includes the four plugins while preserving existing lab mock tools.
+- Both invocation modes discover and execute the same definitions automatically through the existing registry/kernel.
+
+## Plugin Contracts
+
+### `session.terminate`
+
+- Arguments: optional `reason` string.
+- Deterministic, no LLM fallback required.
+- Port: dialogue/session termination boundary, keyed by event ID.
+- Policy: `TERMINATE`, high risk, terminal, serialized against session lifecycle work.
+- Default adapter returns a normalized terminated result and is idempotent by event ID.
+
+### `device.volume.adjust`
+
+- Arguments:
+  - `mode`: `absolute`, `relative`, `mute`, or `unmute`;
+  - `value`: integer `0..100` for absolute;
+  - `delta`: integer `-100..100`, excluding zero, for relative.
+- JSON Schema enforces mode-specific required/forbidden fields.
+- Deterministic resolver recognizes clear Chinese/English mute, unmute, absolute, and signed relative requests; incomplete requests remain eligible for EventAgent fallback.
+- Port: device-action dispatcher boundary, keyed by event ID.
+- Policy: `SILENT_SUCCESS`, medium risk, device-volume conflict class.
+- Invalid/out-of-range/ambiguous requests never call the port.
+
+### `calendar.schedule.create`
+
+- Arguments: `title`, RFC3339 `start_at`, IANA-style `timezone`, optional `recurrence`, optional non-negative `reminder_minutes`.
+- Deterministic resolver accepts already structured arguments and explicit ISO/RFC3339 details only; it must not guess relative or ambiguous natural-language times.
+- Missing/ambiguous fields can use the existing EventAgent LLM fallback in dual mode.
+- Port: calendar/reminder application boundary with event-ID idempotency.
+- Policy: `TEMPLATE_FOLLOW_UP`, medium risk, schedule-write concurrency class.
+- Default adapter deduplicates repeated event IDs and returns normalized confirmation data.
+
+### `knowledge.web.search`
+
+- Arguments: focused non-empty `query`, optional `max_results` from `1..5`.
+- Deterministic resolver derives the latest relevant user request when provider arguments are absent.
+- Port: external-search adapter returning a stable compact result contract.
+- Policy: `LLM_FOLLOW_UP`, low risk, read-only concurrency class.
+- Default adapter returns deterministic mock sources with retrieval metadata; no network or credentials.
+
+## Scope
+
+- Add plugin definitions and injectable ports/default adapters.
+- Register plugins in the default registry and expose them from the existing tools API/catalog.
+- Add focused schema, resolver, metadata, execution, failure, idempotency, and mode-parity tests.
+- Preserve existing `handoff_note`, `mock_search`, and `mock_ticket` lab tools.
+
+## Boundaries
+
+- Do not implement real MQTT/device commands, calendar storage, session shutdown, or internet search.
+- Do not add name-specific branches to Runtime, EventAgent, EventKernel, or provider parsers.
+- Do not implement bounded batch scheduling, terminal barriers, result-policy aggregation, or two-answer runtime behavior here; those are Todo 48.
+- Do not guess schedule relative times without an explicit clock/timezone context.
+
+## Files
+
+- Add: `src/agent_lab/application/events/builtin_plugins.py`
+- Modify: `src/agent_lab/application/events/__init__.py`
+- Modify: `src/agent_lab/application/tools.py`
+- Add: `tests/test_builtin_event_plugins.py`
+- Modify: `tests/test_websocket_api.py` only for default tools catalog coverage if needed.
+
+## Requirement Execution Loop
+
+### Plan
+
+1. Add RED catalog/metadata tests for all four namespaced plugins.
+2. Add RED valid/invalid resolver and schema tests per plugin.
+3. Add RED port execution, normalized failure, and idempotency tests.
+4. Implement ports, default adapters, and flat definitions without touching generic orchestration.
+5. Verify both `dual_agent` and `chat_agent_tools` receive the same schemas/results for the built-ins.
+6. Run focused/full verification and independent reviews.
+
+### Observe / Update
+
+Record any plugin contract ambiguity as a `47.x` todo. Mark complete only when adding these plugins requires no Runtime/kernel event-name conditionals and all external actions remain behind ports.
+
+## Verification
+
+- `UV_CACHE_DIR=.uv-cache uv run pytest tests/test_builtin_event_plugins.py tests/test_event_agent.py tests/test_debug_runtime.py -q`
+- `UV_CACHE_DIR=.uv-cache uv run pytest`
+- `UV_CACHE_DIR=.uv-cache uv run python -c "from agent_lab.application.tools import build_default_tool_registry; print([x['name'] for x in build_default_tool_registry().available_tools()])"`
+- `git diff --check`

docs/plans/todos.md

@@ -84,7 +84,7 @@
 | 45.7 | done | `docs/plans/todo-45.7-structured-incomplete-mixed-validation.md` | Prevent an explicit structured `complete=False` flag from bypassing substantive validation failures. | Structured incomplete plus substantive errors skips fallback; bounded final gate APPROVED. |
 | 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 | 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. |
+| 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. |
 | 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. |