calvyn-code 0.14.0

package/optional-skills/productivity/telephony/scripts/telephony.py

@@ -0,0 +1,1343 @@
+#!/usr/bin/env python3
+"""Telephony helper for the Hermes optional telephony skill.
+
+Capabilities:
+- Persist telephony provider credentials to ~/.hermes/.env
+- Search for, buy, and remember Twilio phone numbers
+- Make direct Twilio calls (TwiML <Say> or <Play>)
+- Send SMS / MMS via Twilio
+- Poll inbound SMS for an owned Twilio number using only this script + state
+- Import a Twilio number into Vapi and persist the returned Vapi phone_number_id
+- Make outbound AI voice calls via Bland.ai or Vapi
+
+This file intentionally uses Python stdlib HTTP clients so the skill can run in a
+minimal environment with no extra pip installs.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import re
+import sys
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from html import escape as xml_escape
+from pathlib import Path
+from typing import Any
+
+TWILIO_API_BASE = "https://api.twilio.com/2010-04-01/Accounts"
+VAPI_API_BASE = "https://api.vapi.ai"
+BLAND_API_BASE = "https://api.bland.ai/v1"
+
+BLAND_DEFAULT_VOICE = "mason"
+BLAND_DEFAULT_MODEL = "enhanced"
+BLAND_VOICES = {
+    "mason": "Male, natural, friendly (recommended)",
+    "josh": "Male, conversational",
+    "ryan": "Male, professional",
+    "matt": "Male, casual",
+    "evelyn": "Female, natural, warm (recommended)",
+    "tina": "Female, warm, friendly",
+    "june": "Female, conversational",
+}
+
+VAPI_DEFAULT_VOICE_PROVIDER = "11labs"
+VAPI_DEFAULT_VOICE_ID = "cjVigY5qzO86Huf0OWal"  # ElevenLabs "Eric"
+VAPI_DEFAULT_MODEL = "gpt-4o"
+TWILIO_DEFAULT_TTS_VOICE = "Polly.Joanna"
+DEFAULT_AI_PROVIDER = "bland"
+STATE_VERSION = 1
+
+
+class TelephonyError(RuntimeError):
+    """Domain-specific failure surfaced to the skill/user."""
+
+
+@dataclass
+class OwnedTwilioNumber:
+    sid: str
+    phone_number: str
+    friendly_name: str
+    capabilities: dict[str, Any]
+
+
+def _hermes_home() -> Path:
+    return Path(os.environ.get("HERMES_HOME", "~/.hermes")).expanduser()
+
+
+def _env_path() -> Path:
+    return _hermes_home() / ".env"
+
+
+def _config_path() -> Path:
+    return _hermes_home() / "config.yaml"
+
+
+def _state_path() -> Path:
+    return _hermes_home() / "telephony_state.json"
+
+
+def _load_root_config() -> dict[str, Any]:
+    path = _config_path()
+    if not path.exists():
+        return {}
+    try:
+        import yaml  # optional dependency; Hermes already ships PyYAML
+    except Exception:
+        return {}
+    try:
+        with path.open("r", encoding="utf-8") as handle:
+            data = yaml.safe_load(handle) or {}
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _config_lookup(*paths: tuple[str, ...], default: str = "") -> str:
+    root = _load_root_config()
+    for path in paths:
+        node: Any = root
+        for key in path:
+            if not isinstance(node, dict):
+                node = None
+                break
+            node = node.get(key)
+        if node not in (None, "") and not isinstance(node, dict):
+            return str(node)
+    return default
+
+
+def _load_dotenv_values(path: Path | None = None) -> dict[str, str]:
+    env_file = path or _env_path()
+    if not env_file.exists():
+        return {}
+    values: dict[str, str] = {}
+    for raw_line in env_file.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = raw_line.partition("=")
+        key = key.strip()
+        value = value.strip()
+        if value.startswith('"') and value.endswith('"') and len(value) >= 2:
+            value = value[1:-1].replace('\\"', '"').replace('\\\\', '\\')
+        values[key] = value
+    return values
+
+
+def _env_or_config(env_key: str, *config_paths: tuple[str, ...], default: str = "") -> str:
+    value = os.environ.get(env_key, "")
+    if value:
+        return value
+    dotenv_value = _load_dotenv_values().get(env_key, "")
+    if dotenv_value:
+        return dotenv_value
+    return _config_lookup(*config_paths, default=default)
+
+
+def _load_state(path: Path | None = None) -> dict[str, Any]:
+    state_file = path or _state_path()
+    if not state_file.exists():
+        return {"version": STATE_VERSION}
+    try:
+        data = json.loads(state_file.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            data.setdefault("version", STATE_VERSION)
+            return data
+    except Exception:
+        pass
+    return {"version": STATE_VERSION}
+
+
+def _save_state(state: dict[str, Any], path: Path | None = None) -> Path:
+    state_file = path or _state_path()
+    state_file.parent.mkdir(parents=True, exist_ok=True)
+    state_file.write_text(json.dumps(state, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return state_file
+
+
+def _quote_env_value(value: str) -> str:
+    if re.fullmatch(r"[A-Za-z0-9_./:+@-]+", value):
+        return value
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+    return f'"{escaped}"'
+
+
+def _upsert_env_file(updates: dict[str, str], env_path: Path | None = None) -> Path:
+    path = env_path or _env_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists():
+        lines = path.read_text(encoding="utf-8").splitlines()
+    else:
+        lines = []
+
+    seen: set[str] = set()
+    new_lines: list[str] = []
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or "=" not in line:
+            new_lines.append(line)
+            continue
+        key, _, _rest = line.partition("=")
+        key = key.strip()
+        if key in updates:
+            new_lines.append(f"{key}={_quote_env_value(str(updates[key]))}")
+            seen.add(key)
+        else:
+            new_lines.append(line)
+
+    if new_lines and new_lines[-1].strip():
+        new_lines.append("")
+    for key, value in updates.items():
+        if key not in seen:
+            new_lines.append(f"{key}={_quote_env_value(str(value))}")
+
+    path.write_text("\n".join(new_lines).rstrip() + "\n", encoding="utf-8")
+    return path
+
+
+def _normalize_phone(number: str) -> str:
+    if not number:
+        raise TelephonyError("Phone number is required")
+    trimmed = number.strip()
+    if not trimmed.startswith("+"):
+        raise TelephonyError(
+            f"Phone number must be E.164 format (for example +15551234567), got: {number}"
+        )
+    digits = "+" + re.sub(r"\D", "", trimmed)
+    if len(digits) < 8:
+        raise TelephonyError(f"Phone number looks too short: {number}")
+    return digits
+
+
+def _mask_phone(number: str) -> str:
+    digits = re.sub(r"\D", "", number or "")
+    if len(digits) < 4:
+        return "***"
+    return f"***-***-{digits[-4:]}"
+
+
+def _parse_twilio_date(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    try:
+        dt = parsedate_to_datetime(value)
+        return dt.astimezone(timezone.utc) if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+    except Exception:
+        return None
+
+
+def _json_request(
+    method: str,
+    url: str,
+    *,
+    headers: dict[str, str] | None = None,
+    params: dict[str, Any] | None = None,
+    form: dict[str, Any] | None = None,
+    json_body: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    if params:
+        query = urllib.parse.urlencode(params, doseq=True)
+        url = f"{url}?{query}"
+
+    request_headers = dict(headers or {})
+    body: bytes | None = None
+    if json_body is not None:
+        body = json.dumps(json_body).encode("utf-8")
+        request_headers.setdefault("Content-Type", "application/json")
+    elif form is not None:
+        body = urllib.parse.urlencode(form, doseq=True).encode("utf-8")
+        request_headers.setdefault("Content-Type", "application/x-www-form-urlencoded")
+
+    req = urllib.request.Request(url, data=body, headers=request_headers, method=method.upper())
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            payload = resp.read().decode("utf-8")
+            return json.loads(payload) if payload else {}
+    except urllib.error.HTTPError as exc:
+        body_text = exc.read().decode("utf-8", errors="replace") if exc.fp else ""
+        try:
+            parsed = json.loads(body_text) if body_text else {}
+        except Exception:
+            parsed = {"raw": body_text}
+        raise TelephonyError(f"HTTP {exc.code} from {url}: {parsed or exc.reason}") from exc
+    except urllib.error.URLError as exc:
+        raise TelephonyError(f"Connection error for {url}: {exc.reason}") from exc
+
+
+def _twilio_creds() -> tuple[str, str]:
+    sid = _env_or_config(
+        "TWILIO_ACCOUNT_SID",
+        ("telephony", "twilio", "account_sid"),
+        ("phone", "twilio", "account_sid"),
+    )
+    token = _env_or_config(
+        "TWILIO_AUTH_TOKEN",
+        ("telephony", "twilio", "auth_token"),
+        ("phone", "twilio", "auth_token"),
+    )
+    if not sid or not token:
+        raise TelephonyError(
+            "Twilio credentials are not configured. Use 'save-twilio' or set "
+            "TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN in ~/.hermes/.env."
+        )
+    return sid, token
+
+
+def _twilio_basic_headers() -> dict[str, str]:
+    sid, token = _twilio_creds()
+    auth = base64.b64encode(f"{sid}:{token}".encode("utf-8")).decode("ascii")
+    return {"Authorization": f"Basic {auth}"}
+
+
+def _twilio_request(method: str, path: str, *, params=None, form=None) -> dict[str, Any]:
+    sid, _token = _twilio_creds()
+    return _json_request(
+        method,
+        f"{TWILIO_API_BASE}/{sid}/{path.lstrip('/')}",
+        headers=_twilio_basic_headers(),
+        params=params,
+        form=form,
+    )
+
+
+def _twilio_owned_numbers(limit: int = 50) -> list[OwnedTwilioNumber]:
+    payload = _twilio_request("GET", "IncomingPhoneNumbers.json", params={"PageSize": limit})
+    items = payload.get("incoming_phone_numbers", []) or []
+    results: list[OwnedTwilioNumber] = []
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        caps = item.get("capabilities") if isinstance(item.get("capabilities"), dict) else {}
+        results.append(
+            OwnedTwilioNumber(
+                sid=str(item.get("sid", "")),
+                phone_number=str(item.get("phone_number", "")),
+                friendly_name=str(item.get("friendly_name", "")),
+                capabilities=caps,
+            )
+        )
+    return results
+
+
+def _remember_twilio_number(
+    *,
+    phone_number: str,
+    phone_sid: str = "",
+    save_env: bool = False,
+    state_path: Path | None = None,
+    env_path: Path | None = None,
+) -> dict[str, Any]:
+    state = _load_state(state_path)
+    twilio_state = state.setdefault("twilio", {})
+    twilio_state["default_phone_number"] = phone_number
+    if phone_sid:
+        twilio_state["default_phone_sid"] = phone_sid
+    _save_state(state, state_path)
+
+    saved_env_keys: list[str] = []
+    if save_env:
+        updates = {"TWILIO_PHONE_NUMBER": phone_number}
+        if phone_sid:
+            updates["TWILIO_PHONE_NUMBER_SID"] = phone_sid
+        _upsert_env_file(updates, env_path)
+        saved_env_keys = sorted(updates)
+
+    return {
+        "state_path": str(state_path or _state_path()),
+        "saved_env_keys": saved_env_keys,
+    }
+
+
+def _remember_vapi_number(
+    *,
+    phone_number_id: str,
+    save_env: bool = False,
+    state_path: Path | None = None,
+    env_path: Path | None = None,
+) -> dict[str, Any]:
+    state = _load_state(state_path)
+    vapi_state = state.setdefault("vapi", {})
+    vapi_state["phone_number_id"] = phone_number_id
+    _save_state(state, state_path)
+
+    saved_env_keys: list[str] = []
+    if save_env:
+        _upsert_env_file({"VAPI_PHONE_NUMBER_ID": phone_number_id}, env_path)
+        saved_env_keys = ["VAPI_PHONE_NUMBER_ID"]
+
+    return {
+        "state_path": str(state_path or _state_path()),
+        "saved_env_keys": saved_env_keys,
+    }
+
+
+def _resolve_twilio_number(identifier: str | None = None) -> OwnedTwilioNumber:
+    if identifier:
+        wanted = identifier.strip()
+        normalized = None
+        if wanted.startswith("+"):
+            normalized = _normalize_phone(wanted)
+        for item in _twilio_owned_numbers(limit=100):
+            if item.sid == wanted or item.phone_number == normalized:
+                return item
+        raise TelephonyError(f"Could not find an owned Twilio number matching {identifier}")
+
+    env_number = _env_or_config(
+        "TWILIO_PHONE_NUMBER",
+        ("telephony", "twilio", "phone_number"),
+        ("phone", "twilio", "phone_number"),
+    )
+    env_sid = _env_or_config(
+        "TWILIO_PHONE_NUMBER_SID",
+        ("telephony", "twilio", "phone_number_sid"),
+        ("phone", "twilio", "phone_number_sid"),
+    )
+    state = _load_state()
+    twilio_state = state.get("twilio", {}) if isinstance(state.get("twilio"), dict) else {}
+    preferred_number = env_number or str(twilio_state.get("default_phone_number", ""))
+    preferred_sid = env_sid or str(twilio_state.get("default_phone_sid", ""))
+
+    owned = _twilio_owned_numbers(limit=100)
+    if preferred_sid:
+        for item in owned:
+            if item.sid == preferred_sid:
+                return item
+    if preferred_number:
+        normalized = _normalize_phone(preferred_number)
+        for item in owned:
+            if item.phone_number == normalized:
+                return item
+    if len(owned) == 1:
+        return owned[0]
+
+    raise TelephonyError(
+        "No default Twilio phone number is set. Use 'twilio-buy --save-env', "
+        "'twilio-set-default', or set TWILIO_PHONE_NUMBER in ~/.hermes/.env."
+    )
+
+
+def _vapi_api_key() -> str:
+    return _env_or_config(
+        "VAPI_API_KEY",
+        ("telephony", "vapi", "api_key"),
+        ("phone", "vapi", "api_key"),
+    )
+
+
+def _vapi_phone_number_id() -> str:
+    state = _load_state()
+    vapi_state = state.get("vapi", {}) if isinstance(state.get("vapi"), dict) else {}
+    return _env_or_config(
+        "VAPI_PHONE_NUMBER_ID",
+        ("telephony", "vapi", "phone_number_id"),
+        ("phone", "vapi", "phone_number_id"),
+        default=str(vapi_state.get("phone_number_id", "")),
+    )
+
+
+def _bland_api_key() -> str:
+    return _env_or_config(
+        "BLAND_API_KEY",
+        ("telephony", "bland", "api_key"),
+        ("phone", "bland", "api_key"),
+    )
+
+
+def _ai_provider(default: str = DEFAULT_AI_PROVIDER) -> str:
+    return _env_or_config(
+        "PHONE_PROVIDER",
+        ("telephony", "provider"),
+        ("phone", "provider"),
+        default=default,
+    ).lower().strip()
+
+
+def _twilio_search_numbers(
+    *,
+    country: str = "US",
+    area_code: str | None = None,
+    contains: str | None = None,
+    limit: int = 10,
+    sms_enabled: bool = True,
+    voice_enabled: bool = True,
+) -> dict[str, Any]:
+    params: dict[str, Any] = {
+        "PageSize": max(1, min(limit, 20)),
+        "SmsEnabled": str(bool(sms_enabled)).lower(),
+        "VoiceEnabled": str(bool(voice_enabled)).lower(),
+    }
+    if area_code:
+        params["AreaCode"] = str(area_code)
+    if contains:
+        params["Contains"] = str(contains)
+
+    payload = _twilio_request(
+        "GET",
+        f"AvailablePhoneNumbers/{country.upper()}/Local.json",
+        params=params,
+    )
+    items = payload.get("available_phone_numbers", []) or []
+    return {
+        "success": True,
+        "country": country.upper(),
+        "count": len(items),
+        "numbers": [
+            {
+                "phone_number": item.get("phone_number"),
+                "friendly_name": item.get("friendly_name"),
+                "locality": item.get("locality"),
+                "region": item.get("region"),
+                "postal_code": item.get("postal_code"),
+                "iso_country": item.get("iso_country"),
+                "capabilities": {
+                    "voice": item.get("voice_enabled"),
+                    "sms": item.get("sms_enabled"),
+                    "mms": item.get("mms_enabled"),
+                },
+            }
+            for item in items
+            if isinstance(item, dict)
+        ],
+    }
+
+
+def _twilio_buy_number(
+    phone_number: str,
+    *,
+    save_env: bool = False,
+    state_path: Path | None = None,
+    env_path: Path | None = None,
+) -> dict[str, Any]:
+    normalized = _normalize_phone(phone_number)
+    payload = _twilio_request("POST", "IncomingPhoneNumbers.json", form={"PhoneNumber": normalized})
+    purchased = {
+        "success": True,
+        "provider": "twilio",
+        "phone_number": payload.get("phone_number", normalized),
+        "phone_sid": payload.get("sid"),
+        "friendly_name": payload.get("friendly_name"),
+        "capabilities": payload.get("capabilities", {}),
+        "message": "Twilio number purchased successfully.",
+    }
+    purchased.update(
+        _remember_twilio_number(
+            phone_number=str(purchased["phone_number"]),
+            phone_sid=str(purchased.get("phone_sid") or ""),
+            save_env=save_env,
+            state_path=state_path,
+            env_path=env_path,
+        )
+    )
+    return purchased
+
+
+def _twilio_list_owned() -> dict[str, Any]:
+    owned = _twilio_owned_numbers(limit=100)
+    return {
+        "success": True,
+        "provider": "twilio",
+        "count": len(owned),
+        "numbers": [
+            {
+                "phone_number": item.phone_number,
+                "phone_sid": item.sid,
+                "friendly_name": item.friendly_name,
+                "capabilities": item.capabilities,
+            }
+            for item in owned
+        ],
+    }
+
+
+def _twilio_set_default(identifier: str, *, save_env: bool = False) -> dict[str, Any]:
+    owned = _resolve_twilio_number(identifier)
+    result = {
+        "success": True,
+        "provider": "twilio",
+        "phone_number": owned.phone_number,
+        "phone_sid": owned.sid,
+        "message": "Default Twilio number updated.",
+    }
+    result.update(
+        _remember_twilio_number(
+            phone_number=owned.phone_number,
+            phone_sid=owned.sid,
+            save_env=save_env,
+        )
+    )
+    return result
+
+
+def _twiml_say(message: str, voice: str) -> str:
+    return f"<Response><Say voice=\"{xml_escape(voice)}\">{xml_escape(message)}</Say></Response>"
+
+
+def _twiml_play(audio_url: str) -> str:
+    return f"<Response><Play>{xml_escape(audio_url)}</Play></Response>"
+
+
+def _twilio_call(
+    to_number: str,
+    *,
+    message: str | None = None,
+    audio_url: str | None = None,
+    voice: str = TWILIO_DEFAULT_TTS_VOICE,
+    send_digits: str | None = None,
+    from_identifier: str | None = None,
+    record: bool = False,
+) -> dict[str, Any]:
+    destination = _normalize_phone(to_number)
+    source = _resolve_twilio_number(from_identifier)
+    if bool(message) == bool(audio_url):
+        raise TelephonyError("Provide exactly one of 'message' or 'audio_url' for twilio-call")
+
+    twiml = _twiml_play(audio_url) if audio_url else _twiml_say(message or "", voice)
+    form: dict[str, Any] = {
+        "To": destination,
+        "From": source.phone_number,
+        "Twiml": twiml,
+    }
+    if send_digits:
+        form["SendDigits"] = send_digits
+    if record:
+        form["Record"] = "true"
+
+    payload = _twilio_request("POST", "Calls.json", form=form)
+    return {
+        "success": True,
+        "provider": "twilio",
+        "call_sid": payload.get("sid"),
+        "status": payload.get("status"),
+        "from_phone_number": source.phone_number,
+        "to_phone_number_masked": _mask_phone(destination),
+        "mode": "play" if audio_url else "say",
+        "recording_requested": record,
+        "message": "Twilio call initiated.",
+    }
+
+
+def _twilio_call_status(call_sid: str) -> dict[str, Any]:
+    payload = _twilio_request("GET", f"Calls/{call_sid}.json")
+    return {
+        "success": True,
+        "provider": "twilio",
+        "call_sid": payload.get("sid"),
+        "status": payload.get("status"),
+        "direction": payload.get("direction"),
+        "duration": payload.get("duration"),
+        "from_phone_number": payload.get("from"),
+        "to_phone_number_masked": _mask_phone(str(payload.get("to") or "")),
+        "start_time": payload.get("start_time"),
+        "end_time": payload.get("end_time"),
+        "answered_by": payload.get("answered_by"),
+    }
+
+
+def _twilio_send_sms(
+    to_number: str,
+    body: str,
+    *,
+    media_urls: list[str] | None = None,
+    from_identifier: str | None = None,
+) -> dict[str, Any]:
+    destination = _normalize_phone(to_number)
+    source = _resolve_twilio_number(from_identifier)
+    if not body.strip():
+        raise TelephonyError("SMS body cannot be empty")
+    form: dict[str, Any] = {
+        "To": destination,
+        "From": source.phone_number,
+        "Body": body,
+    }
+    if media_urls:
+        form["MediaUrl"] = media_urls
+    payload = _twilio_request("POST", "Messages.json", form=form)
+    return {
+        "success": True,
+        "provider": "twilio",
+        "message_sid": payload.get("sid"),
+        "status": payload.get("status"),
+        "from_phone_number": source.phone_number,
+        "to_phone_number_masked": _mask_phone(destination),
+        "media_count": len(media_urls or []),
+        "message": "SMS/MMS queued via Twilio.",
+    }
+
+
+def _checkpoint_for_messages(messages: list[dict[str, Any]]) -> tuple[str, str]:
+    if not messages:
+        return "", ""
+    newest = messages[0]
+    return str(newest.get("sid") or ""), str(newest.get("date_sent") or newest.get("date_created") or "")
+
+
+def _messages_after_checkpoint(messages: list[dict[str, Any]], last_sid: str) -> list[dict[str, Any]]:
+    if not last_sid:
+        return messages
+    filtered: list[dict[str, Any]] = []
+    for message in messages:
+        if str(message.get("sid") or "") == last_sid:
+            break
+        filtered.append(message)
+    return filtered
+
+
+def _twilio_inbox(
+    *,
+    limit: int = 20,
+    since_last: bool = False,
+    mark_seen: bool = False,
+    phone_identifier: str | None = None,
+    state_path: Path | None = None,
+) -> dict[str, Any]:
+    owned = _resolve_twilio_number(phone_identifier)
+    payload = _twilio_request(
+        "GET",
+        "Messages.json",
+        params={"To": owned.phone_number, "PageSize": max(1, min(limit, 100))},
+    )
+    raw_messages = payload.get("messages", []) or []
+    messages = [m for m in raw_messages if isinstance(m, dict)]
+
+    state = _load_state(state_path)
+    twilio_state = state.setdefault("twilio", {})
+    last_sid = str(twilio_state.get("last_inbound_message_sid", ""))
+    if since_last:
+        messages = _messages_after_checkpoint(messages, last_sid)
+
+    message_rows = [
+        {
+            "sid": msg.get("sid"),
+            "direction": msg.get("direction"),
+            "status": msg.get("status"),
+            "from_phone_number": msg.get("from"),
+            "to_phone_number": msg.get("to"),
+            "date_sent": msg.get("date_sent"),
+            "body": msg.get("body"),
+            "num_media": msg.get("num_media"),
+        }
+        for msg in messages
+    ]
+
+    if mark_seen and message_rows:
+        last_seen_sid, last_seen_date = _checkpoint_for_messages(message_rows)
+        twilio_state["last_inbound_message_sid"] = last_seen_sid
+        twilio_state["last_inbound_message_date"] = last_seen_date
+        _save_state(state, state_path)
+
+    return {
+        "success": True,
+        "provider": "twilio",
+        "phone_number": owned.phone_number,
+        "count": len(message_rows),
+        "messages": message_rows,
+        "since_last": since_last,
+        "marked_seen": bool(mark_seen and message_rows),
+        "state_path": str(state_path or _state_path()),
+        "last_seen_message_sid": twilio_state.get("last_inbound_message_sid", ""),
+    }
+
+
+def _vapi_import_twilio_number(
+    *,
+    phone_identifier: str | None = None,
+    save_env: bool = False,
+    state_path: Path | None = None,
+    env_path: Path | None = None,
+) -> dict[str, Any]:
+    api_key = _vapi_api_key()
+    if not api_key:
+        raise TelephonyError(
+            "Vapi is not configured. Use 'save-vapi' or set VAPI_API_KEY in ~/.hermes/.env first."
+        )
+    owned = _resolve_twilio_number(phone_identifier)
+    sid, token = _twilio_creds()
+    payload = _json_request(
+        "POST",
+        f"{VAPI_API_BASE}/phone-number",
+        headers={"Authorization": f"Bearer {api_key}"},
+        json_body={
+            "provider": "twilio",
+            "number": owned.phone_number,
+            "twilioAccountSid": sid,
+            "twilioAuthToken": token,
+        },
+    )
+    phone_number_id = str(payload.get("id") or "")
+    if not phone_number_id:
+        raise TelephonyError(f"Vapi did not return a phone number id: {payload}")
+    result = {
+        "success": True,
+        "provider": "vapi",
+        "phone_number_id": phone_number_id,
+        "phone_number": owned.phone_number,
+        "message": "Twilio number imported into Vapi.",
+    }
+    result.update(
+        _remember_vapi_number(
+            phone_number_id=phone_number_id,
+            save_env=save_env,
+            state_path=state_path,
+            env_path=env_path,
+        )
+    )
+    return result
+
+
+def _bland_call(
+    phone_number: str,
+    task: str,
+    *,
+    voice: str | None = None,
+    first_sentence: str | None = None,
+    max_duration: int = 3,
+) -> dict[str, Any]:
+    api_key = _bland_api_key()
+    if not api_key:
+        raise TelephonyError(
+            "Bland.ai is not configured. Use 'save-bland' or set BLAND_API_KEY in ~/.hermes/.env."
+        )
+    normalized = _normalize_phone(phone_number)
+    if voice is None:
+        voice = _env_or_config(
+            "BLAND_DEFAULT_VOICE",
+            ("telephony", "bland", "default_voice"),
+            ("phone", "bland", "default_voice"),
+            default=BLAND_DEFAULT_VOICE,
+        )
+    payload = _json_request(
+        "POST",
+        f"{BLAND_API_BASE}/calls",
+        headers={"authorization": api_key},
+        json_body={
+            "phone_number": normalized,
+            "task": task,
+            "voice": voice,
+            "model": BLAND_DEFAULT_MODEL,
+            "max_duration": max_duration,
+            "record": True,
+            "wait_for_greeting": True,
+            **({"first_sentence": first_sentence} if first_sentence else {}),
+        },
+    )
+    call_id = str(payload.get("call_id") or "")
+    if not call_id:
+        raise TelephonyError(f"Bland.ai returned no call_id: {payload}")
+    return {
+        "success": True,
+        "provider": "bland",
+        "call_id": call_id,
+        "voice": voice,
+        "max_duration_minutes": max_duration,
+        "to_phone_number_masked": _mask_phone(normalized),
+        "message": "AI call queued with Bland.ai.",
+    }
+
+
+def _bland_status(call_id: str, analyze: str | None = None) -> dict[str, Any]:
+    api_key = _bland_api_key()
+    if not api_key:
+        raise TelephonyError("Bland.ai is not configured.")
+    payload = _json_request("GET", f"{BLAND_API_BASE}/calls/{call_id}", headers={"authorization": api_key})
+    result = {
+        "success": True,
+        "provider": "bland",
+        "call_id": call_id,
+        "status": payload.get("status"),
+        "answered_by": payload.get("answered_by"),
+        "duration_minutes": payload.get("call_length"),
+        "transcript": payload.get("concatenated_transcript", ""),
+        "recording_url": payload.get("recording_url"),
+    }
+    if analyze and payload.get("status") == "completed":
+        questions = [[q.strip(), "string"] for q in analyze.split(",") if q.strip()]
+        if questions:
+            analysis = _json_request(
+                "POST",
+                f"{BLAND_API_BASE}/calls/{call_id}/analyze",
+                headers={"authorization": api_key},
+                json_body={"questions": questions},
+            )
+            result["analysis"] = analysis
+    return result
+
+
+def _vapi_call(
+    phone_number: str,
+    task: str,
+    *,
+    voice_id: str | None = None,
+    first_sentence: str | None = None,
+    max_duration: int = 3,
+) -> dict[str, Any]:
+    api_key = _vapi_api_key()
+    if not api_key:
+        raise TelephonyError(
+            "Vapi is not configured. Use 'save-vapi' or set VAPI_API_KEY in ~/.hermes/.env."
+        )
+    phone_number_id = _vapi_phone_number_id()
+    if not phone_number_id:
+        raise TelephonyError(
+            "No Vapi phone number id is configured. Import an owned Twilio number with "
+            "'vapi-import-twilio --save-env' or set VAPI_PHONE_NUMBER_ID in ~/.hermes/.env."
+        )
+    normalized = _normalize_phone(phone_number)
+    voice_provider = _env_or_config(
+        "VAPI_VOICE_PROVIDER",
+        ("telephony", "vapi", "default_voice_provider"),
+        ("phone", "vapi", "default_voice_provider"),
+        default=VAPI_DEFAULT_VOICE_PROVIDER,
+    )
+    if voice_id is None:
+        voice_id = _env_or_config(
+            "VAPI_VOICE_ID",
+            ("telephony", "vapi", "default_voice_id"),
+            ("phone", "vapi", "default_voice_id"),
+            default=VAPI_DEFAULT_VOICE_ID,
+        )
+    model = _env_or_config(
+        "VAPI_MODEL",
+        ("telephony", "vapi", "model"),
+        ("phone", "vapi", "model"),
+        default=VAPI_DEFAULT_MODEL,
+    )
+    assistant = {
+        "model": {
+            "provider": "openai",
+            "model": model,
+            "messages": [{"role": "system", "content": task}],
+        },
+        "voice": {"provider": voice_provider, "voiceId": voice_id},
+        "maxDurationSeconds": max_duration * 60,
+    }
+    if first_sentence:
+        assistant["firstMessage"] = first_sentence
+    payload = _json_request(
+        "POST",
+        f"{VAPI_API_BASE}/call",
+        headers={"Authorization": f"Bearer {api_key}"},
+        json_body={
+            "phoneNumberId": phone_number_id,
+            "customer": {"number": normalized},
+            "assistant": assistant,
+        },
+    )
+    call_id = str(payload.get("id") or "")
+    if not call_id:
+        raise TelephonyError(f"Vapi returned no call id: {payload}")
+    return {
+        "success": True,
+        "provider": "vapi",
+        "call_id": call_id,
+        "voice_provider": voice_provider,
+        "voice_id": voice_id,
+        "max_duration_minutes": max_duration,
+        "to_phone_number_masked": _mask_phone(normalized),
+        "message": "AI call queued with Vapi.",
+    }
+
+
+def _vapi_status(call_id: str) -> dict[str, Any]:
+    api_key = _vapi_api_key()
+    if not api_key:
+        raise TelephonyError("Vapi is not configured.")
+    payload = _json_request(
+        "GET",
+        f"{VAPI_API_BASE}/call/{call_id}",
+        headers={"Authorization": f"Bearer {api_key}"},
+    )
+    return {
+        "success": True,
+        "provider": "vapi",
+        "call_id": call_id,
+        "status": payload.get("status"),
+        "duration_seconds": payload.get("duration"),
+        "ended_reason": payload.get("endedReason"),
+        "transcript": payload.get("transcript", ""),
+        "recording_url": payload.get("recordingUrl"),
+        "summary": payload.get("summary"),
+        "cost": payload.get("cost"),
+    }
+
+
+def _provider_decision_tree() -> list[dict[str, str]]:
+    return [
+        {
+            "need": "I want the agent to own a real number for SMS, inbound polling, or future telephony identity.",
+            "use": "Twilio",
+            "why": "Twilio is the clearest path to provisioning numbers, sending SMS/MMS, polling inbound texts, and later webhook-based inbound telephony.",
+        },
+        {
+            "need": "I only want the easiest outbound AI voice calls right now.",
+            "use": "Bland.ai",
+            "why": "Bland is the simplest outbound AI calling setup: one API key, no separate number import flow.",
+        },
+        {
+            "need": "I want premium conversational voice quality for AI calls, ideally on my own number.",
+            "use": "Twilio + Vapi",
+            "why": "Buy/import the number with Twilio, then import it into Vapi for better voices and more flexible assistants.",
+        },
+        {
+            "need": "I want to call with a prerecorded/custom voice message generated elsewhere.",
+            "use": "Twilio direct call + public audio URL",
+            "why": "Generate or host audio separately, then let Twilio play it with a simple outbound call.",
+        },
+    ]
+
+
+def diagnose() -> dict[str, Any]:
+    state = _load_state()
+    twilio_state = state.get("twilio", {}) if isinstance(state.get("twilio"), dict) else {}
+    vapi_state = state.get("vapi", {}) if isinstance(state.get("vapi"), dict) else {}
+    provider = _ai_provider()
+
+    twilio_sid = _env_or_config(
+        "TWILIO_ACCOUNT_SID",
+        ("telephony", "twilio", "account_sid"),
+        ("phone", "twilio", "account_sid"),
+    )
+    twilio_token = _env_or_config(
+        "TWILIO_AUTH_TOKEN",
+        ("telephony", "twilio", "auth_token"),
+        ("phone", "twilio", "auth_token"),
+    )
+    twilio_phone = _env_or_config(
+        "TWILIO_PHONE_NUMBER",
+        ("telephony", "twilio", "phone_number"),
+        ("phone", "twilio", "phone_number"),
+        default=str(twilio_state.get("default_phone_number", "")),
+    )
+
+    bland_key = _bland_api_key()
+    vapi_key = _vapi_api_key()
+    vapi_phone_id = _vapi_phone_number_id() or str(vapi_state.get("phone_number_id", ""))
+
+    return {
+        "success": True,
+        "state_path": str(_state_path()),
+        "env_path": str(_env_path()),
+        "ai_call_provider": provider,
+        "providers": {
+            "twilio": {
+                "account_sid_configured": bool(twilio_sid),
+                "auth_token_configured": bool(twilio_token),
+                "default_phone_number": twilio_phone,
+                "default_phone_sid": twilio_state.get("default_phone_sid", ""),
+                "last_inbound_message_sid": twilio_state.get("last_inbound_message_sid", ""),
+                "last_inbound_message_date": twilio_state.get("last_inbound_message_date", ""),
+            },
+            "bland": {
+                "configured": bool(bland_key),
+                "default_voice": _env_or_config(
+                    "BLAND_DEFAULT_VOICE",
+                    ("telephony", "bland", "default_voice"),
+                    ("phone", "bland", "default_voice"),
+                    default=BLAND_DEFAULT_VOICE,
+                ),
+            },
+            "vapi": {
+                "configured": bool(vapi_key),
+                "phone_number_id": vapi_phone_id,
+                "voice_provider": _env_or_config(
+                    "VAPI_VOICE_PROVIDER",
+                    ("telephony", "vapi", "default_voice_provider"),
+                    ("phone", "vapi", "default_voice_provider"),
+                    default=VAPI_DEFAULT_VOICE_PROVIDER,
+                ),
+                "voice_id": _env_or_config(
+                    "VAPI_VOICE_ID",
+                    ("telephony", "vapi", "default_voice_id"),
+                    ("phone", "vapi", "default_voice_id"),
+                    default=VAPI_DEFAULT_VOICE_ID,
+                ),
+                "model": _env_or_config(
+                    "VAPI_MODEL",
+                    ("telephony", "vapi", "model"),
+                    ("phone", "vapi", "model"),
+                    default=VAPI_DEFAULT_MODEL,
+                ),
+            },
+        },
+        "decision_tree": _provider_decision_tree(),
+        "notes": [
+            "Twilio is the best path for owning a durable phone number, texting, and polling inbound SMS.",
+            "Bland is the easiest path for outbound AI calls only.",
+            "Vapi is best when you want better AI voice quality, usually backed by a Twilio-owned number.",
+            "VoIP numbers are not guaranteed to work for every third-party 2FA flow.",
+        ],
+    }
+
+
+def save_twilio(account_sid: str, auth_token: str, phone_number: str = "", phone_sid: str = "") -> dict[str, Any]:
+    updates = {
+        "TWILIO_ACCOUNT_SID": account_sid.strip(),
+        "TWILIO_AUTH_TOKEN": auth_token.strip(),
+    }
+    if phone_number:
+        updates["TWILIO_PHONE_NUMBER"] = _normalize_phone(phone_number)
+    if phone_sid:
+        updates["TWILIO_PHONE_NUMBER_SID"] = phone_sid.strip()
+    env_file = _upsert_env_file(updates)
+    result = {
+        "success": True,
+        "provider": "twilio",
+        "saved_env_keys": sorted(updates),
+        "env_path": str(env_file),
+        "message": "Twilio credentials saved to ~/.hermes/.env.",
+    }
+    if phone_number:
+        result.update(_remember_twilio_number(phone_number=updates["TWILIO_PHONE_NUMBER"], phone_sid=phone_sid.strip(), save_env=False))
+    return result
+
+
+def save_bland(api_key: str, voice: str = BLAND_DEFAULT_VOICE) -> dict[str, Any]:
+    env_file = _upsert_env_file(
+        {
+            "BLAND_API_KEY": api_key.strip(),
+            "BLAND_DEFAULT_VOICE": voice.strip() or BLAND_DEFAULT_VOICE,
+            "PHONE_PROVIDER": "bland",
+        }
+    )
+    return {
+        "success": True,
+        "provider": "bland",
+        "saved_env_keys": ["BLAND_API_KEY", "BLAND_DEFAULT_VOICE", "PHONE_PROVIDER"],
+        "env_path": str(env_file),
+        "message": "Bland.ai configuration saved to ~/.hermes/.env.",
+    }
+
+
+def save_vapi(
+    api_key: str,
+    *,
+    phone_number_id: str = "",
+    voice_provider: str = VAPI_DEFAULT_VOICE_PROVIDER,
+    voice_id: str = VAPI_DEFAULT_VOICE_ID,
+    model: str = VAPI_DEFAULT_MODEL,
+) -> dict[str, Any]:
+    updates = {
+        "VAPI_API_KEY": api_key.strip(),
+        "VAPI_VOICE_PROVIDER": voice_provider.strip() or VAPI_DEFAULT_VOICE_PROVIDER,
+        "VAPI_VOICE_ID": voice_id.strip() or VAPI_DEFAULT_VOICE_ID,
+        "VAPI_MODEL": model.strip() or VAPI_DEFAULT_MODEL,
+        "PHONE_PROVIDER": "vapi",
+    }
+    if phone_number_id:
+        updates["VAPI_PHONE_NUMBER_ID"] = phone_number_id.strip()
+    env_file = _upsert_env_file(updates)
+    result = {
+        "success": True,
+        "provider": "vapi",
+        "saved_env_keys": sorted(updates),
+        "env_path": str(env_file),
+        "message": "Vapi configuration saved to ~/.hermes/.env.",
+    }
+    if phone_number_id:
+        result.update(_remember_vapi_number(phone_number_id=phone_number_id.strip(), save_env=False))
+    return result
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Hermes telephony helper")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("diagnose", help="Show saved telephony state and provider readiness")
+
+    p = sub.add_parser("save-twilio", help="Save Twilio credentials to ~/.hermes/.env")
+    p.add_argument("account_sid")
+    p.add_argument("auth_token")
+    p.add_argument("--phone-number", default="")
+    p.add_argument("--phone-sid", default="")
+
+    p = sub.add_parser("save-bland", help="Save Bland.ai settings to ~/.hermes/.env")
+    p.add_argument("api_key")
+    p.add_argument("--voice", default=BLAND_DEFAULT_VOICE)
+
+    p = sub.add_parser("save-vapi", help="Save Vapi settings to ~/.hermes/.env")
+    p.add_argument("api_key")
+    p.add_argument("--phone-number-id", default="")
+    p.add_argument("--voice-provider", default=VAPI_DEFAULT_VOICE_PROVIDER)
+    p.add_argument("--voice-id", default=VAPI_DEFAULT_VOICE_ID)
+    p.add_argument("--model", default=VAPI_DEFAULT_MODEL)
+
+    p = sub.add_parser("twilio-search", help="Search Twilio numbers available for purchase")
+    p.add_argument("--country", default="US")
+    p.add_argument("--area-code", default="")
+    p.add_argument("--contains", default="")
+    p.add_argument("--limit", type=int, default=10)
+    p.add_argument("--sms-enabled", action=argparse.BooleanOptionalAction, default=True)
+    p.add_argument("--voice-enabled", action=argparse.BooleanOptionalAction, default=True)
+
+    p = sub.add_parser("twilio-buy", help="Buy a Twilio phone number")
+    p.add_argument("phone_number")
+    p.add_argument("--save-env", action="store_true")
+
+    sub.add_parser("twilio-owned", help="List Twilio numbers already owned by the account")
+
+    p = sub.add_parser("twilio-set-default", help="Remember one owned Twilio number as the default")
+    p.add_argument("identifier", help="Owned phone number in E.164 or Twilio phone SID")
+    p.add_argument("--save-env", action="store_true")
+
+    p = sub.add_parser("twilio-call", help="Place a direct Twilio call")
+    p.add_argument("to_number")
+    p.add_argument("--message", default="")
+    p.add_argument("--audio-url", default="")
+    p.add_argument("--voice", default=TWILIO_DEFAULT_TTS_VOICE)
+    p.add_argument("--send-digits", default="")
+    p.add_argument("--from-number", default="")
+    p.add_argument("--record", action="store_true")
+
+    p = sub.add_parser("twilio-call-status", help="Check a Twilio call status")
+    p.add_argument("call_sid")
+
+    p = sub.add_parser("twilio-send-sms", help="Send SMS or MMS via Twilio")
+    p.add_argument("to_number")
+    p.add_argument("body")
+    p.add_argument("--media-url", action="append", default=[])
+    p.add_argument("--from-number", default="")
+
+    p = sub.add_parser("twilio-inbox", help="Poll inbound SMS for the default or specified Twilio number")
+    p.add_argument("--limit", type=int, default=20)
+    p.add_argument("--since-last", action="store_true")
+    p.add_argument("--mark-seen", action="store_true")
+    p.add_argument("--phone-number", default="")
+
+    p = sub.add_parser("vapi-import-twilio", help="Import an owned Twilio number into Vapi")
+    p.add_argument("--phone-number", default="")
+    p.add_argument("--save-env", action="store_true")
+
+    p = sub.add_parser("ai-call", help="Place an outbound AI voice call via Bland.ai or Vapi")
+    p.add_argument("to_number")
+    p.add_argument("task")
+    p.add_argument("--provider", choices=["bland", "vapi"], default="")
+    p.add_argument("--voice", default="")
+    p.add_argument("--first-sentence", default="")
+    p.add_argument("--max-duration", type=int, default=3)
+
+    p = sub.add_parser("ai-status", help="Check an AI call status via Bland.ai or Vapi")
+    p.add_argument("call_id")
+    p.add_argument("--provider", choices=["bland", "vapi"], default="")
+    p.add_argument("--analyze", default="")
+
+    return parser
+
+
+def _dispatch(args: argparse.Namespace) -> dict[str, Any]:
+    cmd = args.command
+    if cmd == "diagnose":
+        return diagnose()
+    if cmd == "save-twilio":
+        return save_twilio(args.account_sid, args.auth_token, phone_number=args.phone_number, phone_sid=args.phone_sid)
+    if cmd == "save-bland":
+        return save_bland(args.api_key, voice=args.voice)
+    if cmd == "save-vapi":
+        return save_vapi(
+            args.api_key,
+            phone_number_id=args.phone_number_id,
+            voice_provider=args.voice_provider,
+            voice_id=args.voice_id,
+            model=args.model,
+        )
+    if cmd == "twilio-search":
+        return _twilio_search_numbers(
+            country=args.country,
+            area_code=args.area_code or None,
+            contains=args.contains or None,
+            limit=args.limit,
+            sms_enabled=args.sms_enabled,
+            voice_enabled=args.voice_enabled,
+        )
+    if cmd == "twilio-buy":
+        return _twilio_buy_number(args.phone_number, save_env=args.save_env)
+    if cmd == "twilio-owned":
+        return _twilio_list_owned()
+    if cmd == "twilio-set-default":
+        return _twilio_set_default(args.identifier, save_env=args.save_env)
+    if cmd == "twilio-call":
+        return _twilio_call(
+            args.to_number,
+            message=args.message or None,
+            audio_url=args.audio_url or None,
+            voice=args.voice,
+            send_digits=args.send_digits or None,
+            from_identifier=args.from_number or None,
+            record=args.record,
+        )
+    if cmd == "twilio-call-status":
+        return _twilio_call_status(args.call_sid)
+    if cmd == "twilio-send-sms":
+        return _twilio_send_sms(
+            args.to_number,
+            args.body,
+            media_urls=args.media_url or None,
+            from_identifier=args.from_number or None,
+        )
+    if cmd == "twilio-inbox":
+        return _twilio_inbox(
+            limit=args.limit,
+            since_last=args.since_last,
+            mark_seen=args.mark_seen,
+            phone_identifier=args.phone_number or None,
+        )
+    if cmd == "vapi-import-twilio":
+        return _vapi_import_twilio_number(
+            phone_identifier=args.phone_number or None,
+            save_env=args.save_env,
+        )
+    if cmd == "ai-call":
+        provider = (args.provider or _ai_provider()).lower().strip()
+        if provider == "vapi":
+            return _vapi_call(
+                args.to_number,
+                args.task,
+                voice_id=args.voice or None,
+                first_sentence=args.first_sentence or None,
+                max_duration=args.max_duration,
+            )
+        if provider == "bland":
+            return _bland_call(
+                args.to_number,
+                args.task,
+                voice=args.voice or None,
+                first_sentence=args.first_sentence or None,
+                max_duration=args.max_duration,
+            )
+        raise TelephonyError(
+            f"Unsupported AI call provider '{provider}'. Use --provider bland or --provider vapi, "
+            "or set PHONE_PROVIDER in ~/.hermes/.env."
+        )
+    if cmd == "ai-status":
+        provider = (args.provider or _ai_provider()).lower().strip()
+        if provider == "vapi":
+            return _vapi_status(args.call_id)
+        if provider == "bland":
+            return _bland_status(args.call_id, analyze=args.analyze or None)
+        raise TelephonyError(
+            f"Unsupported AI call provider '{provider}'. Use --provider bland or --provider vapi, "
+            "or set PHONE_PROVIDER in ~/.hermes/.env."
+        )
+    raise TelephonyError(f"Unknown command: {cmd}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    try:
+        result = _dispatch(args)
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+        return 0
+    except TelephonyError as exc:
+        print(json.dumps({"success": False, "error": str(exc)}, indent=2, ensure_ascii=False), file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())