Marius Mutu
ff9b9a0d1d
Replaces 5s polling on /echo/ralph.html with EventSource streaming and adds
a rollback control for the running Ralph cards.
Server (dashboard/handlers/ralph.py):
- /api/ralph/stream — Server-Sent Events. Emits `event: status` whenever a
signature over the projects' state changes (poll filesystem at 2s); emits
`event: heartbeat` every 30s to keep proxies happy. Disables proxy
buffering via X-Accel-Buffering:no.
- /api/ralph/<slug>/rollback (POST) — runs `git revert --no-edit HEAD` in
the project; falls back to `git reset --hard HEAD~1` only if revert
reports conflict. After rolling back the commit, decrements `passes` on
the last user story marked complete in prd.json (atomic temp+rename
write, same pattern as ralph_dag.py). Returns
`{success, message, reverted_commit, story_reverted, method}`.
- _ralph_validate_slug tightened to a strict regex (alphanum + dash +
underscore, ≤64 chars) plus explicit ../, /, \ rejection. All previously
accepted slugs still pass; URL-encoded traversal and shell metachars
now blocked before the filesystem is touched.
- _ralph_collect_status / _ralph_signature factored out of
handle_ralph_status so the SSE loop can reuse them and detect changes
cheaply.
Server (dashboard/api.py):
- HTTPServer → ThreadingHTTPServer with daemon_threads=True. SSE is a
long-lived response; without threading a single client would block all
other dashboard endpoints.
- /api/ralph/stream (GET) and /api/ralph/<slug>/rollback (POST) wired
into the dispatch.
Client (dashboard/ralph.html):
- EventSource('/api/ralph/stream') with permanent fallback to 5s polling
when readyState=CLOSED (no server, CORS blocked, browser without SSE).
- Indicator badge: 🟢 Live (SSE), ⏱ Polling (fallback), Offline.
- Rollback button (undo-2 icon) on running cards; native confirm() with
message: "Asta va da git revert HEAD pe <slug> și va decrementa ultima
story trecută. Continui?"
Tests (tests/test_dashboard_ralph_endpoint.py, +20 cases):
- Strict slug validator: underscore allowed, >64 rejected, special chars
/ backslash / URL-encoded traversal rejected.
- _ralph_collect_status + _ralph_signature: stable when nothing changes,
flips when project added or `passes` toggles.
- Rollback: invalid slug → 400, non-git project → 400, real two-commit
repo revert succeeds and decrements last passing story (US-002 goes
passes:false while US-001 stays passes:true), no-passing-stories case
succeeds with story_reverted=None, response shape contract, atomic
helper leaves no .tmp file behind.
- API routing smoke: confirms ThreadingHTTPServer + stream + rollback
references present in dashboard/api.py.
39/39 tests pass on tests/test_dashboard_ralph_endpoint.py. Pre-existing
failures in test_dashboard_constants.py::test_base_dir_is_echo_core (the
worktree dir is `echo-core-realtime`, not `echo-core`) and
test_dashboard_unified_index.py::test_index_has_all_panels are unrelated
to this change and reproduced on master.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Echo Core
AI-powered personal assistant bot with Discord, Telegram, and WhatsApp bridges. Uses Claude Code CLI for conversation, with persistent sessions, cron scheduling, semantic memory search, and heartbeat monitoring.
Quick Start
# Interactive setup wizard (recommended for first install)
bash setup.sh
The wizard handles prerequisites, virtual environment, bridge tokens, config, and systemd services in 10 guided steps.
Manual Setup
# 1. Create venv and install dependencies
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# 2. Store Discord token in keyring
./cli.py secrets set discord_token
# 3. Edit config.json (bot name, owner ID, channels)
# 4. Start
systemctl --user start echo-core
Architecture
┌─────────────┐
│ Claude CLI │
└──────┬──────┘
│
┌──────┴──────┐
│ Router │
└──────┬──────┘
┌────────────┼────────────┐
│ │ │
┌─────┴─────┐ ┌───┴───┐ ┌──────┴──────┐
│ Discord │ │Telegram│ │ WhatsApp │
│ (d.py) │ │(ptb) │ │(Baileys+py) │
└────────────┘ └────────┘ └─────────────┘
- Discord: slash commands via discord.py
- Telegram: commands + inline keyboards via python-telegram-bot
- WhatsApp: Node.js Baileys bridge + Python polling adapter
- All three run concurrently in the same asyncio event loop
Key Components
| Component | Description |
|---|---|
src/main.py |
Entry point — starts all adapters + scheduler + heartbeat |
src/router.py |
Routes messages to Claude or handles commands |
src/claude_session.py |
Claude Code CLI wrapper with --resume sessions |
src/credential_store.py |
Keyring-based secrets manager |
src/scheduler.py |
APScheduler cron jobs |
src/heartbeat.py |
Periodic health checks |
src/memory_search.py |
Ollama embeddings + SQLite semantic search |
cli.py |
CLI tool — status, doctor, logs, secrets, cron, etc. |
setup.sh |
Interactive 10-step setup wizard |
bridge/whatsapp/ |
Node.js WhatsApp bridge (Baileys + Express) |
CLI Usage
The setup wizard installs eco as a global command (~/.local/bin/eco):
eco status # Bot online/offline, uptime
eco doctor # Full diagnostic check
eco restart # Restart the service
eco restart --bridge # Restart bot + WhatsApp bridge
eco stop # Stop the service
eco logs # Tail echo-core.log (last 20 lines)
eco logs 50 # Last 50 lines
eco secrets list # Show stored credentials
eco secrets set <name> # Store a secret in keyring
eco secrets test # Check required secrets
eco sessions list # Active Claude sessions
eco sessions clear # Clear all sessions
eco channel list # Registered Discord channels
eco cron list # Show scheduled jobs
eco cron run <name> # Force-run a cron job
eco memory search "<query>" # Semantic search in memory
eco memory reindex # Rebuild search index
eco heartbeat # Run health checks
eco whatsapp status # WhatsApp bridge connection
eco whatsapp qr # QR code pairing instructions
eco send <alias> <message> # Send message via router
Configuration
config.json — runtime configuration:
{
"bot": {
"name": "Echo",
"default_model": "opus",
"owner": "DISCORD_USER_ID",
"admins": ["TELEGRAM_USER_ID"]
},
"channels": { },
"telegram_channels": { },
"whatsapp": {
"enabled": true,
"bridge_url": "http://127.0.0.1:8098",
"owner": "PHONE_NUMBER"
},
"whatsapp_channels": { }
}
Secrets (Discord/Telegram tokens) are stored in the system keyring, not in config files.
Services
Echo Core runs as systemd user services:
systemctl --user start echo-core # Start bot
systemctl --user start echo-whatsapp-bridge # Start WA bridge
systemctl --user status echo-core # Check status
journalctl --user -u echo-core -f # Follow logs
Requirements
- Python 3.12+
- Claude Code CLI
- Node.js 22+ (only for WhatsApp bridge)
Tests
source .venv/bin/activate
pytest tests/
440 tests, zero failures.