# Next Session: `trigger_agent` Tool for Annie

## What
Build a `trigger_agent` tool so Annie can dispatch background agents from chat. When Rajesh says "generate the detailed ISP weekly report," Annie calls `trigger_agent(agent_name="router_weekly_report")` instead of answering inline. Results arrive async via Telegram.

## Plan
Approved plan with adversarial review findings at: `~/.claude/plans/stateful-fluttering-rainbow.md`

**Read the plan first — it has the full implementation, all review findings, and the design decisions.**

## Key Design Decisions (from adversarial review — 15 findings, ALL addressed)
1. **Direct `_scheduler.trigger_now()` call** — NOT HTTP-to-self. Inject scheduler via `set_scheduler()` pattern (same as existing `set_task_queue()`). Eliminates 6 failure modes (wrong port, auth token, 401 silent fail, event loop contention, JSON parse crash, circular dependency).
2. **NOT gated** — no env flag needed. Has its own cooldown. Similar to `invoke_researcher`.
3. **`group="agents"`** — NOT `"subagent"`. Cron-style dispatch ≠ conversational subagent.
4. **Agent names verified on Titan**: `router_weekly_report` and `router_daily_report` (NOT `router_daily`).
5. **Live agent list on 404** — handler calls `_scheduler._discovery.get_definitions()` instead of hardcoded names.
6. **Dual cooldown** — per-agent 10s + global 5s cross-agent (Beast GPU contention).
7. **run_id surfaced** — `trigger_now()` returns run_id, handler includes it in response.
8. **All logging** — `logger.error()` on every failure, `logger.info()` on success.

## Files to Modify
1. `services/annie-voice/tool_schemas.py` — `TriggerAgentInput(agent_name: str)`
2. `services/annie-voice/text_llm.py` — `set_scheduler()` + `_dispatch_trigger_agent()` + ToolSpec entry
3. `services/annie-voice/tool_adapters.py` — `"trigger_agent": ToolAdapter()`
4. `services/annie-voice/server.py` — `set_scheduler(_scheduler)` at startup
5. `services/annie-voice/tests/test_schema_golden.py` — golden test + update "31 specs" → "32 specs"
6. `services/annie-voice/tests/test_trigger_agent.py` — handler unit tests (scheduler None, success, ValueError, cooldown)

## Start Command
```bash
cat ~/.claude/plans/stateful-fluttering-rainbow.md
```
Then implement the plan. All adversarial findings are already addressed in it.

## Verification
1. `cd services/annie-voice && python3 -m pytest tests/test_schema_golden.py tests/test_tool_dispatch.py tests/test_tool_adapters.py -v`
2. `python3 -m pytest tests/test_trigger_agent.py -v`
3. `python3 -m pytest tests/ -x` (full suite)
4. Deploy: commit, push, Titan pull, `__pycache__` clear, restart Annie
5. E2E: Ask Annie via Telegram "generate the detailed weekly ISP report" → should trigger agent → report arrives on Telegram