feat: Twilio SMS relay sidecar

[cgfixit]

CyClaw SMS Relay Sidecar

Adds a Twilio webhook sidecar that lets you interact with CyClaw over SMS.

Files

File	Purpose
sms_relay.py	FastAPI app — Twilio webhook, async CyClaw calls, outbound SMS
sms_relay.env.example	Environment variable template
requirements.patch	Adds twilio==9.4.3 (optional, sidecar-only)
docker-compose.patch	sms-relay service stanza under --profile sms

Architecture

Twilio → ngrok → sms_relay :8788 → CyClaw :8787
                    ↑
              ACK immediately (<Response/>)
              then async POST /query
              then outbound SMS via Twilio REST

Confirm state machine

When CyClaw returns needs_confirm=true, the sender receives the confirm message and can reply:

• local → offline best-effort (the only working path in default mode=offline)
• grok → online via Grok (requires mode=hybrid + grok.enabled=true)
• claude → online via Claude (requires mode=hybrid + claude.enabled=true)
• cancel → clear pending state
• more → resend last answer (available any time)

⚠️ Important config note

Default config.yaml has app.mode=offline, grok.enabled=false, claude.enabled=false. Only local confirm will produce an answer until you enable online providers.

Security posture (matches existing CyClaw hardening)

• Loopback-only Docker port publish (127.0.0.1:8788)
• Non-root user, no-new-privileges, all caps dropped, read-only root fs
• Credentials via env_file only — never baked into image
• Twilio signature validation is a TODO (placeholder comment in code)

Not yet done (future PRs)

• Dockerfile.sms_relay — thin image build (referenced in docker-compose.patch)
• Twilio request-signature validation (X-Twilio-Signature)
• Per-sender rate limiting
• Persistent state (Redis/sqlite) for multi-worker deploy