voicemode-channel 0.0.1 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Bailey
+
+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

@@ -1,6 +1,160 @@
-# voicemode-channel
+# VoiceMode Channel
 
-VoiceMode Channel - inbound voice calls to Claude Code via VoiceMode Connect.
+A Claude Code plugin that enables inbound voice calls via [VoiceMode Connect](https://voicemode.dev).
 
-This is a placeholder package to reserve the name. See the full project at:
-https://github.com/mbailey/voicemode-channel
+Users speak on their phone or web app, and their messages arrive in your Claude Code session as channel events. Claude responds using the reply tool, and the response is spoken aloud on the caller's device.
+
+![VoiceMode Connect web app showing a voice conversation with Claude Code](assets/screenshot.png)
+
+```
+User speaks on phone/web -> VoiceMode gateway -> Channel plugin -> Claude Code
+                                                                       |
+User hears TTS response  <- Channel reply tool <----------------------+
+```
+
+## Install
+
+### Claude Code plugin
+
+```bash
+claude plugin marketplace add mbailey/claude-plugins
+claude plugin install voicemode-channel@mbailey
+```
+
+### Standalone (any MCP host)
+
+```bash
+npx voicemode-channel
+```
+
+## Prerequisites
+
+- Node.js 20+
+- VoiceMode Connect credentials (`~/.voicemode/credentials`)
+  - Run `voicemode-channel auth login` to authenticate
+
+## Auth
+
+Manage your VoiceMode Connect credentials:
+
+```bash
+voicemode-channel auth login    # Authenticate via browser (PKCE flow)
+voicemode-channel auth logout   # Remove stored credentials
+voicemode-channel auth status   # Show current auth state
+```
+
+Or via npx:
+
+```bash
+npx voicemode-channel auth login
+```
+
+## Usage
+
+### Enable the channel
+
+```bash
+# During research preview, use the development flag
+VOICEMODE_CHANNEL_ENABLED=true claude --dangerously-load-development-channels plugin:voicemode-channel@mbailey
+```
+
+### Make a call
+
+Open **[app.voicemode.dev](https://app.voicemode.dev)** on your phone or browser. Sign in with the same account, tap the call button, and speak. Claude will respond and you'll hear TTS audio playback.
+
+## Configuration
+
+| Environment Variable           | Default                  | Description                                                                 |
+| ------------------------------ | ------------------------ | --------------------------------------------------------------------------- |
+| `VOICEMODE_CHANNEL_ENABLED`    | `false`                  | **Required.** Must be `true` to enable. Server exits immediately otherwise. |
+| `VOICEMODE_CHANNEL_DEBUG`      | `false`                  | Enable debug logging                                                        |
+| `VOICEMODE_CONNECT_WS_URL`     | `wss://voicemode.dev/ws` | WebSocket gateway URL                                                       |
+| `VOICEMODE_AGENT_NAME`         | `voicemode`              | Agent identity for gateway registration                                     |
+| `VOICEMODE_AGENT_DISPLAY_NAME` | `Claude Code`            | Display name shown to callers                                               |
+
+## How it works
+
+This plugin provides an MCP server that declares the experimental `claude/channel` capability. It:
+
+1. Connects to the VoiceMode Connect WebSocket gateway (authenticated via Auth0)
+2. Registers as a callable agent so callers can reach it
+3. Receives voice transcripts and pushes them as channel notifications
+4. Provides a `reply` tool for Claude to send responses back
+
+Channel events appear in Claude's session as:
+
+```
+<channel source="voicemode-channel" caller="NAME">TRANSCRIPT</channel>
+```
+
+## Troubleshooting
+
+**Channel not connecting**
+
+- Ensure `VOICEMODE_CHANNEL_ENABLED=true` is set
+- Check credentials exist: `voicemode-channel auth status`
+- Re-authenticate: `voicemode-channel auth login`
+- Enable debug logging: `VOICEMODE_CHANNEL_DEBUG=true`
+
+**No audio on caller's device**
+
+- Confirm you're signed into [app.voicemode.dev](https://app.voicemode.dev) with the same account
+- Check that Claude is using the `reply` tool (not a plain text response)
+
+**Plugin not found after install**
+
+- Verify Claude Code v2.1.80+ is installed: `claude --version`
+- Reinstall: `claude plugin install voicemode-channel@mbailey`
+
+**Hook timeout on startup**
+
+- The SessionStart hook installs npm dependencies -- this may take a moment on first run
+- Subsequent starts use the cached install and are fast
+
+## Development
+
+```bash
+# Clone and test locally
+git clone https://github.com/mbailey/voicemode-channel.git
+cd voicemode-channel
+npm install
+
+# Build
+make build
+
+# Test with --plugin-dir
+VOICEMODE_CHANNEL_ENABLED=true claude --plugin-dir . --dangerously-load-development-channels server:voicemode-channel
+```
+
+### Testing with mcptools
+
+[mcptools](https://github.com/f/mcptools) provides an interactive shell for testing MCP servers (`brew install mcptools`):
+
+```bash
+make shell
+```
+
+Example session:
+
+```
+mcp > tools                              # List available tools
+mcp > status                             # Check connection state
+mcp > reply {"text":"hello from cli"}    # Send a voice reply
+mcp > profile                            # View agent profile
+mcp > profile {"voice":"af_sky"}         # Update profile fields
+mcp > /q                                 # Quit
+```
+
+The MCP Inspector web UI is also available:
+
+```bash
+make inspect
+```
+
+## Status
+
+Research preview. Requires Claude Code v2.1.80+ with channel support.
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,12 @@
+/**
+ * OAuth PKCE login flow for VoiceMode Connect.
+ *
+ * Implements Auth0 PKCE authentication using only Node built-ins:
+ * - crypto for PKCE code verifier/challenge
+ * - http for localhost callback server
+ * - child_process for opening browser
+ *
+ * Ported from voice_mode/auth.py in the Python CLI.
+ */
+import { type StoredCredentials } from './credentials.js';
+export declare function login(log: (msg: string) => void): Promise<StoredCredentials>;

package/dist/auth.js

@@ -0,0 +1,298 @@
+/**
+ * OAuth PKCE login flow for VoiceMode Connect.
+ *
+ * Implements Auth0 PKCE authentication using only Node built-ins:
+ * - crypto for PKCE code verifier/challenge
+ * - http for localhost callback server
+ * - child_process for opening browser
+ *
+ * Ported from voice_mode/auth.py in the Python CLI.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { execFile } from 'node:child_process';
+import { platform } from 'node:os';
+import { AUTH0_DOMAIN, AUTH0_CLIENT_ID, save_credentials, } from './credentials.js';
+// ---------------------------------------------------------------------------
+// Auth0 OAuth parameters (matching Python CLI)
+// ---------------------------------------------------------------------------
+const AUTH0_SCOPES = 'openid profile email offline_access';
+const AUTH0_AUDIENCE = 'https://voicemode.dev/api';
+// ---------------------------------------------------------------------------
+// Callback server configuration
+// ---------------------------------------------------------------------------
+const CALLBACK_PORT_START = 8765;
+const CALLBACK_PORT_END = 8769;
+const CALLBACK_TIMEOUT_MS = 300_000; // 5 minutes
+function generate_pkce_params() {
+    // 32 random bytes → base64url ≈ 43 characters
+    const code_verifier = randomBytes(32)
+        .toString('base64url');
+    // SHA256 hash → base64url (no padding)
+    const code_challenge = createHash('sha256')
+        .update(code_verifier, 'ascii')
+        .digest('base64url');
+    return { code_verifier, code_challenge };
+}
+// ---------------------------------------------------------------------------
+// Port selection
+// ---------------------------------------------------------------------------
+/**
+ * Try to listen on a port, resolving with the server if successful.
+ * Eliminates TOCTOU race by using listen() directly instead of checking first.
+ */
+function try_listen(server, port) {
+    return new Promise((resolve) => {
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE')
+                resolve(false);
+            else
+                resolve(false);
+        });
+        server.listen(port, '127.0.0.1', () => resolve(true));
+    });
+}
+// ---------------------------------------------------------------------------
+// Callback HTML page
+// ---------------------------------------------------------------------------
+function escape_html(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+function callback_page(success, error_message = '') {
+    const icon_bg = success ? '#3fb950' : '#f85149';
+    const icon_svg = success
+        ? '<path d="M9 16.17L4.83 12l-1.42 1.41L9 19 21 7l-1.41-1.41z" fill="#0d1117"/>'
+        : '<path d="M19 6.41L17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12z" fill="#0d1117"/>';
+    const heading = success ? 'Authentication Successful' : 'Authentication Failed';
+    const message = success
+        ? 'You can close this window and return to the terminal.'
+        : (error_message ? `Error: ${escape_html(error_message)}` : 'Something went wrong.');
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>VoiceMode - ${heading}</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+    background: #0d1117; color: #e6edf3;
+    display: flex; align-items: center; justify-content: center;
+    min-height: 100vh; padding: 24px;
+  }
+  .card {
+    background: #161b22; border: 1px solid #30363d; border-radius: 12px;
+    padding: 48px 40px; max-width: 420px; width: 100%; text-align: center;
+  }
+  .icon {
+    display: inline-flex; align-items: center; justify-content: center;
+    width: 48px; height: 48px; background: ${icon_bg}; border-radius: 50%; margin-bottom: 20px;
+  }
+  h1 { font-size: 20px; font-weight: 600; margin-bottom: 8px; color: #e6edf3; }
+  p { font-size: 14px; color: #8b949e; line-height: 1.5; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <div><div class="icon">
+      <svg width="24" height="24" viewBox="0 0 24 24">${icon_svg}</svg>
+    </div></div>
+    <h1>${heading}</h1>
+    <p>${message}</p>
+  </div>
+</body>
+</html>`;
+}
+// ---------------------------------------------------------------------------
+// Browser opening
+// ---------------------------------------------------------------------------
+function open_browser(url) {
+    const plat = platform();
+    let cmd;
+    let args;
+    if (plat === 'darwin') {
+        cmd = 'open';
+        args = [url];
+    }
+    else if (plat === 'linux') {
+        cmd = 'xdg-open';
+        args = [url];
+    }
+    else {
+        // Windows fallback (unlikely for this project)
+        cmd = 'cmd';
+        args = ['/c', 'start', '', url];
+    }
+    try {
+        execFile(cmd, args, (err) => {
+            if (err) {
+                // Browser open failed -- headless fallback already handled by caller
+            }
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Auth0 API calls
+// ---------------------------------------------------------------------------
+async function exchange_code_for_tokens(code, code_verifier, redirect_uri) {
+    const token_url = `https://${AUTH0_DOMAIN}/oauth/token`;
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: AUTH0_CLIENT_ID,
+        code,
+        code_verifier,
+        redirect_uri,
+    });
+    const response = await fetch(token_url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: body.toString(),
+    });
+    if (!response.ok) {
+        let detail = `HTTP ${response.status}`;
+        try {
+            const err = (await response.json());
+            detail = `${err.error ?? 'unknown'}: ${err.error_description ?? 'Token exchange failed'}`;
+        }
+        catch { /* use HTTP status */ }
+        throw new Error(`Token exchange failed: ${detail}`);
+    }
+    return (await response.json());
+}
+async function get_user_info(access_token) {
+    const url = `https://${AUTH0_DOMAIN}/userinfo`;
+    try {
+        const response = await fetch(url, {
+            headers: { Authorization: `Bearer ${access_token}` },
+        });
+        if (!response.ok)
+            return null;
+        return (await response.json());
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Authorization URL builder
+// ---------------------------------------------------------------------------
+function build_authorize_url(redirect_uri, pkce, state) {
+    const params = new URLSearchParams({
+        response_type: 'code',
+        client_id: AUTH0_CLIENT_ID,
+        redirect_uri,
+        scope: AUTH0_SCOPES,
+        audience: AUTH0_AUDIENCE,
+        code_challenge: pkce.code_challenge,
+        code_challenge_method: 'S256',
+        state,
+    });
+    return `https://${AUTH0_DOMAIN}/authorize?${params.toString()}`;
+}
+// ---------------------------------------------------------------------------
+// Main login flow
+// ---------------------------------------------------------------------------
+export async function login(log) {
+    // Generate PKCE parameters and state upfront (needed for the request handler)
+    const pkce = generate_pkce_params();
+    const state = randomBytes(16).toString('base64url');
+    // Create the server with request handler and find a port by trying to listen directly.
+    // The server stays bound to the port the entire time -- no TOCTOU race.
+    const result = await new Promise((resolve, reject) => {
+        let bound_port = 0;
+        const callback_server = createServer((req, res) => {
+            const url = new URL(req.url ?? '/', `http://localhost:${bound_port}`);
+            if (url.pathname !== '/callback') {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const error = url.searchParams.get('error');
+            if (error) {
+                const desc = url.searchParams.get('error_description') ?? 'Unknown error';
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(callback_page(false, desc));
+                cleanup();
+                reject(new Error(`${error}: ${desc}`));
+                return;
+            }
+            const code = url.searchParams.get('code');
+            if (!code) {
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(callback_page(false, 'Missing authorization code'));
+                cleanup();
+                reject(new Error('Missing authorization code in callback'));
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end(callback_page(true));
+            cleanup();
+            resolve({ code, state: url.searchParams.get('state'), port: bound_port });
+        });
+        const timeout_timer = setTimeout(() => {
+            cleanup();
+            resolve(null);
+        }, CALLBACK_TIMEOUT_MS);
+        function cleanup() {
+            clearTimeout(timeout_timer);
+            callback_server.close();
+        }
+        // Try ports sequentially until one binds
+        async function bind_port() {
+            for (let p = CALLBACK_PORT_START; p <= CALLBACK_PORT_END; p++) {
+                if (await try_listen(callback_server, p)) {
+                    bound_port = p;
+                    return;
+                }
+            }
+            cleanup();
+            reject(new Error(`No available ports in range ${CALLBACK_PORT_START}-${CALLBACK_PORT_END}. ` +
+                'Please close applications using these ports and try again.'));
+        }
+        bind_port().then(() => {
+            const redirect_uri = `http://localhost:${bound_port}/callback`;
+            const auth_url = build_authorize_url(redirect_uri, pkce, state);
+            log(`Callback server listening on port ${bound_port}`);
+            // Try to open browser
+            const opened = open_browser(auth_url);
+            if (!opened || !process.env.DISPLAY && !process.env.BROWSER && platform() === 'linux') {
+                // Headless fallback
+                process.stderr.write(`\nOpen this URL in your browser to log in:\n\n  ${auth_url}\n\n`);
+            }
+            else {
+                log('Opening browser for authentication...');
+            }
+            log('Waiting for authentication (up to 5 minutes)...');
+        }).catch(reject);
+    });
+    if (result === null) {
+        throw new Error('Authentication timed out. Please try again.');
+    }
+    // Verify state (CSRF protection)
+    if (result.state !== state) {
+        throw new Error('State mismatch -- possible CSRF attack. Please try again.');
+    }
+    log('Authorization code received, exchanging for tokens...');
+    // Exchange code for tokens
+    const redirect_uri = `http://localhost:${result.port}/callback`;
+    const token_response = await exchange_code_for_tokens(result.code, pkce.code_verifier, redirect_uri);
+    const expires_in = token_response.expires_in ?? 3600;
+    // Fetch user info (optional, non-fatal)
+    const user_info = await get_user_info(token_response.access_token);
+    // Build and save credentials
+    const creds = {
+        access_token: token_response.access_token,
+        refresh_token: token_response.refresh_token ?? null,
+        expires_at: Date.now() / 1000 + expires_in,
+        token_type: token_response.token_type ?? 'Bearer',
+        user_info: user_info ?? undefined,
+    };
+    save_credentials(creds);
+    log('Login successful -- credentials saved to ~/.voicemode/credentials');
+    return creds;
+}

package/dist/credentials.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared credential management for VoiceMode Connect.
+ *
+ * Auth0 constants, credential file I/O, and token refresh logic
+ * used by both the gateway client and the auth login flow.
+ */
+export declare const AUTH0_DOMAIN = "dev-2q681p5hobd1dtmm.us.auth0.com";
+export declare const AUTH0_CLIENT_ID = "1uJR1Q4HMkLkhzOXTg5JFuqBCq0FBsXK";
+export declare const CREDENTIALS_FILE: string;
+export interface StoredCredentials {
+    access_token: string;
+    refresh_token: string | null;
+    expires_at: number;
+    token_type: string;
+    user_info?: Record<string, unknown>;
+}
+export declare function load_credentials(): StoredCredentials | null;
+export declare function save_credentials(creds: StoredCredentials): void;
+export declare function is_expired(creds: StoredCredentials): boolean;
+export declare function refresh_access_token(refresh_token: string): Promise<StoredCredentials | null>;
+/**
+ * Get a valid (non-expired) access token, refreshing if necessary.
+ * Returns the access token string, or null if no valid token is available.
+ */
+export declare function get_valid_token(log: (msg: string) => void): Promise<string | null>;

package/dist/credentials.js

@@ -0,0 +1,109 @@
+/**
+ * Shared credential management for VoiceMode Connect.
+ *
+ * Auth0 constants, credential file I/O, and token refresh logic
+ * used by both the gateway client and the auth login flow.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// ---------------------------------------------------------------------------
+// Auth0 configuration
+// ---------------------------------------------------------------------------
+export const AUTH0_DOMAIN = 'dev-2q681p5hobd1dtmm.us.auth0.com';
+export const AUTH0_CLIENT_ID = '1uJR1Q4HMkLkhzOXTg5JFuqBCq0FBsXK';
+// ---------------------------------------------------------------------------
+// Credential storage
+// ---------------------------------------------------------------------------
+export const CREDENTIALS_FILE = join(homedir(), '.voicemode', 'credentials');
+const TOKEN_EXPIRY_BUFFER_SECONDS = 60;
+// ---------------------------------------------------------------------------
+// Credential helpers
+// ---------------------------------------------------------------------------
+export function load_credentials() {
+    try {
+        const raw = readFileSync(CREDENTIALS_FILE, 'utf-8');
+        const data = JSON.parse(raw);
+        if (!data.access_token)
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+export function save_credentials(creds) {
+    try {
+        const dir = join(homedir(), '.voicemode');
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // Best effort -- if we can't save, we continue with the in-memory token
+    }
+}
+export function is_expired(creds) {
+    return Date.now() / 1000 >= (creds.expires_at - TOKEN_EXPIRY_BUFFER_SECONDS);
+}
+export async function refresh_access_token(refresh_token) {
+    const token_url = `https://${AUTH0_DOMAIN}/oauth/token`;
+    const body = new URLSearchParams({
+        grant_type: 'refresh_token',
+        client_id: AUTH0_CLIENT_ID,
+        refresh_token,
+    });
+    try {
+        const response = await fetch(token_url, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: body.toString(),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const data = (await response.json());
+        const expires_in = data.expires_in ?? 3600;
+        const new_creds = {
+            access_token: data.access_token,
+            refresh_token: data.refresh_token ?? refresh_token,
+            expires_at: Date.now() / 1000 + expires_in,
+            token_type: data.token_type ?? 'Bearer',
+        };
+        return new_creds;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get a valid (non-expired) access token, refreshing if necessary.
+ * Returns the access token string, or null if no valid token is available.
+ */
+export async function get_valid_token(log) {
+    const creds = load_credentials();
+    if (!creds) {
+        log('No credentials found at ~/.voicemode/credentials');
+        log('Run: voicemode connect auth login');
+        return null;
+    }
+    if (!is_expired(creds)) {
+        return creds.access_token;
+    }
+    log('Access token expired, attempting refresh...');
+    if (!creds.refresh_token) {
+        log('No refresh token available -- please re-login');
+        log('Run: voicemode connect auth login');
+        return null;
+    }
+    const refreshed = await refresh_access_token(creds.refresh_token);
+    if (!refreshed) {
+        log('Token refresh failed -- please re-login');
+        log('Run: voicemode connect auth login');
+        return null;
+    }
+    // Preserve user_info from original credentials
+    refreshed.user_info = creds.user_info;
+    save_credentials(refreshed);
+    log('Token refreshed successfully');
+    return refreshed.access_token;
+}