# Next Session: Zomato Telegram Ordering UX — IMPLEMENT

## Context
Session 402 (2026-04-04) completed full architecture planning. Session 20 (2026-04-08) re-verified all line numbers and updated this plan against the current codebase.

**Read the plan first:** `/home/rajesh/.claude/plans/witty-honking-quilt.md` — contains the complete implementation plan with verified line numbers, phased build sequence, and security checklist.

## What Was Done
- **Session 402:** 3 Explore agents traced TWF handler, Zomato MCP, Annie tool system. 1 Plan agent designed implementation. Plan approved.
- **Session 20 (revision):** Re-verified ALL line numbers against current codebase (2099-line text_llm.py, 748-line bot.py, etc.). All correct. Updated stale references from original plan file.

## Key Architecture Decision
**No Playwright needed.** Zomato's MCP provides `checkout_cart` as a direct API call. Entire order lifecycle lives in the Telegram handler via MCP calls.

## Capability Registry
**No manual registration needed.** The capability manifest (`capability_manifest.py`) auto-derives from `TOOL_SPECS`. Adding a `ToolSpec(group="ordering", gated=True)` to `text_llm.py` automatically registers `order_food` in the `/v1/capabilities` endpoint. This is the same pattern used by `order_flour` and `order_from_cremeitalia`.

## Files to Create (4)
1. `services/annie-voice/zomato_tools.py` (~120 lines) — Voice tool, writes trigger JSON
2. `services/telegram-bot/zomato_handler.py` (~800 lines) — State machine + MCP client (MAIN WORK)
3. `services/telegram-bot/tests/test_zomato_handler.py` (~500 lines) — State machine tests
4. `services/annie-voice/tests/test_zomato_tools.py` (~100 lines) — Tool tests

## Files to Modify (6)
5. `services/annie-voice/text_llm.py` — feature flag (line 219) + schema import (line 239) + intents (line 347) + dispatch (line 531) + ToolSpec (line 1089) + gating (line 1326)
6. `services/annie-voice/tool_schemas.py` — `OrderFoodInput` (after line 189)
7. `services/annie-voice/tool_adapters.py` — `"order_food": ToolAdapter()` (after line 280)
8. `services/telegram-bot/pending_handler.py` — route `zomato_menu` (after line 284)
9. `services/telegram-bot/bot.py` — register `^zom:` callback (after line 693)
10. Titan `.env` — `ZOMATO_ENABLED=true` (deploy time, project .env NOT ~/.her-os/.env)

## NOT Modified (and why)
- `capability_manifest.py` — auto-derives from TOOL_SPECS, no manual update
- `observability.py` / `chronicler.py` — TWF doesn't emit events; skip for consistency
- Dashboard creature registry — no creature without observability events
- `RESOURCE-REGISTRY.md` — no GPU model changes

## Implementation Sequence (6 phases)
1. **Annie Voice tool + wiring** — `zomato_tools.py` + text_llm.py changes + tool_schemas + tool_adapters
2. **Core Telegram handler** — `zomato_handler.py` with MCP client, states: RESTAURANTS→MENU→ITEMS→VARIANTS→CART
3. **Checkout + UPI QR** — CONFIRMING state, `create_cart` + `checkout_cart`, QR photo delivery
4. **Reorder flow** — `get_order_history`, REORDER_PICK state
5. **Tests** — both test files, run full suite
6. **Deploy + live test** — `ZOMATO_ENABLED=true`, restart, order food

## State Machine Summary
```
RESTAURANTS → zom:res:{idx} → MENU (categories)
  → zom:cat:{idx} → ITEMS → zom:item:{idx} → VARIANTS
    → zom:var:{idx} → CART → zom:checkout → CONFIRMING
      → zom:yes → create_cart + checkout_cart → UPI QR photo

REORDER_PICK (from history) → zom:ro:{idx} → CART → same checkout flow
```

## Technical Notes
- **MCP endpoint:** `https://mcp-server.zomato.com/mcp` (JSON-RPC over HTTP, SSE response)
- **Token:** `~/.her-os/annie/mcp-tokens/zomato_tokens.json` (30-day with refresh, check expiry before use)
- **`pay_later` does NOT work** — always use `payment_type="upi_qr"`
- **UPI QR:** delivered via `bot.send_photo()` (separate message — edits can't add photos)
- **Session TTL:** 4 hours (matching TWF)
- **Callback data:** all `zom:*` patterns under 64 bytes (Telegram limit)
- **Address:** Rajesh's home HSR `address_id: 233093817`

## Key References
- **Plan file:** `/home/rajesh/.claude/plans/witty-honking-quilt.md`
- **MCP prototype (extract client):** `scripts/prototypes/zomato_prototype.py:63-180`
- **TWF handler (state machine template):** `services/telegram-bot/twf_handler.py`
- **TWF tools (trigger JSON template):** `services/annie-voice/twf_tools.py`
- **Zomato MCP config:** `memory/project_zomato_mcp_integration.md`
- **Rajesh's address_id:** `233093817` (Home HSR)

## Previous Session Context
- `docs/NEXT-SESSION-ZOMATO-MCP.md` — original TODO list (items 2-5 still pending: Zepto/Blinkit login, Swiggy Instamart, Swiggy Dineout, ADB history)