feat: restore voice-call plugin parity

docs/plugins/voice-call.md

@@ -1,5 +1,5 @@
 ---
-summary: "Voice Call plugin: Twilio-backed outbound calls (plugin install + config + CLI)"
+summary: "Voice Call plugin: outbound + inbound calls via Twilio/Telnyx (plugin install + config + CLI)"
 read_when:
   - You want to place an outbound voice call from Clawdbot
   - You are configuring or developing the voice-call plugin
@@ -7,20 +7,19 @@ read_when:
 
 # Voice Call (plugin)
 
-Outbound voice calls for Clawdbot via a plugin.
-
-If you’re new to plugins, start with [Plugins](/plugin): what they are, where
-they live on disk, and how install/config works.
+Voice calls for Clawdbot via a plugin. Supports outbound notifications and
+multi-turn conversations with inbound policies.
 
 Current providers:
-- `twilio` (real calls)
-- `log` (dev fallback; no network)
+- `twilio` (Programmable Voice + Media Streams)
+- `telnyx` (Call Control v2)
+- `mock` (dev/no network)
 
 Quick mental model:
 - Install plugin
 - Restart Gateway
 - Configure under `plugins.entries.voice-call.config`
-- Use `clawdbot voicecall …` or the `voice_call` tool
+- Use `clawdbot voicecall ...` or the `voice_call` tool
 
 ## Where it runs (local vs remote)
 
@@ -28,23 +27,6 @@ The Voice Call plugin runs **inside the Gateway process**.
 
 If you use a remote Gateway, install/configure the plugin on the **machine running the Gateway**, then restart the Gateway to load it.
 
-## Twilio setup (getting the credentials)
-
-You’ll need:
-- **Account SID** (`AC...`)
-- **Auth Token** (treat like a password)
-- A Twilio **Voice-capable phone number** to use as `from` (E.164, like `+15551234567`)
-
-Steps:
-1) Create/sign in to Twilio: `https://www.twilio.com/`
-2) Open the Twilio Console: `https://console.twilio.com/`
-3) Find your **Account SID** + **Auth Token** (typically on the Console dashboard / Account settings).
-4) Buy (or select) a Twilio phone number with **Voice** capability:
-   - Console → Phone Numbers → Manage → Buy a number
-5) (Trial accounts) You may need to verify the destination `to` numbers before Twilio allows outbound calling.
-
-Tip: keep `twilio.authToken` out of git; store it in `~/.clawdbot/clawdbot.json` or your Control UI config, not in repo files.
-
 ## Install
 
 ### Option A: install from npm (recommended)
@@ -53,38 +35,17 @@ Tip: keep `twilio.authToken` out of git; store it in `~/.clawdbot/clawdbot.json`
 clawdbot plugins install @clawdbot/voice-call
 ```
 
-This downloads the package, extracts it into `~/.clawdbot/extensions/`, and enables it in `clawdbot.json`.
-
 Restart the Gateway afterwards.
 
 ### Option B: install from a local folder (dev, no copying)
 
-This keeps the plugin in-place (great for iterating locally) and adds the folder
-to `plugins.load.paths`.
-
 ```bash
 clawdbot plugins install /absolute/path/to/voice-call
-```
-
-If your plugin has dependencies, install them in that folder (so it has a
-`node_modules`):
-
-```bash
 cd /absolute/path/to/voice-call && pnpm install
 ```
 
 Restart the Gateway afterwards.
 
-### Option C: copy into the global extensions folder (dev)
-
-```bash
-mkdir -p ~/.clawdbot/extensions
-cp -R extensions/voice-call ~/.clawdbot/extensions/voice-call
-cd ~/.clawdbot/extensions/voice-call && pnpm install
-```
-
-Restart the Gateway afterwards.
-
 ## Config
 
 Set config under `plugins.entries.voice-call.config`:
@@ -96,13 +57,33 @@ Set config under `plugins.entries.voice-call.config`:
       "voice-call": {
         enabled: true,
         config: {
-          provider: "twilio",
+          provider: "twilio", // or "telnyx" | "mock"
+          fromNumber: "+15550001234",
+          toNumber: "+15550005678",
+
           twilio: {
             accountSid: "ACxxxxxxxx",
-            authToken: "…",
-            from: "+15551234567",
-            statusCallbackUrl: "https://example.com/twilio-status", // optional
-            twimlUrl: "https://example.com/twiml" // optional
+            authToken: "..."
+          },
+
+          // Webhook server
+          serve: {
+            port: 3334,
+            path: "/voice/webhook"
+          },
+
+          // Public exposure (pick one)
+          // publicUrl: "https://example.ngrok.app/voice/webhook",
+          // tunnel: { provider: "ngrok" },
+          // tailscale: { mode: "funnel", path: "/voice/webhook" }
+
+          outbound: {
+            defaultMode: "notify" // notify | conversation
+          },
+
+          streaming: {
+            enabled: true,
+            streamPath: "/voice/stream"
           }
         }
       }
@@ -111,34 +92,57 @@ Set config under `plugins.entries.voice-call.config`:
 }
 ```
 
-Dev fallback:
+Notes:
+- Twilio/Telnyx require a **publicly reachable** webhook URL.
+- `mock` is a local dev provider (no network calls).
+- `skipSignatureVerification` is for local testing only.
+
+## Inbound calls
+
+Inbound policy defaults to `disabled`. To enable inbound calls, set:
 
 ```json5
-{ provider: "log" }
+{
+  inboundPolicy: "allowlist",
+  allowFrom: ["+15550001234"],
+  inboundGreeting: "Hello! How can I help?"
+}
 ```
 
-Notes:
-- `twilio.authToken` is treated as sensitive in the Control UI schema hints.
+Auto-responses use the agent system. Tune with:
+- `responseModel`
+- `responseSystemPrompt`
+- `responseTimeoutMs`
 
 ## CLI
 
 ```bash
-clawdbot voicecall start --to "+15555550123" --message "Hello from Clawdbot"
-clawdbot voicecall status --sid CAxxxxxxxx
+clawdbot voicecall call --to "+15555550123" --message "Hello from Clawdbot"
+clawdbot voicecall continue --call-id <id> --message "Any questions?"
+clawdbot voicecall speak --call-id <id> --message "One moment"
+clawdbot voicecall end --call-id <id>
+clawdbot voicecall status --call-id <id>
+clawdbot voicecall tail
+clawdbot voicecall expose --mode funnel
 ```
 
 ## Agent tool
 
 Tool name: `voice_call`
 
-- `mode`: `"call" | "status"` (default: `call`)
-- `to`: required for `call`
-- `sid`: required for `status`
-- `message`: optional
+Actions:
+- `initiate_call` (message, to?, mode?)
+- `continue_call` (callId, message)
+- `speak_to_user` (callId, message)
+- `end_call` (callId)
+- `get_status` (callId)
 
 This repo ships a matching skill doc at `skills/voice-call/SKILL.md`.
 
 ## Gateway RPC
 
-- `voicecall.start` (`to`, optional `message`)
-- `voicecall.status` (`sid`)
+- `voicecall.initiate` (`to?`, `message`, `mode?`)
+- `voicecall.continue` (`callId`, `message`)
+- `voicecall.speak` (`callId`, `message`)
+- `voicecall.end` (`callId`)
+- `voicecall.status` (`callId`)