# @alma/wa-connector — the most powerful WhatsApp→Claude connector (SPEC)

Iddo (2026-06-06): "the most powerful WhatsApp connector to OUR Claude, from scratch."
Resolved per the [[inquiry-verdict-wip-rail]] (reuse-or-justify): **don't reimplement the WhatsApp
protocol** (Noise handshake + multi-device E2E = months reimplementing a mature rock, and the verdict's
Root Cause #2 was literally "4 half-built WhatsApp bridges"). **"Ours from scratch" = OUR power layer
on top of the proven transport rock.** That's where the value is — not the handshake.

## Architecture (LEGO, ALMAWARE standard)
```
WhatsApp  ⇄  [TRANSPORT ROCK]            [OUR POWER LAYER — built from scratch]
              wa-whatsmeow (Go/whatsmeow)   brain.py + router + memory + council
              · already paired (.db)         · context per conversation
              · key-free Claude Opus          · Claude Opus via Max-CLI shim (key-free)
              · POST /send (+ anti-flood)     · optional multi-AI council (multichat)
              · /health                       · long-term memory (cortex)
              · NEW: POST incoming → us        · tools / automations / interface contracts
```
**The seam:** add ONE thing to the rock — an *incoming webhook*: on each owner message, wa-whatsmeow
POSTs `{from,text,chat}` to our brain (`http://127.0.0.1:8770/incoming`) instead of calling Claude
inline. Our brain decides the reply (context + memory + Opus, optionally the council) and sends it back
via the rock's existing `POST /send`. Clean contract; the rock stays a dumb, reliable transport.

## Why this is "the most powerful" (vs. the inline bridge it replaces)
1. **Conversation context + memory** — not stateless one-shots; remembers the thread + long-term cortex.
2. **Opus brain, key-free** — via the Max-CLI shim ([[claude-max-cli-keyfree-shim]]).
3. **Council mode** — can fan a hard question to the multi-AI chat ([[multi-ai-chat-module]]) and answer with the best.
4. **Tools/automations** — pluggable skills (reminders, search, home-control) per the standard.
5. **Multi-recipient + anti-flood** — RateLimiter already in /send; our router enforces one-considered-message ([[never-flood-people-with-messages]]).
6. **Interface contract** — implements the ALMAWARE `comms` contract → snaps into comms-hub (TG/SMS/mail later).

## Definition of Done (real-senses verified)
1. Owner sends a WA message → our brain (not inline) produces the reply → arrives in WhatsApp. (verified by a real round-trip on the owner self-chat.)
2. Context persists across 3+ turns in a thread.
3. Anti-flood holds (rapid messages don't spam a recipient).
4. Survives restart (autostart task, paired session reused).
5. `/health` green for both rock + brain.

## Build order
- [x] SPEC + DoD (this file).
- [x] `brain.py` — CASCADE power layer: **Grok-first (Iddo "use grok") → Claude Opus fallback** (key-free
      Max-CLI shim), circuit breaker so a logged-out Grok doesn't hang every message, per-chat context,
      anti-flood. Verified 2026-06-06: Grok timeout→breaker→Claude answered; clean Hebrew round-trip.
- [x] Go seam: `wa-whatsmeow/main.go` already POSTs incoming→brain :8770 with inline-Claude fallback. (done)
- [x] Hebrew bug fixed in the shared shim (`_shared/claude_max_client.py`): prompt now via **stdin (UTF-8)**,
      not argv (argv got cp1252-mangled to "????" on Windows). Verified by codepoint/hex inspection.
- [ ] **Needs Iddo:** WhatsApp re-pair (QR) on the rock + grok.com web login — then full live self-chat round-trip.
- [ ] Memory + council + tools (incremental).

## Run (when rock is paired)
1. Rock:  `wa-whatsmeow\start-wa-grok.cmd`  (control :8199, secret set-your-own-sec!, owner 000000000000)
2. Brain: `wa-plugin\start-brain-grok.cmd`  (brain :8770, prefers Grok :8077, falls back to Opus)
   Brain env knobs: BRAIN_PREFER=grok|claude, GROK_TIMEOUT, GROK_COOLDOWN, CLAUDE_MODEL=opus.

## Status
SPEC done. brain.py skeleton started. This is a **SPARKS→ACTIVE candidate** — becomes the next ACTIVE
project once multi-ai-chat closes (grok login). Per the rail, not a 5th parallel bridge: it **consolidates
onto the one working rock** and adds our layer.
