luxlabs 1.0.0

package/commands/voice-agents.js

@@ -0,0 +1,1055 @@
+/**
+ * Voice Agents CLI Commands
+ *
+ * Manage ElevenLabs voice agents from the command line.
+ * This allows Claude Code to create, update, and manage voice agents
+ * without requiring the user to use the Lux Studio UI.
+ */
+
+const axios = require('axios');
+const chalk = require('chalk');
+const fs = require('fs');
+const path = require('path');
+const {
+  getApiUrl,
+  getStudioApiUrl,
+  getAuthHeaders,
+  isAuthenticated,
+  getOrgId,
+  getProjectId,
+  LUX_STUDIO_DIR,
+} = require('../lib/config');
+const {
+  error,
+  success,
+  info,
+  warn,
+  formatTable,
+  requireArgs,
+  parseJson,
+} = require('../lib/helpers');
+
+// ElevenLabs API base URL
+const ELEVENLABS_API_URL = 'https://api.elevenlabs.io/v1';
+
+// Lux Studio API URL for webhooks and credentials
+const LUX_STUDIO_API_URL = process.env.LUX_STUDIO_API_URL || 'https://v2.uselux.ai';
+
+// Built-in voice names
+const BUILT_IN_VOICES = [
+  'Rachel', 'Drew', 'Clyde', 'Paul', 'Domi',
+  'Dave', 'Fin', 'Sarah', 'Antoni', 'Thomas',
+];
+
+/**
+ * Get the voice agents cache path for the current project
+ */
+function getCachePath() {
+  const orgId = getOrgId();
+  const projectId = getProjectId();
+  if (!orgId || !projectId) return null;
+
+  // Handle org ID format (might have org_ prefix or not)
+  const orgDir = orgId.startsWith('org_') ? orgId : `org_${orgId}`;
+  return path.join(LUX_STUDIO_DIR, orgDir, 'projects', projectId, 'voice-agents-cache.json');
+}
+
+/**
+ * Read the local cache
+ */
+function readCache() {
+  const cachePath = getCachePath();
+  if (!cachePath || !fs.existsSync(cachePath)) {
+    return { agents: [], phoneNumbers: [], lastUpdated: null };
+  }
+
+  try {
+    return JSON.parse(fs.readFileSync(cachePath, 'utf8'));
+  } catch {
+    return { agents: [], phoneNumbers: [], lastUpdated: null };
+  }
+}
+
+/**
+ * Write to the local cache
+ */
+function writeCache(data) {
+  const cachePath = getCachePath();
+  if (!cachePath) return;
+
+  const dir = path.dirname(cachePath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const cache = {
+    ...readCache(),
+    ...data,
+    lastUpdated: new Date().toISOString(),
+  };
+
+  fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+}
+
+/**
+ * Get voice agent API key from Lux platform credentials
+ * Uses the platform credential endpoint (shared across all users)
+ */
+async function getVoiceAgentApiKey() {
+  try {
+    // Use platform credential endpoint (shared key, not per-project)
+    const { data } = await axios.get(
+      `${LUX_STUDIO_API_URL}/api/platform/credentials/elevenlabs`,
+      { headers: getAuthHeaders() }
+    );
+
+    // Response format: { type: 'elevenlabs', data: { apiKey } }
+    if (data?.data?.apiKey) {
+      return data.data.apiKey;
+    }
+
+    return null;
+  } catch (err) {
+    // Platform credential not available
+    return null;
+  }
+}
+
+/**
+ * Make ElevenLabs API request
+ */
+async function elevenLabsRequest(method, endpoint, apiKey, data = null) {
+  const config = {
+    method,
+    url: `${ELEVENLABS_API_URL}${endpoint}`,
+    headers: {
+      'xi-api-key': apiKey,
+      'Content-Type': 'application/json',
+    },
+  };
+
+  if (data) {
+    config.data = data;
+  }
+
+  const response = await axios(config);
+  return response.data;
+}
+
+/**
+ * List all agents for the current project
+ */
+async function listAgents(apiKey) {
+  const projectId = getProjectId();
+  const projectTag = `project-${projectId}`;
+
+  const data = await elevenLabsRequest('GET', '/convai/agents', apiKey);
+
+  // Filter to only agents tagged with this project
+  // Note: Tags are at agent.tags, not agent.metadata.tags
+  const agents = (data.agents || [])
+    .filter(agent => {
+      const tags = agent.tags || [];
+      return tags.includes(projectTag);
+    })
+    .map(agent => ({
+      id: agent.agent_id,
+      name: agent.name,
+      voice: agent.conversation_config?.agent?.prompt?.llm?.model || '',
+      voiceId: agent.conversation_config?.tts?.voice_id || '',
+      systemPrompt: agent.conversation_config?.agent?.prompt?.prompt || '',
+      greeting: agent.conversation_config?.agent?.first_message || '',
+      maxDurationSeconds: agent.conversation_config?.conversation?.max_duration_seconds || 600,
+      temperature: agent.conversation_config?.agent?.prompt?.temperature || 0.7,
+      language: agent.conversation_config?.agent?.language || 'en',
+      tags: agent.tags || [],
+      createdAt: agent.created_at,
+    }));
+
+  return agents;
+}
+
+/**
+ * Get a single agent
+ */
+async function getAgent(apiKey, agentId) {
+  const data = await elevenLabsRequest('GET', `/convai/agents/${agentId}`, apiKey);
+
+  return {
+    id: data.agent_id,
+    name: data.name,
+    voice: data.conversation_config?.tts?.voice_id || '',
+    voiceId: data.conversation_config?.tts?.voice_id || '',
+    systemPrompt: data.conversation_config?.agent?.prompt?.prompt || '',
+    greeting: data.conversation_config?.agent?.first_message || '',
+    maxDurationSeconds: data.conversation_config?.conversation?.max_duration_seconds || 600,
+    temperature: data.conversation_config?.agent?.prompt?.temperature || 0.7,
+    language: data.conversation_config?.agent?.language || 'en',
+    tags: data.tags || [],
+  };
+}
+
+// Voice name to ID mapping (same as elevenlabs-client.ts)
+const VOICE_MAP = {
+  Rachel: '21m00Tcm4TlvDq8ikWAM',
+  Drew: '29vD33N1CtxCmqQRPOHJ',
+  Clyde: '2EiwWnXFnvU5JabPnv8n',
+  Paul: '5Q0t7uMcjvnagumLfvZi',
+  Domi: 'AZnzlk1XvdvUeBnXmlld',
+  Dave: 'CYw3kZ02Hs0563khs1Fj',
+  Fin: 'D38z5RcWu1voky8WS1ja',
+  Sarah: 'EXAVITQu4vr4xnSDxMaL',
+  Antoni: 'ErXwobaYiN019PkySvjV',
+  Thomas: 'GBv7mTt0atIp3Br8iCZE',
+};
+
+/**
+ * Create a new agent
+ * Uses the same API structure as elevenlabs-client.ts
+ */
+async function createAgent(apiKey, config) {
+  const projectId = getProjectId();
+  const voiceId = VOICE_MAP[config.voice] || config.voiceId || config.voice || VOICE_MAP['Rachel'];
+
+  // Build ElevenLabs agent config (same structure as elevenlabs-client.ts)
+  const agentConfig = {
+    name: config.name,
+    conversation_config: {
+      agent: {
+        prompt: {
+          prompt: config.systemPrompt || '',
+          llm: 'gemini-2.0-flash',
+          temperature: config.temperature || 0.7,
+          max_tokens: 500,
+        },
+        first_message: config.greeting || 'Hello! How can I help you today?',
+        language: config.language || 'en',
+      },
+      tts: {
+        voice_id: voiceId,
+        model_id: 'eleven_flash_v2',
+        optimize_streaming_latency: 3,
+        stability: 0.5,
+        similarity_boost: 0.75,
+        speed: 1.0,
+        use_speaker_boost: true,
+      },
+      asr: {
+        quality: 'high',
+        provider: 'elevenlabs',
+        user_input_audio_format: 'pcm_16000',
+      },
+      turn: {
+        mode: 'turn',
+        turn_timeout: 7,
+      },
+      conversation: {
+        max_duration_seconds: config.maxDurationSeconds || 600,
+        silence_timeout_seconds: -1,
+      },
+      privacy: {
+        retention_days: -1,
+      },
+    },
+    tags: ['lux-platform', `project-${projectId}`],
+  };
+
+  // Add data collection if configured
+  if (config.dataCollection && config.dataCollection.length > 0) {
+    agentConfig.data_collection = {
+      schema: config.dataCollection.map(field => ({
+        identifier: field.identifier,
+        type: field.type || 'string',
+        description: field.description || '',
+      })),
+    };
+  }
+
+  // Use /convai/agents/create endpoint (not /convai/agents)
+  const data = await elevenLabsRequest('POST', '/convai/agents/create', apiKey, agentConfig);
+
+  return {
+    id: data.agent_id,
+    name: data.name,
+  };
+}
+
+/**
+ * Update an agent
+ * Uses the same API structure as elevenlabs-client.ts
+ */
+async function updateAgent(apiKey, agentId, config) {
+  // First get existing agent to merge config
+  const existing = await getAgent(apiKey, agentId);
+  const voiceId = config.voice ? (VOICE_MAP[config.voice] || config.voice) : existing.voiceId;
+
+  // Build update config (same structure as elevenlabs-client.ts)
+  const updateConfig = {};
+
+  if (config.name) {
+    updateConfig.name = config.name;
+  }
+
+  // Only include conversation_config if we're updating relevant fields
+  const needsConversationConfig =
+    config.systemPrompt !== undefined ||
+    config.greeting !== undefined ||
+    config.voice !== undefined ||
+    config.temperature !== undefined ||
+    config.maxDurationSeconds !== undefined ||
+    config.language !== undefined;
+
+  if (needsConversationConfig) {
+    updateConfig.conversation_config = {
+      agent: {
+        prompt: {
+          prompt: config.systemPrompt !== undefined ? config.systemPrompt : existing.systemPrompt,
+          llm: 'gemini-2.0-flash',
+          temperature: config.temperature !== undefined ? config.temperature : existing.temperature,
+          max_tokens: 500,
+        },
+        first_message: config.greeting !== undefined ? config.greeting : existing.greeting,
+        language: config.language || existing.language,
+      },
+      tts: {
+        voice_id: voiceId,
+        model_id: 'eleven_flash_v2',
+        optimize_streaming_latency: 3,
+        stability: 0.5,
+        similarity_boost: 0.75,
+        speed: 1.0,
+        use_speaker_boost: true,
+      },
+      asr: {
+        quality: 'high',
+        provider: 'elevenlabs',
+        user_input_audio_format: 'pcm_16000',
+      },
+      turn: {
+        mode: 'turn',
+        turn_timeout: 7,
+      },
+      conversation: {
+        max_duration_seconds: config.maxDurationSeconds || existing.maxDurationSeconds,
+        silence_timeout_seconds: -1,
+      },
+      privacy: {
+        retention_days: -1,
+      },
+    };
+  }
+
+  // Add data collection if configured
+  if (config.dataCollection && config.dataCollection.length > 0) {
+    updateConfig.data_collection = {
+      schema: config.dataCollection.map(field => ({
+        identifier: field.identifier,
+        type: field.type || 'string',
+        description: field.description || '',
+      })),
+    };
+  }
+
+  const data = await elevenLabsRequest('PATCH', `/convai/agents/${agentId}`, apiKey, updateConfig);
+
+  return {
+    id: data.agent_id,
+    name: data.name,
+  };
+}
+
+/**
+ * Delete an agent
+ */
+async function deleteAgent(apiKey, agentId) {
+  await elevenLabsRequest('DELETE', `/convai/agents/${agentId}`, apiKey);
+}
+
+/**
+ * List phone numbers
+ */
+async function listPhoneNumbers(apiKey) {
+  const data = await elevenLabsRequest('GET', '/convai/phone-numbers', apiKey);
+
+  return (data.phone_numbers || []).map(pn => ({
+    id: pn.phone_number_id,
+    phoneNumber: pn.phone_number,
+    label: pn.label || pn.phone_number,
+    provider: pn.provider || 'unknown',
+  }));
+}
+
+// =============================================================================
+// TWILIO API FUNCTIONS (for Lux-managed inbound calls)
+// =============================================================================
+
+/**
+ * Get Twilio credentials from Lux credentials
+ */
+async function getTwilioCredentials() {
+  const projectId = getProjectId();
+  const studioApiUrl = getStudioApiUrl();
+
+  try {
+    const { data } = await axios.get(
+      `${studioApiUrl}/api/projects/${projectId}/credentials/by-type/twilio`,
+      { headers: getAuthHeaders() }
+    );
+
+    if (data?.credential?.data?.accountSid && data?.credential?.data?.authToken) {
+      return {
+        accountSid: data.credential.data.accountSid,
+        authToken: data.credential.data.authToken,
+      };
+    }
+
+    return null;
+  } catch (err) {
+    // If that fails, try the dashboard API
+    try {
+      const apiUrl = getApiUrl();
+      const { data } = await axios.get(
+        `${apiUrl}/api/projects/${projectId}/credentials/by-type/twilio`,
+        { headers: getAuthHeaders() }
+      );
+      if (data?.credential?.data?.accountSid && data?.credential?.data?.authToken) {
+        return {
+          accountSid: data.credential.data.accountSid,
+          authToken: data.credential.data.authToken,
+        };
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Make Twilio API request
+ */
+async function twilioRequest(method, endpoint, creds, data = null) {
+  const auth = Buffer.from(`${creds.accountSid}:${creds.authToken}`).toString('base64');
+  const config = {
+    method,
+    url: `https://api.twilio.com/2010-04-01/Accounts/${creds.accountSid}${endpoint}`,
+    headers: {
+      'Authorization': `Basic ${auth}`,
+      'Content-Type': 'application/x-www-form-urlencoded',
+    },
+  };
+
+  if (data) {
+    config.data = new URLSearchParams(data).toString();
+  }
+
+  const response = await axios(config);
+  return response.data;
+}
+
+/**
+ * List Twilio phone numbers
+ */
+async function listTwilioPhoneNumbers(creds) {
+  const data = await twilioRequest('GET', '/IncomingPhoneNumbers.json', creds);
+  const cache = readCache();
+  const inboundConfig = cache.inboundConfig || {};
+
+  return (data.incoming_phone_numbers || []).map(p => ({
+    sid: p.sid,
+    phoneNumber: p.phone_number,
+    friendlyName: p.friendly_name,
+    voiceUrl: p.voice_url || null,
+    isLuxManaged: p.voice_url?.includes('lux-studio-api') || false,
+    inboundConfig: inboundConfig[p.phone_number] || null,
+  }));
+}
+
+/**
+ * Configure Twilio phone number for Lux-managed inbound calls
+ */
+async function configureTwilioInbound(creds, phoneNumber, flowId) {
+  // Find the phone number SID
+  const numbers = await listTwilioPhoneNumbers(creds);
+  const target = numbers.find(n => n.phoneNumber === phoneNumber);
+
+  if (!target) {
+    throw new Error(`Phone number ${phoneNumber} not found in your Twilio account`);
+  }
+
+  // Build webhook URL
+  const orgId = getOrgId();
+  const webhookUrl = `${LUX_STUDIO_API_URL}/api/webhooks/${flowId}?org=${orgId}`;
+
+  // Configure Twilio
+  await twilioRequest('POST', `/IncomingPhoneNumbers/${target.sid}.json`, creds, {
+    VoiceUrl: webhookUrl,
+    VoiceMethod: 'POST',
+  });
+
+  // Update cache
+  const cache = readCache();
+  const inboundConfig = cache.inboundConfig || {};
+  inboundConfig[phoneNumber] = {
+    flowId,
+    webhookUrl,
+    mode: 'lux-managed',
+    configuredAt: new Date().toISOString(),
+  };
+  writeCache({ inboundConfig });
+
+  return { webhookUrl, phoneNumberSid: target.sid };
+}
+
+/**
+ * Reset Twilio phone number configuration
+ */
+async function resetTwilioInbound(creds, phoneNumber) {
+  // Find the phone number SID
+  const numbers = await listTwilioPhoneNumbers(creds);
+  const target = numbers.find(n => n.phoneNumber === phoneNumber);
+
+  if (!target) {
+    throw new Error(`Phone number ${phoneNumber} not found in your Twilio account`);
+  }
+
+  // Clear webhook URL
+  await twilioRequest('POST', `/IncomingPhoneNumbers/${target.sid}.json`, creds, {
+    VoiceUrl: '',
+    StatusCallback: '',
+  });
+
+  // Update cache
+  const cache = readCache();
+  const inboundConfig = cache.inboundConfig || {};
+  delete inboundConfig[phoneNumber];
+  writeCache({ inboundConfig });
+
+  return { phoneNumberSid: target.sid };
+}
+
+/**
+ * Main handler for voice-agents commands
+ */
+async function handleVoiceAgents(args) {
+  // Check authentication
+  if (!isAuthenticated()) {
+    console.log(
+      chalk.red('❌ Not authenticated. Run'),
+      chalk.white('lux login'),
+      chalk.red('first.')
+    );
+    process.exit(1);
+  }
+
+  const command = args[0];
+
+  if (!command) {
+    console.log(`
+${chalk.bold('Usage:')} lux voice-agents <command> [args]
+
+${chalk.bold('Agent Commands:')}
+  list                              List all voice agents for current project
+  get <agent-id>                    Get agent details
+  create <name> [options]           Create a new voice agent
+  update <agent-id> [options]       Update an existing agent
+  delete <agent-id>                 Delete an agent
+  phones                            List available phone numbers
+
+${chalk.bold('Inbound Call Commands (Lux-managed):')}
+  twilio-numbers                    List Twilio phone numbers with webhook status
+  configure-inbound <phone> <flow>  Configure phone number for Lux-managed inbound calls
+  inbound-status <phone>            Check inbound configuration status
+  reset-inbound <phone>             Reset phone number configuration
+
+${chalk.bold('Utility Commands:')}
+  status                            Check voice agent prerequisites (credentials, phone numbers)
+  cache                             Show local cache status
+
+${chalk.bold('Create/Update Options:')}
+  --voice <name>                    Voice name (Rachel, Drew, Sarah, etc.)
+  --prompt <text>                   System prompt for the agent
+  --prompt-file <path>              Read system prompt from file
+  --greeting <text>                 First message when call starts
+  --temperature <0-1>               Response creativity (default: 0.7)
+  --max-duration <seconds>          Max call length (default: 600)
+  --language <code>                 Language code (default: en)
+  --data-collection <json>          Data fields to collect (JSON array)
+
+${chalk.bold('Examples:')}
+  lux voice-agents list
+  lux voice-agents create "Support Agent" --voice Rachel --prompt "You are helpful."
+  lux voice-agents create "City Collector" --voice Rachel --prompt "Ask what city..." \\
+    --data-collection '[{"identifier":"city","type":"string","description":"User city"}]'
+  lux voice-agents twilio-numbers
+  lux voice-agents configure-inbound +15551234567 flow_abc123
+  lux voice-agents inbound-status +15551234567
+
+${chalk.bold('Available Voices:')}
+  ${BUILT_IN_VOICES.join(', ')}
+`);
+    process.exit(0);
+  }
+
+  // Get voice agent API key from platform credentials
+  info('Loading voice agent credentials...');
+  const apiKey = await getVoiceAgentApiKey();
+
+  if (!apiKey && command !== 'cache' && command !== 'status') {
+    error(
+      'Voice agent credentials not available.\n\n' +
+      'Voice agents may not be enabled for this project.\n' +
+      'Contact support if this issue persists.'
+    );
+  }
+
+  try {
+    switch (command) {
+      case 'list': {
+        info('Loading voice agents...');
+        const agents = await listAgents(apiKey);
+
+        // Update cache
+        writeCache({ agents });
+
+        if (agents.length === 0) {
+          console.log('\n(No voice agents found for this project)\n');
+          console.log('Create one with: lux voice-agents create "Agent Name" --voice Rachel --prompt "..."');
+        } else {
+          console.log(`\n${chalk.bold('Voice Agents')} (${agents.length})\n`);
+          agents.forEach((a, i) => {
+            console.log(`  ${chalk.cyan(a.name)}`);
+            console.log(`    Voice: ${a.voice || '(default)'}`);
+            const promptPreview = (a.systemPrompt || '').substring(0, 60).replace(/\n/g, ' ');
+            if (promptPreview) {
+              console.log(`    Prompt: ${promptPreview}${a.systemPrompt?.length > 60 ? '...' : ''}`);
+            }
+            console.log(`    ID: ${chalk.gray(a.id)}`);
+            if (i < agents.length - 1) console.log('');
+          });
+        }
+        break;
+      }
+
+      case 'get': {
+        requireArgs(args.slice(1), 1, 'lux voice-agents get <agent-id>');
+        const agentId = args[1];
+
+        info(`Loading agent: ${agentId}`);
+        const agent = await getAgent(apiKey, agentId);
+
+        console.log(`\n🤖 Agent Details:\n`);
+        console.log(`  ID:           ${agent.id}`);
+        console.log(`  Name:         ${agent.name}`);
+        console.log(`  Voice:        ${agent.voice || '(default)'}`);
+        console.log(`  Language:     ${agent.language}`);
+        console.log(`  Temperature:  ${agent.temperature}`);
+        console.log(`  Max Duration: ${agent.maxDurationSeconds}s`);
+        console.log(`  Greeting:     ${agent.greeting || '(none)'}`);
+        console.log(`\n📝 System Prompt:\n`);
+        console.log(agent.systemPrompt || '(empty)');
+        console.log('');
+        break;
+      }
+
+      case 'create': {
+        requireArgs(args.slice(1), 1, 'lux voice-agents create <name> [options]');
+        const name = args[1];
+
+        // Parse options
+        const options = parseOptions(args.slice(2));
+
+        // Read prompt from file if specified
+        if (options.promptFile) {
+          options.systemPrompt = fs.readFileSync(options.promptFile, 'utf8');
+        }
+
+        info(`Creating voice agent: ${name}`);
+        const agent = await createAgent(apiKey, {
+          name,
+          voice: options.voice,
+          voiceId: options.voice,
+          systemPrompt: options.prompt || options.systemPrompt,
+          greeting: options.greeting,
+          temperature: options.temperature ? parseFloat(options.temperature) : undefined,
+          maxDurationSeconds: options.maxDuration ? parseInt(options.maxDuration) : undefined,
+          language: options.language,
+          dataCollection: options.dataCollection ? JSON.parse(options.dataCollection) : undefined,
+        });
+
+        // Refresh cache
+        const agents = await listAgents(apiKey);
+        writeCache({ agents });
+
+        success(`Voice agent created!`);
+        console.log(`  ID:   ${agent.id}`);
+        console.log(`  Name: ${agent.name}`);
+        break;
+      }
+
+      case 'update': {
+        requireArgs(args.slice(1), 1, 'lux voice-agents update <agent-id> [options]');
+        const agentId = args[1];
+
+        // Parse options
+        const options = parseOptions(args.slice(2));
+
+        // Read prompt from file if specified
+        if (options.promptFile) {
+          options.systemPrompt = fs.readFileSync(options.promptFile, 'utf8');
+        }
+
+        info(`Updating voice agent: ${agentId}`);
+        const agent = await updateAgent(apiKey, agentId, {
+          name: options.name,
+          voice: options.voice,
+          voiceId: options.voice,
+          systemPrompt: options.prompt || options.systemPrompt,
+          greeting: options.greeting,
+          temperature: options.temperature ? parseFloat(options.temperature) : undefined,
+          maxDurationSeconds: options.maxDuration ? parseInt(options.maxDuration) : undefined,
+          language: options.language,
+          dataCollection: options.dataCollection ? JSON.parse(options.dataCollection) : undefined,
+        });
+
+        // Refresh cache
+        const agents = await listAgents(apiKey);
+        writeCache({ agents });
+
+        success(`Voice agent updated!`);
+        console.log(`  ID:   ${agent.id}`);
+        console.log(`  Name: ${agent.name}`);
+        break;
+      }
+
+      case 'delete': {
+        requireArgs(args.slice(1), 1, 'lux voice-agents delete <agent-id>');
+        const agentId = args[1];
+
+        info(`Deleting voice agent: ${agentId}`);
+        await deleteAgent(apiKey, agentId);
+
+        // Refresh cache
+        const agents = await listAgents(apiKey);
+        writeCache({ agents });
+
+        success('Voice agent deleted!');
+        break;
+      }
+
+      case 'phones': {
+        info('Loading phone numbers...');
+        const phoneNumbers = await listPhoneNumbers(apiKey);
+
+        // Update cache
+        writeCache({ phoneNumbers });
+
+        if (phoneNumbers.length === 0) {
+          console.log('\n(No phone numbers found)\n');
+          console.log('Import a Twilio phone number in Lux Studio Voice Agents panel.');
+        } else {
+          console.log(`\n${chalk.bold('Phone Numbers')} (${phoneNumbers.length})\n`);
+          phoneNumbers.forEach((pn, i) => {
+            console.log(`  ${chalk.cyan(pn.phoneNumber)}`);
+            if (pn.label && pn.label !== pn.phoneNumber) {
+              console.log(`    Label: ${pn.label}`);
+            }
+            console.log(`    ID: ${chalk.gray(pn.id)}`);
+            if (i < phoneNumbers.length - 1) console.log('');
+          });
+        }
+        break;
+      }
+
+      // ===========================================================================
+      // INBOUND CALL COMMANDS (Lux-managed)
+      // ===========================================================================
+
+      case 'twilio-numbers': {
+        info('Loading Twilio credentials...');
+        const twilioCreds = await getTwilioCredentials();
+
+        if (!twilioCreds) {
+          error(
+            'Twilio credentials not configured.\n\n' +
+            'Add your Twilio Account SID and Auth Token in Lux Studio:\n' +
+            '  Settings → Credentials → Add Twilio Credentials'
+          );
+        }
+
+        info('Loading Twilio phone numbers...');
+        const twilioNumbers = await listTwilioPhoneNumbers(twilioCreds);
+
+        if (twilioNumbers.length === 0) {
+          console.log('\n(No phone numbers found in your Twilio account)\n');
+        } else {
+          console.log(`\n${chalk.bold('Twilio Phone Numbers')} (${twilioNumbers.length})\n`);
+          twilioNumbers.forEach((n, i) => {
+            const status = n.isLuxManaged
+              ? chalk.green('Lux-managed')
+              : n.voiceUrl
+                ? chalk.yellow('External webhook')
+                : chalk.gray('Not configured');
+            console.log(`  ${chalk.cyan(n.phoneNumber)}  ${status}`);
+            if (n.friendlyName && n.friendlyName !== n.phoneNumber) {
+              console.log(`    Name: ${n.friendlyName}`);
+            }
+            if (n.inboundConfig) {
+              console.log(`    Flow: ${n.inboundConfig.flowId}`);
+            }
+            console.log(`    SID: ${chalk.gray(n.sid)}`);
+            if (i < twilioNumbers.length - 1) console.log('');
+          });
+        }
+        break;
+      }
+
+      case 'configure-inbound': {
+        requireArgs(args.slice(1), 2, 'lux voice-agents configure-inbound <phone-number> <flow-id>');
+        const phoneNumber = args[1];
+        const flowId = args[2];
+
+        info('Loading Twilio credentials...');
+        const twilioCreds = await getTwilioCredentials();
+
+        if (!twilioCreds) {
+          error(
+            'Twilio credentials not configured.\n\n' +
+            'Add your Twilio Account SID and Auth Token in Lux Studio:\n' +
+            '  Settings → Credentials → Add Twilio Credentials'
+          );
+        }
+
+        info(`Configuring ${phoneNumber} for flow ${flowId}...`);
+        const result = await configureTwilioInbound(twilioCreds, phoneNumber, flowId);
+
+        success('Phone number configured for Lux-managed inbound calls!');
+        console.log(`\n  Phone Number: ${phoneNumber}`);
+        console.log(`  Flow ID: ${flowId}`);
+        console.log(`  Webhook URL: ${result.webhookUrl}`);
+        console.log('');
+        break;
+      }
+
+      case 'inbound-status': {
+        requireArgs(args.slice(1), 1, 'lux voice-agents inbound-status <phone-number>');
+        const phoneNumber = args[1];
+
+        info('Loading Twilio credentials...');
+        const twilioCreds = await getTwilioCredentials();
+
+        if (!twilioCreds) {
+          error(
+            'Twilio credentials not configured.\n\n' +
+            'Add your Twilio Account SID and Auth Token in Lux Studio:\n' +
+            '  Settings → Credentials → Add Twilio Credentials'
+          );
+        }
+
+        info(`Checking status for ${phoneNumber}...`);
+        const numbers = await listTwilioPhoneNumbers(twilioCreds);
+        const target = numbers.find(n => n.phoneNumber === phoneNumber);
+
+        if (!target) {
+          error(`Phone number ${phoneNumber} not found in your Twilio account`);
+        }
+
+        console.log(`\n📞 Inbound Status for ${phoneNumber}\n`);
+        console.log(`  SID: ${target.sid}`);
+        console.log(`  Friendly Name: ${target.friendlyName}`);
+        console.log(`  Voice URL: ${target.voiceUrl || '(not configured)'}`);
+        console.log(`  Lux-managed: ${target.isLuxManaged ? 'Yes' : 'No'}`);
+
+        if (target.inboundConfig) {
+          console.log(`\n  Cached Config:`);
+          console.log(`    Flow ID: ${target.inboundConfig.flowId}`);
+          console.log(`    Webhook URL: ${target.inboundConfig.webhookUrl}`);
+          console.log(`    Configured At: ${target.inboundConfig.configuredAt}`);
+        }
+        console.log('');
+        break;
+      }
+
+      case 'reset-inbound': {
+        requireArgs(args.slice(1), 1, 'lux voice-agents reset-inbound <phone-number>');
+        const phoneNumber = args[1];
+
+        info('Loading Twilio credentials...');
+        const twilioCreds = await getTwilioCredentials();
+
+        if (!twilioCreds) {
+          error(
+            'Twilio credentials not configured.\n\n' +
+            'Add your Twilio Account SID and Auth Token in Lux Studio:\n' +
+            '  Settings → Credentials → Add Twilio Credentials'
+          );
+        }
+
+        info(`Resetting configuration for ${phoneNumber}...`);
+        await resetTwilioInbound(twilioCreds, phoneNumber);
+
+        success('Phone number configuration reset!');
+        console.log(`\n  Phone Number: ${phoneNumber}`);
+        console.log('  Voice URL has been cleared.');
+        console.log('');
+        break;
+      }
+
+      // ===========================================================================
+      // UTILITY COMMANDS
+      // ===========================================================================
+
+      case 'status': {
+        console.log(`\n${chalk.bold('Voice Agent Prerequisites Status')}\n`);
+
+        // Check ElevenLabs/Voice Agent credentials
+        const elevenLabsOk = !!apiKey;
+        console.log(`ElevenLabs API:     ${elevenLabsOk ? chalk.green('✓ configured') : chalk.red('✗ not configured')}`);
+
+        // Check Twilio credentials
+        let twilioOk = false;
+        let twilioNumbers = [];
+        try {
+          const twilioCreds = await getTwilioCredentials();
+          twilioOk = !!twilioCreds;
+          if (twilioOk) {
+            twilioNumbers = await listTwilioPhoneNumbers(twilioCreds);
+          }
+        } catch {
+          twilioOk = false;
+        }
+        console.log(`Twilio API:         ${twilioOk ? chalk.green('✓ configured') : chalk.red('✗ not configured')}`);
+
+        // Check phone numbers
+        let importedNumbers = [];
+        if (elevenLabsOk) {
+          try {
+            importedNumbers = await listPhoneNumbers(apiKey);
+          } catch {
+            // Ignore errors
+          }
+        }
+
+        const totalPhones = Math.max(twilioNumbers.length, importedNumbers.length);
+        console.log(`Phone Numbers:      ${totalPhones > 0 ? chalk.green(`✓ ${totalPhones} available`) : chalk.yellow('⚠ none available')}`);
+
+        // Summary and next steps
+        console.log('');
+
+        if (!elevenLabsOk) {
+          console.log(chalk.yellow('⚠ Voice agent credentials not available.'));
+          console.log('  Voice agents may not be enabled for this project.');
+          console.log('');
+        }
+
+        if (!twilioOk) {
+          console.log(chalk.yellow('⚠ Twilio not configured - inbound calls will not work.'));
+          console.log('  Add credentials in: Settings → Credentials → Twilio');
+          console.log('');
+        }
+
+        if (totalPhones === 0 && twilioOk) {
+          console.log(chalk.yellow('⚠ No phone numbers available.'));
+          console.log('  Import a Twilio number in the Voice Agents panel.');
+          console.log('');
+        }
+
+        // Ready status
+        const outboundReady = elevenLabsOk && totalPhones > 0;
+        const inboundReady = elevenLabsOk && twilioOk && totalPhones > 0;
+
+        console.log(chalk.bold('Capabilities:'));
+        console.log(`  Outbound calls:   ${outboundReady ? chalk.green('✓ ready') : chalk.red('✗ not ready')}`);
+        console.log(`  Inbound calls:    ${inboundReady ? chalk.green('✓ ready') : chalk.red('✗ not ready')}`);
+        console.log('');
+
+        break;
+      }
+
+      case 'cache': {
+        const cache = readCache();
+        const cachePath = getCachePath();
+
+        console.log(`\n📁 Cache Location: ${cachePath || '(not available)'}\n`);
+
+        if (cache.lastUpdated) {
+          console.log(`Last Updated: ${cache.lastUpdated}\n`);
+          console.log(`Agents: ${cache.agents?.length || 0}`);
+          console.log(`Phone Numbers: ${cache.phoneNumbers?.length || 0}`);
+          console.log(`Inbound Configs: ${Object.keys(cache.inboundConfig || {}).length}`);
+
+          if (cache.agents?.length > 0) {
+            console.log(`\nAgents:`);
+            cache.agents.forEach(a => {
+              console.log(`  - ${a.name} (${a.id})`);
+            });
+          }
+
+          if (cache.phoneNumbers?.length > 0) {
+            console.log(`\nPhone Numbers:`);
+            cache.phoneNumbers.forEach(p => {
+              console.log(`  - ${p.phoneNumber} (${p.id})`);
+            });
+          }
+
+          if (cache.inboundConfig && Object.keys(cache.inboundConfig).length > 0) {
+            console.log(`\nInbound Configs (Lux-managed):`);
+            Object.entries(cache.inboundConfig).forEach(([phone, config]) => {
+              console.log(`  - ${phone}`);
+              console.log(`      Flow: ${config.flowId}`);
+              console.log(`      Configured: ${config.configuredAt}`);
+            });
+          }
+        } else {
+          console.log('Cache is empty. Run "lux voice-agents list" to populate.');
+        }
+        console.log('');
+        break;
+      }
+
+      default:
+        error(
+          `Unknown command: ${command}\n\nRun 'lux voice-agents' to see available commands`
+        );
+    }
+  } catch (err) {
+    const errorMessage =
+      err.response?.data?.detail?.message ||
+      err.response?.data?.detail ||
+      err.response?.data?.error ||
+      err.message ||
+      'Unknown error';
+    error(`${errorMessage}`);
+  }
+}
+
+/**
+ * Parse command line options (--key value format)
+ */
+function parseOptions(args) {
+  const options = {};
+  let i = 0;
+
+  while (i < args.length) {
+    const arg = args[i];
+
+    if (arg.startsWith('--')) {
+      const key = arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      const value = args[i + 1];
+
+      if (value && !value.startsWith('--')) {
+        options[key] = value;
+        i += 2;
+      } else {
+        options[key] = true;
+        i += 1;
+      }
+    } else {
+      i += 1;
+    }
+  }
+
+  return options;
+}
+
+module.exports = { handleVoiceAgents };