voicemode-channel 0.1.4 → 0.2.0

package/README.md

@@ -17,6 +17,7 @@ User hears TTS response  <- Channel reply tool <----------------------+
 ### Claude Code plugin
 
 ```bash
+claude plugin marketplace add mbailey/claude-plugins
 claude plugin install voicemode-channel@mbailey
 ```
 
@@ -63,13 +64,13 @@ Open **[app.voicemode.dev](https://app.voicemode.dev)** on your phone or browser
 
 ## 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 |
+| 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
 
@@ -81,6 +82,7 @@ This plugin provides an MCP server that declares the experimental `claude/channe
 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>
 ```
@@ -88,20 +90,24 @@ Channel events appear in Claude's session as:
 ## 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
 
@@ -114,12 +120,37 @@ cd voicemode-channel
 npm install
 
 # Build
-npm run 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.

package/dist/auth.js

@@ -12,7 +12,6 @@ import { createHash, randomBytes } from 'node:crypto';
 import { createServer } from 'node:http';
 import { execFile } from 'node:child_process';
 import { platform } from 'node:os';
-import { createConnection } from 'node:net';
 import { AUTH0_DOMAIN, AUTH0_CLIENT_ID, save_credentials, } from './credentials.js';
 // ---------------------------------------------------------------------------
 // Auth0 OAuth parameters (matching Python CLI)
@@ -38,23 +37,27 @@ function generate_pkce_params() {
 // ---------------------------------------------------------------------------
 // Port selection
 // ---------------------------------------------------------------------------
-function is_port_available(port) {
+/**
+ * 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) => {
-        const sock = createConnection({ host: '127.0.0.1', port });
-        sock.once('connect', () => { sock.destroy(); resolve(false); });
-        sock.once('error', () => { sock.destroy(); resolve(true); });
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE')
+                resolve(false);
+            else
+                resolve(false);
+        });
+        server.listen(port, '127.0.0.1', () => resolve(true));
     });
 }
-async function find_available_port() {
-    for (let port = CALLBACK_PORT_START; port <= CALLBACK_PORT_END; port++) {
-        if (await is_port_available(port))
-            return port;
-    }
-    return null;
-}
 // ---------------------------------------------------------------------------
 // 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
@@ -63,7 +66,7 @@ function callback_page(success, error_message = '') {
     const heading = success ? 'Authentication Successful' : 'Authentication Failed';
     const message = success
         ? 'You can close this window and return to the terminal.'
-        : (error_message ? `Error: ${error_message}` : 'Something went wrong.');
+        : (error_message ? `Error: ${escape_html(error_message)}` : 'Something went wrong.');
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -195,22 +198,15 @@ function build_authorize_url(redirect_uri, pkce, state) {
 // Main login flow
 // ---------------------------------------------------------------------------
 export async function login(log) {
-    // Find available port
-    const port = await find_available_port();
-    if (port === null) {
-        throw new Error(`No available ports in range ${CALLBACK_PORT_START}-${CALLBACK_PORT_END}. ` +
-            'Please close applications using these ports and try again.');
-    }
-    // Generate PKCE parameters and state
+    // Generate PKCE parameters and state upfront (needed for the request handler)
     const pkce = generate_pkce_params();
     const state = randomBytes(16).toString('base64url');
-    const redirect_uri = `http://localhost:${port}/callback`;
-    // Build authorization URL
-    const auth_url = build_authorize_url(redirect_uri, pkce, state);
-    // Start callback server and wait for the authorization code
+    // 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) => {
-        const server = createServer((req, res) => {
-            const url = new URL(req.url ?? '/', `http://localhost:${port}`);
+        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();
@@ -236,7 +232,7 @@ export async function login(log) {
             res.writeHead(200, { 'Content-Type': 'text/html' });
             res.end(callback_page(true));
             cleanup();
-            resolve({ code, state: url.searchParams.get('state') });
+            resolve({ code, state: url.searchParams.get('state'), port: bound_port });
         });
         const timeout_timer = setTimeout(() => {
             cleanup();
@@ -244,10 +240,24 @@ export async function login(log) {
         }, CALLBACK_TIMEOUT_MS);
         function cleanup() {
             clearTimeout(timeout_timer);
-            server.close();
+            callback_server.close();
         }
-        server.listen(port, '127.0.0.1', () => {
-            log(`Callback server listening on port ${port}`);
+        // 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') {
@@ -258,11 +268,7 @@ export async function login(log) {
                 log('Opening browser for authentication...');
             }
             log('Waiting for authentication (up to 5 minutes)...');
-        });
-        server.on('error', (err) => {
-            cleanup();
-            reject(new Error(`Callback server error: ${err.message}`));
-        });
+        }).catch(reject);
     });
     if (result === null) {
         throw new Error('Authentication timed out. Please try again.');
@@ -273,6 +279,7 @@ export async function login(log) {
     }
     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)

package/dist/credentials.js

@@ -35,7 +35,7 @@ export function load_credentials() {
 export function save_credentials(creds) {
     try {
         const dir = join(homedir(), '.voicemode');
-        mkdirSync(dir, { recursive: true });
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
         writeFileSync(CREDENTIALS_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
     }
     catch {

package/dist/gateway.js

@@ -23,6 +23,9 @@ import { get_valid_token } from './credentials.js';
 // Configuration
 // ---------------------------------------------------------------------------
 const WS_URL = process.env.VOICEMODE_CONNECT_WS_URL ?? 'wss://voicemode.dev/ws';
+if (WS_URL.startsWith('ws://')) {
+    process.stderr.write('[voicemode-channel] WARNING: Gateway URL uses unencrypted ws:// -- tokens will be sent in cleartext\n');
+}
 const HEARTBEAT_INTERVAL_MS = 25_000;
 const HEARTBEAT_LIVENESS_TIMEOUT_MS = 60_000; // Force-close if no pong received within this window
 const INITIAL_RETRY_DELAY_MS = 1_000;
@@ -287,8 +290,8 @@ export class GatewayClient extends EventEmitter {
         const display_name = profile?.display_name ?? process.env.VOICEMODE_AGENT_DISPLAY_NAME ?? 'Claude Code';
         const presence = profile?.presence ?? 'available';
         const host = hostname();
-        const project_path = process.cwd();
-        const context = profile?.context ?? get_project_context(project_path);
+        const project_path = basename(process.cwd()); // Send basename only -- don't leak full filesystem path
+        const context = profile?.context ?? get_project_context(process.cwd());
         const user_entry = {
             name: agent_name,
             host,

package/dist/index.js

@@ -38,6 +38,9 @@ try {
             continue;
         const key = trimmed.slice(0, eq).trim();
         const value = trimmed.slice(eq + 1).trim().replace(/^["']|["']$/g, '');
+        // Only allow VOICEMODE_ prefixed keys to prevent env var injection
+        if (!key.startsWith('VOICEMODE_'))
+            continue;
         // Don't override existing env vars
         if (!(key in process.env)) {
             process.env[key] = value;
@@ -116,6 +119,7 @@ if (process.env.VOICEMODE_CHANNEL_ENABLED !== 'true') {
     process.stderr.write('VoiceMode channel server disabled. Set VOICEMODE_CHANNEL_ENABLED=true to enable.\n');
     process.exit(0);
 }
+const WS_URL = process.env.VOICEMODE_CONNECT_WS_URL ?? 'wss://voicemode.dev/ws';
 const CHANNEL_NAME = 'voicemode-channel';
 const CHANNEL_VERSION = '0.1.4';
 const INSTRUCTIONS = [
@@ -183,6 +187,15 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => {
                     required: ['text'],
                 },
             },
+            {
+                name: 'status',
+                description: 'Check the current status of the VoiceMode channel. ' +
+                    'Returns connection state, gateway URL, session IDs, auth info, and current profile.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
             {
                 name: 'profile',
                 description: 'Get or update the agent profile. ' +
@@ -220,6 +233,9 @@ mcp.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    if (name === 'status') {
+        return handle_status_tool();
+    }
     if (name === 'profile') {
         return handle_profile_tool(args);
     }
@@ -232,6 +248,50 @@ mcp.setRequestHandler(CallToolRequestSchema, async (request) => {
     };
 });
 // ---------------------------------------------------------------------------
+// Tool handler: status
+// ---------------------------------------------------------------------------
+function handle_status_tool() {
+    const lines = [];
+    // Connection state
+    const state = gateway?.state ?? 'disconnected';
+    lines.push(`Connection: ${state}`);
+    lines.push(`Gateway: ${WS_URL}`);
+    // Session IDs
+    const server_session = gateway?.session_id ?? 'none';
+    const agent_session = gateway?.agent_session_id ?? 'none';
+    lines.push(`Session: ${server_session} (server) / ${agent_session} (agent)`);
+    lines.push('');
+    // Auth info
+    const creds = load_credentials();
+    if (creds) {
+        const expired = is_expired(creds);
+        const expires_date = new Date(creds.expires_at * 1000);
+        const expires_str = expires_date.toISOString().slice(0, 16);
+        lines.push(`Auth: authenticated`);
+        const name = creds.user_info?.name;
+        const email = creds.user_info?.email;
+        if (name || email) {
+            const parts = [name, email ? `(${email})` : null].filter(Boolean).join(' ');
+            lines.push(`User: ${parts}`);
+        }
+        lines.push(`Token: ${expired ? 'expired' : 'valid'} (expires ${expires_str})`);
+    }
+    else {
+        lines.push('Auth: not authenticated');
+    }
+    lines.push('');
+    // Profile
+    lines.push(`Profile: set`);
+    lines.push(`  Name: ${currentProfile.name}`);
+    lines.push(`  Display: ${currentProfile.display_name}`);
+    lines.push(`  Context: ${currentProfile.context ?? 'none'}`);
+    lines.push(`  Voice: ${currentProfile.voice ?? 'default'}`);
+    lines.push(`  Presence: ${currentProfile.presence}`);
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+    };
+}
+// ---------------------------------------------------------------------------
 // Tool handler: reply
 // ---------------------------------------------------------------------------
 function handle_reply_tool(args) {
@@ -293,15 +353,16 @@ function handle_profile_tool(args) {
                 }],
         };
     }
-    // Merge provided fields into current profile
+    // Merge provided fields into current profile (cap at 200 chars to prevent abuse)
+    const cap = (s) => s.slice(0, 200);
     if (typeof args.name === 'string')
-        currentProfile.name = args.name;
+        currentProfile.name = cap(args.name);
     if (typeof args.display_name === 'string')
-        currentProfile.display_name = args.display_name;
+        currentProfile.display_name = cap(args.display_name);
     if (typeof args.context === 'string')
-        currentProfile.context = args.context;
+        currentProfile.context = cap(args.context);
     if (typeof args.voice === 'string')
-        currentProfile.voice = args.voice;
+        currentProfile.voice = cap(args.voice);
     if (args.presence === 'available' || args.presence === 'busy' || args.presence === 'away')
         currentProfile.presence = args.presence;
     log(`Profile updated: ${JSON.stringify(currentProfile)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "voicemode-channel",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "VoiceMode Channel - inbound voice calls to Claude Code via VoiceMode Connect",
   "type": "module",
   "main": "dist/index.js",
@@ -20,9 +20,9 @@
     "ws": "^8.18.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^25.5.2",
     "@types/ws": "^8.5.0",
     "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
+    "typescript": "^6.0.2"
   }
 }