@clawvoice/voice-assistant 1.0.0

package/.env.example

@@ -0,0 +1,125 @@
+# ClawVoice - Environment Variables
+# Copy this file to .env and fill in your values.
+# Only configure the providers you plan to use.
+
+# ============================================================
+# TELEPHONY PROVIDER
+# Primary: Twilio (default, widely supported)
+# Alternative: Telnyx (lower cost option)
+# ============================================================
+
+# Which telephony provider to use: "twilio" or "telnyx"
+CLAWVOICE_TELEPHONY_PROVIDER="twilio"
+
+# --- Twilio (default) ---
+TWILIO_ACCOUNT_SID=""
+TWILIO_AUTH_TOKEN=""
+TWILIO_PHONE_NUMBER=""
+
+# --- Telnyx (alternative) ---
+TELNYX_API_KEY=""
+TELNYX_CONNECTION_ID=""
+TELNYX_PHONE_NUMBER=""
+
+# Telnyx webhook signing public key (Ed25519, for verifying inbound webhooks)
+TELNYX_WEBHOOK_SECRET=""
+
+# ============================================================
+# VOICE PROVIDER
+# Option A: Deepgram Voice Agent (single WebSocket, lower latency)
+# Option B: ElevenLabs Conversational AI (premium voices)
+# ============================================================
+
+# Which voice provider to use: "deepgram-agent" or "elevenlabs-conversational"
+CLAWVOICE_VOICE_PROVIDER="deepgram-agent"
+
+# --- Deepgram (required for Option A) ---
+DEEPGRAM_API_KEY=""
+
+# Default Deepgram voice (aura-asteria-en, aura-luna-en, aura-orion-en, aura-arcas-en)
+CLAWVOICE_DEEPGRAM_VOICE="aura-asteria-en"
+
+# --- ElevenLabs (optional, for premium TTS via Deepgram or Option B) ---
+ELEVENLABS_API_KEY=""
+
+# ElevenLabs Agent ID (for Option B: EL Conversational AI)
+ELEVENLABS_AGENT_ID=""
+
+# ElevenLabs voice ID (for Option A: EL TTS via Deepgram)
+ELEVENLABS_VOICE_ID=""
+
+# ============================================================
+# AGENT BEHAVIOR
+# ============================================================
+
+# System prompt for the voice agent (instructions, persona, role)
+CLAWVOICE_VOICE_SYSTEM_PROMPT=""
+
+# Enable inbound call answering (true/false)
+CLAWVOICE_INBOUND_ENABLED="true"
+
+# Enable disclosure statement at call start (true/false)
+CLAWVOICE_DISCLOSURE_ENABLED="true"
+
+# Custom disclosure statement
+CLAWVOICE_DISCLOSURE_STATEMENT="Hello, this call is from an AI assistant calling on behalf of a user."
+
+# ============================================================
+# POST-CALL ANALYSIS
+# ============================================================
+
+# OpenAI API key (optional, for dedicated post-call analysis)
+# If not set, uses OpenClaw's default model provider
+OPENAI_API_KEY=""
+
+# Analysis model (default: gpt-4o-mini for cost efficiency)
+CLAWVOICE_ANALYSIS_MODEL="gpt-4o-mini"
+
+# ============================================================
+# VOICE MEMORY
+# ============================================================
+
+# Can the voice agent read main MEMORY.md? ("read" or "none")
+CLAWVOICE_MAIN_MEMORY_ACCESS="read"
+
+# Auto-extract memories from call transcripts? (true/false)
+CLAWVOICE_AUTO_EXTRACT_MEMORIES="true"
+
+# ============================================================
+# SECURITY
+# ============================================================
+
+# Restrict voice agent tool access (recommended: true)
+CLAWVOICE_RESTRICT_TOOLS="true"
+
+# Denied tools for voice sessions (comma-separated)
+# Default: exec,browser,web_fetch,gateway,cron,sessions_spawn
+CLAWVOICE_DENIED_TOOLS="exec,browser,web_fetch,gateway,cron,sessions_spawn"
+
+# ============================================================
+# CALL BEHAVIOR
+# ============================================================
+
+# Maximum daily outbound calls (0 = unlimited)
+CLAWVOICE_DAILY_CALL_LIMIT="50"
+
+# Enable answering machine detection for outbound calls (true/false)
+CLAWVOICE_AMD_ENABLED="true"
+
+# Maximum call duration in seconds (default: 1800 = 30 minutes)
+CLAWVOICE_MAX_CALL_DURATION="1800"
+
+# Enable call recording (true/false)
+CLAWVOICE_RECORD_CALLS="false"
+
+# Webhook URL for call events (optional, for external integrations)
+CLAWVOICE_WEBHOOK_URL=""
+
+# ============================================================
+# NOTIFICATIONS (optional)
+# ============================================================
+
+# Send post-call notifications to these channels (true/false)
+CLAWVOICE_NOTIFY_TELEGRAM="false"
+CLAWVOICE_NOTIFY_DISCORD="false"
+CLAWVOICE_NOTIFY_SLACK="false"

package/CHANGELOG.md

@@ -0,0 +1,112 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Non-blocking config diagnostics warnings at plugin init — missing credentials and misconfigured settings are now surfaced immediately via `api.log.warn()` rather than failing silently at first call time.
+- Runtime credential failure tests for both Twilio and Telnyx call-start path.
+
+### Fixed
+- OpenClaw guide manifest example now uses the correct stable plugin id (`voice-assistant`) and correct default provider (`twilio`).
+
+---
+
+## [1.0.1] - 2026-03-16
+
+### Added
+- `package.json` now includes `openclaw.extensions` field required by the OpenClaw plugin installer.
+- Named `activate` and `register` exports in plugin entry point for OpenClaw loader compatibility.
+
+### Changed
+- Plugin manifest `id` changed from `clawvoice/voice-assistant` to `voice-assistant` (shorter stable form used by OpenClaw runtime).
+- Init-time config validation no longer hard-fails on missing provider credentials — the plugin can be installed and enabled before credentials are configured.
+- Config schema `required` list cleared so OpenClaw's plugin host does not block enable when credentials are absent.
+- Private ignore rules (internal tooling paths) moved from tracked `.gitignore` to local-only `.git/info/exclude`.
+
+### Fixed
+- History scrubbed to remove all internal development artifacts (BMAD planning files, reference code, `.beads` state, `.claude` commands) from all historical commits and tags.
+
+---
+
+## [1.0.0] - 2026-03-14
+
+Initial production release. Implements all five epics and 17 user stories from the PRD.
+
+### Added
+
+**Core Plugin (Epic 1)**
+- OpenClaw plugin scaffold with manifest, TypeScript build, and SDK integration.
+- Three-tier config resolution (env → plugin config → defaults) with contextual validation.
+- Interactive setup wizard (`clawvoice setup`) for provider credentials and preferences.
+- Configurable disclosure statement spoken at call start (`disclosureEnabled`, `disclosureStatement`).
+- Configurable max call duration with automatic termination (`maxCallDuration`).
+- Enable/disable inbound call answering (`inboundEnabled`).
+- Custom voice system prompt for agent persona and task framing (`voiceSystemPrompt`).
+
+**Voice Bridge (Epic 2)**
+- Audio codec negotiation with actionable diagnostics (μ-law 8 kHz, bidirectional).
+- Deepgram Voice Agent settings builder with configurable TTS voice and system prompt composition.
+- Real-time 160 → 3200-byte audio buffering for Twilio media stream compatibility.
+- 5-second keepalive heartbeat over active voice WebSocket.
+- Greeting grace period preventing false barge-in on agent greeting.
+- Barge-in via Twilio `clear` command when `UserStartedSpeaking` event fires outside grace period.
+- Function call dispatch for `end_call` and custom agent-invoked tools.
+- Per-call transcript tracking (user and agent turns with timestamps).
+- Heartbeat-based disconnection detection with 2-second timeout (NFR10).
+- `DisconnectionRecord` with reason, detail, duration, and transcript length.
+- Call summaries with `CallOutcome` (completed / partial / failed), failure list, and `RetryContext`.
+
+**Safety and Isolation (Epic 3)**
+- Voice-memory write isolation: all writes during a voice session are redirected to `voice-memory/` namespace.
+- Configurable main-memory read access (`mainMemoryAccess`: `read` or `none`).
+- Built-in always-denied tools for voice sessions (`exec`, `browser`, `web_fetch`).
+- User-configurable additional denied tools list (`restrictTools`, `deniedTools`).
+- Prompt injection detection with 8 pattern guards applied before response generation.
+- Telnyx webhook signature verification using Ed25519 public-key cryptography.
+- Twilio webhook signature verification using HMAC-SHA1.
+- Post-call transcript and call record persistence to `voice-memory/calls/{callId}`.
+- Configurable post-call notifications to Telegram, Discord, or Slack channels (`notifyTelegram`, `notifyDiscord`, `notifySlack`).
+
+**CLI (Epic 4)**
+- `clawvoice call <number>` — initiate outbound call with optional `--greeting` and `--purpose` flags.
+- `clawvoice history` — list recent calls with outcome, duration, and status.
+- `clawvoice history <callId>` — full call detail with transcript summary and retry context.
+- `clawvoice status` — run health diagnostics with ✓/⚠/✗ per check and remediation guidance.
+- `clawvoice test` — connectivity test showing pass/fail with remediation, secrets never exposed.
+- `clawvoice promote` — list pending memory candidates and promote approved entries to main memory.
+
+**Advanced Features (Epic 5)**
+- Inbound call handling with AMD (Answering Machine Detection) classification.
+- Per-decision routing: human → bridge, machine → voicemail, fax → reject.
+- Telnyx and Twilio AMD callback routes.
+- Pattern-based memory extraction from call transcripts (health, schedule, preference, relationship, interest categories).
+- Pending/approved/rejected/promoted memory candidate workflow with `MemoryExtractionService`.
+- Health diagnostics covering 8 checks: telephony credentials, voice credentials, webhook URL, disclosure, call duration, inbound status, mode, provider.
+
+**Real telephony integration**
+- Twilio adapter makes real calls via REST API (`https://api.twilio.com/2010-04-01/Accounts/{sid}/Calls.json`).
+- Telnyx adapter makes real calls via REST API (`https://api.telnyx.com/v2/calls`).
+- Both adapters throw immediately if credentials are missing (no silent simulation).
+- Daily outbound call rate limit with per-day counter and reset (`dailyCallLimit`, default 50).
+
+### Security
+- Real cryptographic webhook verification (no stub validation).
+- Built-in prompt injection guards in all voice sessions.
+- Memory namespace isolation prevents voice session data from polluting main agent memory.
+- Credentials never logged or exposed in diagnostic output.
+
+---
+
+## [0.1.0] - 2026-03-13
+
+- Initial repository structure, documentation, and feature overview.
+
+[Unreleased]: https://github.com/ClawVoice/clawvoice/compare/v1.0.0...HEAD
+[1.0.1]: https://github.com/ClawVoice/clawvoice/compare/v1.0.0...02536b5
+[1.0.0]: https://github.com/ClawVoice/clawvoice/compare/a6c9ceb...d58a040
+[0.1.0]: https://github.com/ClawVoice/clawvoice/releases/tag/a6c9ceb

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClawVoice
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,215 @@
+# ClawVoice
+
+Voice calling plugin for OpenClaw. Give your AI agent a phone number.
+
+## What It Does
+
+ClawVoice connects your OpenClaw agent to the phone network. Your agent can receive and make phone calls, with real-time voice conversation powered by Deepgram Voice Agent or ElevenLabs Conversational AI.
+
+**Key features:**
+- **Two voice pipelines**: Deepgram Voice Agent (single WebSocket, lowest latency) or ElevenLabs Conversational AI (premium voice quality)
+- **Voice memory isolation**: Phone calls write to a sandboxed `voice-memory/` namespace. Voice callers cannot corrupt your agent's main memory. Memory promotion to `MEMORY.md` requires explicit review.
+- **Post-call analysis**: After every call, get a transcript, call summary with outcome/failures/retry context, and action items written to voice memory.
+- **Inbound + outbound**: Your agent can take calls and initiate them.
+
+## Quick Start
+
+### 1. Install
+
+Bring your own API keys. You control everything.
+<br>
+
+Configure your providers in `.env` or via `openclaw config set`:
+- **Telephony**: Telnyx (recommended) or Twilio
+- **Voice**: Deepgram Voice Agent or ElevenLabs Conversational AI
+- **Analysis**: OpenAI (optional, falls back to OpenClaw's configured model)
+
+
+```bash
+openclaw plugins install @clawvoice/voice-assistant
+```
+
+### 2. Get API Keys
+
+**Telephony** (pick one):
+- [Telnyx](https://telnyx.com) - Create account, get API key, buy a phone number, set up a Call Control app
+- [Twilio](https://twilio.com) - Create account, get SID + auth token, buy a phone number
+
+**Voice** (pick one):
+- [Deepgram](https://deepgram.com) - Create account, get API key (needed for both voice provider options)
+- [ElevenLabs](https://elevenlabs.io) - Create account, get API key, create a Conversational AI agent (for Option B only)
+
+### 3. Configure
+
+```bash
+# Telephony
+openclaw config set clawvoice.telephonyProvider telnyx
+openclaw config set clawvoice.telnyxApiKey YOUR_KEY
+openclaw config set clawvoice.telnyxConnectionId YOUR_CONNECTION_ID
+openclaw config set clawvoice.telnyxPhoneNumber +15551234567
+
+# Voice (Deepgram Voice Agent)
+openclaw config set clawvoice.voiceProvider deepgram-agent
+openclaw config set clawvoice.deepgramApiKey YOUR_KEY
+
+# Or set via .env file — see .env.example
+```
+
+### 4. Start
+
+```bash
+openclaw start
+```
+
+Your agent now answers calls to the configured phone number.
+
+### 5. Make a test call
+
+```bash
+openclaw clawvoice call +15559876543
+```
+
+Or ask your agent: *"Call +15559876543"*
+
+## Voice Providers
+
+### Deepgram Voice Agent (Recommended)
+
+Single WebSocket handles STT + LLM + TTS. Lowest latency (~200ms round-trip).
+
+- Uses Deepgram's Agent API
+- TTS: Deepgram Aura voices (included) or ElevenLabs (BYOK, routed through Deepgram)
+- Barge-in support (caller can interrupt)
+- LLM routing happens inside Deepgram's infrastructure
+
+### ElevenLabs Conversational AI
+
+ElevenLabs handles the entire voice pipeline. Premium voice quality.
+
+- Create an ElevenLabs Conversational AI agent in their dashboard
+- Point it at your OpenClaw gateway's `/v1/chat/completions` endpoint
+- ElevenLabs handles STT, turn-taking, and TTS
+- OpenClaw provides the brain (tools, memory, personality)
+
+## Voice Memory Isolation
+
+Phone calls are inherently riskier than text — callers can attempt social engineering or prompt injection via voice. ClawVoice sandboxes all voice interactions:
+
+```
+~/.openclaw/workspace/
+  MEMORY.md              # Main memory (text channels)
+  memory/                # Main daily logs
+  voice-memory/          # Voice-only sandbox
+    VOICE-MEMORY.md      # Curated voice long-term memory
+    2026-03-11.md        # Voice daily log
+```
+
+**Access rules:**
+- Voice agent can READ main `MEMORY.md` (configurable)
+- Voice agent can ONLY WRITE to `voice-memory/`
+- Text channels don't see `voice-memory/` by default
+- Memory promotion requires explicit review
+
+### Promote voice memories
+
+```bash
+openclaw clawvoice promote
+```
+
+Reviews pending voice memories and lets you approve/reject promotion to main `MEMORY.md`.
+
+## CLI Commands
+
+```bash
+openclaw clawvoice setup                   # Interactive setup wizard
+openclaw clawvoice call <number>           # Initiate outbound call
+openclaw clawvoice status                  # Show active calls and config
+openclaw clawvoice promote                 # Review and promote voice memories
+openclaw clawvoice history                 # Show recent call history
+openclaw clawvoice test                    # Test voice pipeline connectivity
+```
+
+## Agent Tools
+
+The plugin registers these tools for your OpenClaw agent:
+
+| Tool | Description |
+|------|-------------|
+| `voice_assistant.call` | Initiate an outbound phone call |
+| `voice_assistant.hangup` | End an active call |
+| `voice_assistant.status` | Get status of active/recent calls |
+| `voice_assistant.promote_memory` | Promote a voice memory to main memory |
+
+## Architecture
+
+```
+Phone ──PSTN──> Telnyx ──WebSocket──> ClawVoice Plugin ──> OpenClaw Agent
+                                           │
+                                    ┌──────┴──────┐
+                              Deepgram        ElevenLabs
+                            Voice Agent      Conversational AI
+                           (STT+LLM+TTS)    (STT+TTS, OpenClaw=LLM)
+                                           │
+                                    voice-memory/
+                                   (sandboxed writes)
+```
+
+## Configuration Reference
+
+See [`.env.example`](.env.example) for all environment variables.
+
+Key settings in `openclaw.plugin.json` `configSchema`:
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `telephonyProvider` | `"telnyx" \| "twilio"` | `"telnyx"` | PSTN provider |
+| `voiceProvider` | `"deepgram-agent" \| "elevenlabs-conversational"` | `"deepgram-agent"` | Voice pipeline |
+| `voiceSystemPrompt` | `string` | `""` | Instructions for how the agent behaves on calls |
+| `inboundEnabled` | `boolean` | `true` | Accept inbound calls (disable to only allow outbound) |
+| `mainMemoryAccess` | `"read" \| "none"` | `"read"` | Can voice agent read main MEMORY.md? |
+| `autoExtractMemories` | `boolean` | `true` | Extract memories from transcripts after calls |
+| `restrictTools` | `boolean` | `true` | Restrict tool access for voice sessions |
+| `amdEnabled` | `boolean` | `true` | Answering machine detection for outbound calls |
+| `maxCallDuration` | `number` | `1800` | Maximum call length in seconds |
+| `recordCalls` | `boolean` | `false` | Save call recordings |
+
+## Customizing the Agent's Voice Persona
+
+Set `voiceSystemPrompt` to control how your agent behaves on phone calls:
+
+```bash
+openclaw config set clawvoice.voiceSystemPrompt "You are a friendly customer support agent for Acme Corp. Be concise, helpful, and professional. Always confirm the caller's name before proceeding."
+```
+
+This prompt is injected into the voice agent's system instructions alongside OpenClaw's base personality. If left empty, the agent uses OpenClaw's default system prompt.
+
+## Documentation
+
+- [`docs/SETUP.md`](docs/SETUP.md) - Full setup guide with step-by-step instructions and configuration reference
+- [`docs/FEATURES.md`](docs/FEATURES.md) - Complete feature list
+
+- [`docs/OPENCLAW_PLUGIN_GUIDE.md`](docs/OPENCLAW_PLUGIN_GUIDE.md) - Technical guide for building the OpenClaw plugin
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run tests
+npm test
+
+# Development mode (watch + rebuild)
+npm run dev
+
+# Link for local OpenClaw testing
+npm link
+openclaw plugins install --link @clawvoice/voice-assistant
+```
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+import { PluginAPI } from "@openclaw/plugin-sdk";
+import { ClawVoiceConfig } from "./config";
+import { MemoryExtractionService } from "./services/memory-extraction";
+import { VoiceCallService } from "./services/voice-call";
+export interface SetupPrompter {
+    ask(question: string): Promise<string>;
+    close(): void;
+}
+export declare function runSetupWizard(api: PluginAPI, args: string[], prompter?: SetupPrompter): Promise<void>;
+export declare function registerCLI(api: PluginAPI, config: ClawVoiceConfig, callService: VoiceCallService, memoryService?: MemoryExtractionService): void;