|
|
@@ -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`
|
zhenyu.hu