helix-assistant-cli 0.0.0-stage → 0.2.1

package/src/client/agent-launcher.ts

@@ -0,0 +1,374 @@
+import { spawn, ChildProcess, execSync } from 'child_process';
+import path from 'path';
+import fs from 'fs';
+import crypto from 'crypto';
+import net from 'net';
+import WebSocket from 'ws';
+
+let spawnedAgentProcess: ChildProcess | null = null;
+let activeSpawnToken: string | null = null;
+let startupPromise: Promise<boolean> | null = null;
+
+export function getTokenFilePath(): string {
+  const appData =
+    process.env.APPDATA ||
+    (process.platform === 'darwin'
+      ? path.join(process.env.HOME || '', 'Library/Application Support')
+      : path.join(process.env.HOME || '', '.config'));
+  const helixDir = path.join(appData, 'HELIX');
+  if (!fs.existsSync(helixDir)) {
+    try {
+      fs.mkdirSync(helixDir, { recursive: true });
+    } catch {}
+  }
+  return path.join(helixDir, '.ws_token');
+}
+
+export function getOrGenerateWsToken(): string {
+  if (activeSpawnToken) return activeSpawnToken;
+  if (process.env.HELIX_WS_TOKEN) {
+    activeSpawnToken = process.env.HELIX_WS_TOKEN;
+    return activeSpawnToken;
+  }
+
+  const tokenFile = getTokenFilePath();
+  if (fs.existsSync(tokenFile)) {
+    try {
+      const saved = fs.readFileSync(tokenFile, 'utf-8').trim();
+      if (saved.length >= 16) {
+        activeSpawnToken = saved;
+        process.env.HELIX_WS_TOKEN = activeSpawnToken;
+        return activeSpawnToken;
+      }
+    } catch {}
+  }
+
+  activeSpawnToken = crypto.randomBytes(32).toString('hex');
+  process.env.HELIX_WS_TOKEN = activeSpawnToken;
+  try {
+    fs.writeFileSync(tokenFile, activeSpawnToken, { encoding: 'utf-8', mode: 0o600 });
+  } catch {}
+  return activeSpawnToken;
+}
+
+export function isAgentProcessRunning(): boolean {
+  return spawnedAgentProcess !== null && !spawnedAgentProcess.killed;
+}
+
+export function isAgentStarting(): boolean {
+  return startupPromise !== null;
+}
+
+export function findPythonAgentScript(): string | null {
+  const candidates = [
+    path.resolve(process.cwd(), 'services/agent/main.py'),
+    path.resolve(__dirname, '../../../services/agent/main.py'),
+    path.resolve(__dirname, '../../../../services/agent/main.py'),
+    path.resolve(__dirname, '../../services/agent/main.py'),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+export function findPythonExecutable(repoRoot: string): string {
+  // Check explicit environment variable first
+  if (process.env.PYTHON_PATH && fs.existsSync(process.env.PYTHON_PATH)) {
+    return process.env.PYTHON_PATH;
+  }
+
+  // On Windows, prefer pythonw.exe so NO console terminal window is opened
+  if (process.platform === 'win32') {
+    const venvGuiCandidates = [
+      path.join(repoRoot, '.venv', 'Scripts', 'pythonw.exe'),
+      path.join(repoRoot, 'venv', 'Scripts', 'pythonw.exe'),
+      path.join(repoRoot, 'services', 'agent', '.venv', 'Scripts', 'pythonw.exe'),
+    ];
+
+    for (const venvGui of venvGuiCandidates) {
+      if (fs.existsSync(venvGui)) {
+        return venvGui;
+      }
+    }
+  }
+
+  // Check virtual environment candidates relative to repository root
+  const venvCandidates = [
+    path.join(repoRoot, '.venv', 'Scripts', 'python.exe'),
+    path.join(repoRoot, '.venv', 'bin', 'python'),
+    path.join(repoRoot, 'venv', 'Scripts', 'python.exe'),
+    path.join(repoRoot, 'venv', 'bin', 'python'),
+    path.join(repoRoot, 'services', 'agent', '.venv', 'Scripts', 'python.exe'),
+    path.join(repoRoot, 'services', 'agent', '.venv', 'bin', 'python'),
+  ];
+
+  for (const venvPython of venvCandidates) {
+    if (fs.existsSync(venvPython)) {
+      return venvPython;
+    }
+  }
+
+  // Fallback to system PATH executables
+  const systemCandidates = process.platform === 'win32'
+    ? ['pythonw', 'python', 'py']
+    : ['python', 'python3', 'py'];
+  return systemCandidates[0];
+}
+
+/**
+ * Probes a TCP port quietly without initiating a WebSocket handshake.
+ */
+export function probePort(port: number, host: string = '127.0.0.1', timeoutMs: number = 800): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    let settled = false;
+
+    socket.setTimeout(timeoutMs);
+
+    socket.once('connect', () => {
+      if (!settled) {
+        settled = true;
+        socket.destroy();
+        resolve(true);
+      }
+    });
+
+    socket.once('timeout', () => {
+      if (!settled) {
+        settled = true;
+        socket.destroy();
+        resolve(false);
+      }
+    });
+
+    socket.once('error', () => {
+      if (!settled) {
+        settled = true;
+        socket.destroy();
+        resolve(false);
+      }
+    });
+
+    try {
+      socket.connect(port, host);
+    } catch {
+      if (!settled) {
+        settled = true;
+        resolve(false);
+      }
+    }
+  });
+}
+
+/**
+ * Probes the WebSocket endpoint with Authorization header.
+ * Returns:
+ *   'ready': 101 Switching Protocols (authenticated and connected)
+ *   'unauthorized': 401 Unauthorized (wrong token / rogue process on port)
+ *   'closed': Connection refused / port closed
+ */
+export function probeWebSocketAuth(
+  port: number = 8765,
+  token?: string,
+  host: string = '127.0.0.1',
+  timeoutMs: number = 1000
+): Promise<'ready' | 'unauthorized' | 'closed'> {
+  return new Promise((resolve) => {
+    let settled = false;
+    let timer: NodeJS.Timeout | null = null;
+
+    const headers: Record<string, string> = {};
+    const effectiveToken = token || getOrGenerateWsToken();
+    if (effectiveToken) {
+      headers['Authorization'] = `Bearer ${effectiveToken}`;
+    }
+
+    let ws: WebSocket | null = null;
+    try {
+      ws = new WebSocket(`ws://${host}:${port}`, { headers });
+    } catch {
+      return resolve('closed');
+    }
+
+    const cleanup = () => {
+      if (timer) clearTimeout(timer);
+      if (ws) {
+        ws.removeAllListeners();
+        ws.on('error', () => {});
+        try {
+          if (ws.readyState === WebSocket.OPEN) {
+            ws.close();
+          } else {
+            ws.terminate();
+          }
+        } catch {}
+      }
+    };
+
+    timer = setTimeout(() => {
+      if (!settled) {
+        settled = true;
+        cleanup();
+        resolve('closed');
+      }
+    }, timeoutMs);
+
+    ws.once('open', () => {
+      if (!settled) {
+        settled = true;
+        cleanup();
+        resolve('ready');
+      }
+    });
+
+    ws.once('error', (err: Error) => {
+      if (!settled) {
+        settled = true;
+        const msg = err.message || '';
+        cleanup();
+        if (msg.includes('401') || msg.includes('Unexpected server response: 401')) {
+          resolve('unauthorized');
+        } else {
+          resolve('closed');
+        }
+      }
+    });
+  });
+}
+
+/**
+ * Terminates any rogue or orphaned process occupying the specified port.
+ */
+export function killProcessOnPort(port: number = 8765): void {
+  try {
+    if (process.platform === 'win32') {
+      execSync(
+        `powershell -NoProfile -Command "$conn = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue; if ($conn) { Stop-Process -Id $conn.OwningProcess -Force -ErrorAction SilentlyContinue }"`,
+        { stdio: 'ignore', windowsHide: true }
+      );
+    } else {
+      execSync(`fuser -k ${port}/tcp || lsof -ti tcp:${port} | xargs kill -9`, {
+        stdio: 'ignore',
+      });
+    }
+  } catch {
+    // Ignore errors
+  }
+}
+
+/**
+ * Waits until the agent service has completed startup and successfully accepts WebSocket authentication.
+ */
+export async function waitForAgentReady(
+  port: number = 8765,
+  token?: string,
+  maxWaitMs: number = 45000,
+  pollIntervalMs: number = 1000,
+  onProgress?: (elapsedSec: number) => void
+): Promise<boolean> {
+  if (startupPromise) {
+    return startupPromise;
+  }
+
+  startupPromise = (async () => {
+    const startTime = Date.now();
+    try {
+      while (Date.now() - startTime < maxWaitMs) {
+        // If the spawned child process exited prematurely with an error code, abort
+        if (spawnedAgentProcess !== null && spawnedAgentProcess.exitCode !== null) {
+          return false;
+        }
+
+        const authState = await probeWebSocketAuth(port, token);
+        if (authState === 'ready') {
+          return true;
+        }
+
+        const elapsedSec = Math.floor((Date.now() - startTime) / 1000);
+        if (onProgress) {
+          onProgress(elapsedSec);
+        }
+
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      }
+      return false;
+    } finally {
+      startupPromise = null;
+    }
+  })();
+
+  return startupPromise;
+}
+
+export async function spawnAgentDaemon(port: number = 8765): Promise<{ success: boolean; error?: string }> {
+  const token = getOrGenerateWsToken();
+
+  // 1. Check if the agent is already up and authenticated
+  const currentStatus = await probeWebSocketAuth(port, token, '127.0.0.1', 500);
+  if (currentStatus === 'ready') {
+    return { success: true };
+  }
+
+  // 2. If port is occupied by an unauthorized process, clean it up
+  if (currentStatus === 'unauthorized') {
+    killProcessOnPort(port);
+    await new Promise((resolve) => setTimeout(resolve, 500));
+  }
+
+  if (isAgentProcessRunning() || isAgentStarting()) {
+    return { success: true };
+  }
+
+  const scriptPath = findPythonAgentScript();
+  if (!scriptPath) {
+    return {
+      success: false,
+      error: 'No se encontró el script services/agent/main.py del agente Python.',
+    };
+  }
+
+  const agentDir = path.dirname(scriptPath);
+  const repoRoot = path.resolve(agentDir, '../..');
+  const pythonExec = findPythonExecutable(repoRoot);
+
+  try {
+    const child = spawn(
+      pythonExec,
+      ['main.py', '--ws-port', String(port), '--no-camera'],
+      {
+        cwd: agentDir,
+        detached: true,
+        stdio: 'ignore', // run completely in background
+        windowsHide: true,
+        env: {
+          ...process.env,
+          HELIX_WS_TOKEN: token,
+          HELIX_DISABLE_CAMERA: '1',
+          CAMERA_ENABLED: 'false',
+          PYTHONUNBUFFERED: '1',
+          PYTHONIOENCODING: 'utf-8',
+          PYTHONPATH: repoRoot,
+        },
+      }
+    );
+
+    child.unref();
+    spawnedAgentProcess = child;
+
+    child.on('exit', () => {
+      spawnedAgentProcess = null;
+    });
+
+    return { success: true };
+  } catch (err) {
+    return {
+      success: false,
+      error: `Error al invocar proceso Python: ${(err as Error).message}`,
+    };
+  }
+}
+

package/src/client/types.ts

@@ -0,0 +1,95 @@
+export interface AgentMessage<T = unknown> {
+  type: string;
+  payload: T;
+  timestamp?: string;
+  request_id?: string;
+  error?: string;
+}
+
+export interface UserTextMessagePayload {
+  text: string;
+  conversation_id: string;
+  conversation_history: Array<{ role: 'user' | 'assistant'; content: string }>;
+  attachments?: Array<{
+    name: string;
+    mime_type: string;
+    size?: number;
+    data_base64: string;
+  }>;
+}
+
+export interface SkillSummary {
+  name: string;
+  description: string;
+  triggers?: string[];
+  instructions?: string;
+  custom?: boolean;
+}
+
+export interface McpToolSummary {
+  name: string;
+  description?: string;
+  parameters?: Record<string, unknown>;
+}
+
+export interface McpServerConfig {
+  name: string;
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+  status?: 'connected' | 'idle' | 'connecting' | 'error';
+  error?: string;
+  tools?: McpToolSummary[];
+}
+
+export interface ProviderKeySlot {
+  slot: number;
+  health: 'healthy' | 'degraded' | 'cooldown' | 'unconfigured' | 'error';
+  configured: boolean;
+  masked?: string;
+}
+
+export interface ProviderSummary {
+  id: string;
+  name: string;
+  configured: boolean;
+  keys: ProviderKeySlot[];
+  models_available: number;
+}
+
+export interface ModelSummary {
+  id: string;
+  name?: string;
+  provider: string;
+  capabilities?: Record<string, boolean>;
+}
+
+export interface TaskSummary {
+  task_id: string;
+  prompt?: string;
+  status: 'PENDING' | 'RUNNING' | 'COMPLETED' | 'FAILED' | 'CANCELLED';
+  created_at?: string;
+  result?: string;
+  error?: string;
+}
+
+export interface HelixSettings {
+  voice_enabled?: boolean;
+  wake_word?: string;
+  mcp_servers?: McpServerConfig[];
+  default_model?: string | null;
+  preferred_provider?: string | null;
+  log_level?: string;
+  agent_ws_port?: number;
+  [key: string]: unknown;
+}
+
+export interface ConfirmationRequest {
+  id?: string;
+  request_id?: string;
+  action?: string;
+  description?: string;
+  risk_level?: 'LOW' | 'MEDIUM' | 'HIGH';
+  tool?: string;
+  arguments?: Record<string, unknown>;
+}

package/src/commands/apikey.ts

@@ -0,0 +1,129 @@
+import prompts from 'prompts';
+import chalk from 'chalk';
+import type { AgentClient } from '../client/agent-client';
+import { CYAN, GREEN, RED, YELLOW, GRAY, BOLD, DIM } from '../ui/colors';
+
+const KNOWN_PROVIDERS = [
+  { title: 'OpenAI (GPT-4o, o1, o3-mini)', value: 'openai' },
+  { title: 'Anthropic (Claude 3.5 Sonnet, Claude 3.7)', value: 'anthropic' },
+  { title: 'Google (Gemini 2.0 Flash / Pro)', value: 'google' },
+  { title: 'Groq (Llama 3.3, DeepSeek R1)', value: 'groq' },
+  { title: 'Mistral AI (Mistral Large, Codestral)', value: 'mistral' },
+  { title: 'Ollama / Local Custom Provider', value: 'ollama' },
+];
+
+export async function handleShowApiKey(client: AgentClient): Promise<void> {
+  console.log(`\n${BOLD('🔑 Configuración Actual de API Keys:')}\n`);
+
+  try {
+    const providers = await client.getProviders();
+    if (!providers || providers.length === 0) {
+      console.log(GRAY('  No se encontraron proveedores registrados en el agente.\n'));
+      return;
+    }
+
+    for (const provider of providers) {
+      const statusIcon = provider.configured ? GREEN('●') : GRAY('○');
+      const providerTitle = provider.configured
+        ? chalk.greenBright.bold(provider.name || provider.id)
+        : chalk.gray(provider.name || provider.id);
+
+      console.log(`  ${statusIcon} ${providerTitle} ${DIM(`(${provider.models_available || 0} modelos disponibles)`)}`);
+
+      if (provider.keys && provider.keys.length > 0) {
+        for (const slot of provider.keys) {
+          let healthBadge: string;
+          switch (slot.health) {
+            case 'healthy':
+              healthBadge = chalk.green('✔ Válida / Activa');
+              break;
+            case 'degraded':
+              healthBadge = chalk.yellow('⚠ Degradada');
+              break;
+            case 'cooldown':
+              healthBadge = chalk.red('⏳ Cooldown');
+              break;
+            case 'unconfigured':
+              healthBadge = chalk.gray('○ No configurada');
+              break;
+            default:
+              healthBadge = chalk.gray(slot.health);
+          }
+
+          const maskedText = slot.configured ? chalk.cyan('••••••••••••••••') : chalk.gray('vacío');
+          console.log(`     ${GRAY('Slot ' + slot.slot + ':')} ${maskedText}  [${healthBadge}]`);
+        }
+      } else {
+        console.log(`     ${GRAY('Sin slots de claves registrados')}`);
+      }
+      console.log('');
+    }
+  } catch (error) {
+    console.log(RED(`  Error al consultar API keys del agente: ${(error as Error).message}\n`));
+  }
+}
+
+export async function handleConfigApiKey(client: AgentClient): Promise<void> {
+  console.log(`\n${BOLD('⚙️  Configurador Interactivo de API Keys')}\n`);
+
+  // 1. Select Provider
+  const providerAnswer = await prompts({
+    type: 'select',
+    name: 'provider',
+    message: 'Selecciona el proveedor de IA para configurar:',
+    choices: KNOWN_PROVIDERS,
+  });
+
+  const providerId = providerAnswer.provider as string | undefined;
+  if (!providerId) {
+    console.log(YELLOW('Operación cancelada.\n'));
+    return;
+  }
+
+  // 2. Select Slot
+  const slotAnswer = await prompts({
+    type: 'select',
+    name: 'slot',
+    message: `Selecciona el Slot para ${providerId.toUpperCase()}:`,
+    choices: [
+      { title: 'Slot 1 (Principal)', value: 1 },
+      { title: 'Slot 2 (Respaldo)', value: 2 },
+      { title: 'Slot 3 (Rotación)', value: 3 },
+      { title: 'Añadir nuevo Slot', value: 4 },
+    ],
+  });
+
+  const slotNumber = slotAnswer.slot as number | undefined;
+  if (!slotNumber) {
+    console.log(YELLOW('Operación cancelada.\n'));
+    return;
+  }
+
+  // 3. Prompt for API Key
+  const keyAnswer = await prompts({
+    type: 'password',
+    name: 'apiKey',
+    message: `Introduce la API Key para ${providerId.toUpperCase()} (Slot ${slotNumber}):`,
+    validate: (val: string) => (val && val.trim().length > 0 ? true : 'La API Key no puede estar vacía'),
+  });
+
+  const apiKey = (keyAnswer.apiKey as string | undefined)?.trim();
+  if (!apiKey) {
+    console.log(YELLOW('Operación cancelada.\n'));
+    return;
+  }
+
+  console.log(CYAN(`\n  Validando clave con ${providerId}...`));
+
+  try {
+    const health = await client.validateKey(providerId, slotNumber, apiKey);
+    if (health === 'healthy') {
+      console.log(GREEN(`\n  ✔ ¡API Key validada y guardada con éxito en el almacén seguro!`));
+      console.log(DIM(`  Proveedor: ${providerId} | Slot: ${slotNumber} | Estado: healthy\n`));
+    } else {
+      console.log(YELLOW(`\n  ⚠ La clave fue procesada pero su estado es: ${health}\n`));
+    }
+  } catch (err) {
+    console.log(RED(`\n  ✖ Error al validar la API Key: ${(err as Error).message}\n`));
+  }
+}

package/src/commands/browser.ts

@@ -0,0 +1,39 @@
+import chalk from 'chalk';
+import type { AgentClient } from '../client/agent-client';
+import { CYAN, GREEN, RED, YELLOW, GRAY, BOLD, DIM } from '../ui/colors';
+
+export async function handleBrowserCommand(
+  client: AgentClient,
+  args?: string
+): Promise<void> {
+  const parts = args ? args.trim().split(/\s+/) : [];
+  const subCommand = parts[0]?.toLowerCase();
+  const targetUrl = parts[1];
+
+  if (subCommand === 'open' && targetUrl) {
+    console.log(CYAN(`\n  Solicitando al agente abrir en navegador: ${targetUrl}...`));
+    client.sendUserText(
+      `Por favor abre la siguiente URL en el navegador: ${targetUrl}`,
+      `browser_${Date.now()}`
+    );
+    console.log(GREEN(`  ✔ Comando enviado al agente.\n`));
+    return;
+  }
+
+  try {
+    const settings = await client.getSettings();
+    const engine = (settings.browser_engine as string) || 'chromium';
+    const headless = settings.browser_headless !== false;
+
+    console.log(`\n${BOLD('🌐 Estado de Navegación y Browser Bridge:')}\n`);
+    console.log(`  Motor:       ${CYAN(engine.toUpperCase())}`);
+    console.log(`  Modo:        ${headless ? chalk.yellow('Headless') : chalk.green('Ventana Visible')}`);
+    console.log(`  Descargas:   ${settings.block_downloads ? RED('Bloqueadas') : GREEN('Permitidas')}`);
+    console.log(`  Dominios:    ${settings.block_untrusted_domains ? YELLOW('Filtrado Estricto') : GRAY('Abierto')}`);
+    console.log(`\n  ${DIM('Comandos disponibles:')}`);
+    console.log(`    ${CYAN('/browser')}              ${DIM('- Ver estado de navegación')}`);
+    console.log(`    ${CYAN('/browser open <url>')}   ${DIM('- Abrir URL con el agente')}\n`);
+  } catch (err) {
+    console.log(RED(`  Error al consultar estado del navegador: ${(err as Error).message}\n`));
+  }
+}