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:

# 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.

# 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 tool (instalat ca eco in ~/.local/bin/ de setup.sh)
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)