echo-core/HANDOFF.md

# Echo Core — Session Handoff

**Data:** 2026-02-14
**Proiect:** ~/echo-core/ (inlocuire completa OpenClaw)
**Plan complet:** ~/.claude/plans/enumerated-noodling-floyd.md

---

## Status curent: Stage 13 + Setup Wizard — COMPLET. Toate stages finalizate.

### Stages completate (toate committed):
- **Stage 1** (f2973aa): Project Bootstrap — structura, git, venv, copiere fisiere din clawd
- **Stage 2** (010580b): Secrets Manager — keyring, CLI `echo secrets set/list/test`
- **Stage 3** (339866b): Claude CLI Wrapper — start/resume/clear sessions cu `claude --resume`
- **Stage 4** (6cd155b): Discord Bot Minimal — online, /ping, /channel add, /admin add, /setup
- **Stage 5** (a1a6ca9): Discord + Claude Chat — conversatii complete, typing indicator, message split
- **Stage 6** (5bdceff): Model Selection — /model opus/sonnet/haiku, default per canal
- **Stage 7** (09d3de0): CLI Tool — echo status/doctor/restart/logs/sessions/channel/send
- **Stage 8** (24a4d87): Cron Scheduler — APScheduler, /cron add/list/run/enable/disable
- **Stage 9** (0bc4b8c): Heartbeat — verificari periodice (email, calendar, kb index, git)
- **Stage 10** (0ecfa63): Memory Search — Ollama all-minilm embeddings + SQLite semantic search
- **Stage 10.5** (85c72e4): Rename secrets.py, enhanced /status, usage tracking
- **Stage 11** (d1bb67a): Security Hardening — prompt injection, invocation/security logging, extended doctor
- **Stage 12** (2d8e56d): Telegram Bot — python-telegram-bot, commands, inline keyboards, concurrent with Discord
- **Stage 13** (80502b7 + 624eb09): WhatsApp Bridge — Baileys Node.js bridge + Python adapter, polling, group chat, CLI commands
- **Systemd** (6454f0f): Echo Core + WhatsApp bridge as systemd user services, CLI uses systemctl
- **Setup Wizard** (setup.sh): Interactive onboarding — 10-step wizard, idempotent, bridges Discord/Telegram/WhatsApp

### Total teste: 440 PASS (zero failures)

---

## Ce a fost implementat in Stage 13:

1. **bridge/whatsapp/** — Node.js WhatsApp bridge:
   - Baileys (@whiskeysockets/baileys) — lightweight, no Chromium
   - Express HTTP server on localhost:8098
   - Endpoints: GET /status, GET /qr, POST /send, GET /messages
   - QR code generation as base64 PNG for device linking
   - Session persistence in bridge/whatsapp/auth/
   - Reconnection with exponential backoff (max 5 attempts)
   - Message queue: incoming text messages queued, drained on poll
   - Graceful shutdown on SIGTERM/SIGINT

2. **src/adapters/whatsapp.py** — Python WhatsApp adapter:
   - Polls Node.js bridge every 2s via httpx
   - Routes through existing router.py (same as Discord/Telegram)
   - Separate auth: whatsapp.owner + whatsapp.admins (phone numbers)
   - Private chat: admin-only (unauthorized logged to security.log)
   - Group chat: registered chats processed, uses group JID as channel_id
   - Commands: /clear, /status handled inline
   - Other commands and messages routed to Claude via route_message
   - Message splitting at 4096 chars
   - Wait-for-bridge logic on startup (30 retries, 5s interval)

3. **main.py** — Concurrent execution:
   - Discord + Telegram + WhatsApp in same event loop via asyncio.gather
   - WhatsApp optional: enabled via config.json `whatsapp.enabled`
   - No new secrets needed (bridge URL configured in config.json)

4. **config.json** — New sections:
   - `whatsapp: {enabled, bridge_url, owner, admins}`
   - `whatsapp_channels: {}`

5. **cli.py** — New commands:
   - `echo whatsapp status` — check bridge connection
   - `echo whatsapp qr` — show QR code instructions

6. **.gitignore** — Added bridge/whatsapp/node_modules/ and auth/

---

## Setup WhatsApp:

```bash
# 1. Install Node.js bridge dependencies:
cd ~/echo-core/bridge/whatsapp && npm install

# 2. Start the bridge:
node bridge/whatsapp/index.js
# → QR code will appear — scan with WhatsApp (Linked Devices)

# 3. Enable in config.json:
#   "whatsapp": {"enabled": true, "bridge_url": "http://127.0.0.1:8098", "owner": "PHONE", "admins": []}

# 4. Restart Echo Core:
echo restart

# 5. Send a message from WhatsApp to the linked number
```

---

## Setup Wizard (`setup.sh`):

Script interactiv de onboarding pentru instalari noi sau reconfigurare. 10 pasi:

| Step | Ce face |
|------|---------|
| 0. Welcome | ASCII art, detecteaza setup anterior (`.setup-meta.json`) |
| 1. Prerequisites | Python 3.12+ (hard), pip (hard), Claude CLI (hard), Node 22+ / curl / systemctl (warn) |
| 2. Venv | Creeaza `.venv/`, instaleaza `requirements.txt` cu spinner |
| 3. Identity | Bot name, owner Discord ID, admin IDs — citeste defaults din config existent |
| 4. Discord | Token input (masked), valideaza via `/users/@me`, stocheaza in keyring |
| 5. Telegram | Token via BotFather, valideaza via `/getMe`, stocheaza in keyring |
| 6. WhatsApp | Auto-skip daca lipseste Node.js, `npm install`, telefon owner, instructiuni QR |
| 7. Config | Merge inteligent in `config.json` via Python, backup automat cu timestamp |
| 8. Systemd | Genereaza + enable `echo-core.service` + `echo-whatsapp-bridge.service` |
| 9. Health | Valideaza JSON, secrets keyring, dirs writable, Claude CLI, service status |
| 10. Summary | Tabel cu checkmarks, scrie `.setup-meta.json`, next steps |

**Idempotent:** re-run safe, intreaba "Replace?" (default N) pentru tot ce exista. Backup automat config.json.

```bash
# Fresh install
cd ~/echo-core && bash setup.sh

# Re-run (preserva config + secrets existente)
bash setup.sh
```

---

## Fisiere cheie:

| Fisier | Descriere |
|--------|-----------|
| `src/main.py` | Entry point — Discord + Telegram + WhatsApp + scheduler + heartbeat |
| `src/claude_session.py` | Claude Code CLI wrapper cu --resume, injection protection |
| `src/router.py` | Message routing (comanda vs Claude) |
| `src/scheduler.py` | APScheduler cron jobs |
| `src/heartbeat.py` | Verificari periodice |
| `src/memory_search.py` | Semantic search — Ollama embeddings + SQLite |
| `src/credential_store.py` | Credential broker (keyring) |
| `src/config.py` | Config loader (config.json) |
| `src/adapters/discord_bot.py` | Discord bot cu slash commands |
| `src/adapters/telegram_bot.py` | Telegram bot cu commands + inline keyboards |
| `src/adapters/whatsapp.py` | WhatsApp adapter — polls Node.js bridge |
| `bridge/whatsapp/index.js` | Node.js WhatsApp bridge — Baileys + Express |
| `cli.py` | CLI: echo status/doctor/restart/logs/secrets/cron/heartbeat/memory/whatsapp |
| `setup.sh` | Interactive setup wizard — 10-step onboarding, idempotent |
| `config.json` | Runtime config (channels, telegram_channels, whatsapp, admins, models) |

## Decizii arhitecturale:
- **Claude invocation**: Claude Code CLI cu `--resume` pentru sesiuni persistente
- **Credentials**: keyring (nu plain text pe disk), subprocess isolation
- **Discord**: slash commands (`/`), canale asociate dinamic
- **Telegram**: commands + inline keyboards, @mention/reply in groups
- **WhatsApp**: Baileys Node.js bridge + Python polling adapter, separate auth namespace
- **Cron**: APScheduler, sesiuni izolate per job, `--allowedTools` per job
- **Heartbeat**: verificari periodice, quiet hours (23-08), state tracking
- **Memory Search**: Ollama all-minilm (384 dim), SQLite, cosine similarity
- **Security**: prompt injection markers, separate security.log, extended doctor
- **Concurrency**: Discord + Telegram + WhatsApp in same asyncio event loop via gather

## Infrastructura:
- Ollama: http://10.0.20.161:11434 (all-minilm, llama3.2, nomic-embed-text)