helix-assistant-cli 0.0.0-stage → 0.2.1

package/bin/helix.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+require('../dist/index.js');

package/dist/client/agent-client.d.ts

@@ -0,0 +1,60 @@
+import { EventEmitter } from 'events';
+import type { HelixSettings, McpServerConfig, ModelSummary, ProviderSummary, SkillSummary, TaskSummary } from './types';
+export interface AgentClientOptions {
+    wsUrl?: string;
+    wsToken?: string;
+    autoReconnect?: boolean;
+    reconnectIntervalMs?: number;
+}
+export declare class AgentClient extends EventEmitter {
+    private ws;
+    private wsUrl;
+    private wsToken?;
+    private autoReconnect;
+    private reconnectIntervalMs;
+    private reconnecting;
+    private isExplicitlyClosed;
+    private pendingRequests;
+    private requestTimeouts;
+    private isConnected;
+    constructor(options?: AgentClientOptions);
+    get connected(): boolean;
+    get url(): string;
+    private failedAttempts;
+    private autoSpawnAttempted;
+    private _isAgentStarting;
+    get isStarting(): boolean;
+    connect(): Promise<void>;
+    private _scheduleReconnect;
+    private _handleMessage;
+    request<T = unknown>(type: string, payload?: unknown, timeoutMs?: number): Promise<T>;
+    send(type: string, payload?: unknown): boolean;
+    sendUserText(text: string, conversationId: string, history?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>, attachments?: Array<{
+        name: string;
+        mime_type: string;
+        size?: number;
+        data_base64: string;
+    }>): boolean;
+    getTasks(): Promise<TaskSummary[]>;
+    getProviders(): Promise<ProviderSummary[]>;
+    getModels(requirements?: Record<string, unknown>): Promise<ModelSummary[]>;
+    getSettings(): Promise<HelixSettings>;
+    saveSettings(settings: Partial<HelixSettings>): Promise<HelixSettings>;
+    validateKey(provider: string, slot: number, key: string): Promise<string>;
+    getSkills(): Promise<SkillSummary[]>;
+    saveSkill(skill: Record<string, unknown>): Promise<SkillSummary>;
+    deleteSkill(name: string): Promise<{
+        deleted: boolean;
+    }>;
+    getMcpServers(): Promise<McpServerConfig[]>;
+    getMemoryStatus(): Promise<Record<string, unknown>>;
+    clearMemory(): Promise<void>;
+    cancelTask(taskId: string): void;
+    emergencyStop(): void;
+    confirmAction(requestId: string): void;
+    rejectAction(requestId: string): void;
+    close(): void;
+}

package/dist/client/agent-client.js

@@ -0,0 +1,322 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentClient = void 0;
+const ws_1 = __importDefault(require("ws"));
+const events_1 = require("events");
+class AgentClient extends events_1.EventEmitter {
+    ws = null;
+    wsUrl;
+    wsToken;
+    autoReconnect;
+    reconnectIntervalMs;
+    reconnecting = false;
+    isExplicitlyClosed = false;
+    pendingRequests = new Map();
+    requestTimeouts = new Map();
+    isConnected = false;
+    constructor(options = {}) {
+        super();
+        const { getOrGenerateWsToken } = require('./agent-launcher');
+        this.wsUrl = options.wsUrl || 'ws://127.0.0.1:8765';
+        this.wsToken = options.wsToken || getOrGenerateWsToken();
+        this.autoReconnect = options.autoReconnect ?? true;
+        this.reconnectIntervalMs = options.reconnectIntervalMs ?? 3000;
+    }
+    get connected() {
+        return this.isConnected && this.ws !== null && this.ws.readyState === ws_1.default.OPEN;
+    }
+    get url() {
+        return this.wsUrl;
+    }
+    failedAttempts = 0;
+    autoSpawnAttempted = false;
+    _isAgentStarting = false;
+    get isStarting() {
+        return this._isAgentStarting;
+    }
+    connect() {
+        this.isExplicitlyClosed = false;
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            try {
+                const headers = {};
+                if (this.wsToken) {
+                    headers['Authorization'] = `Bearer ${this.wsToken}`;
+                }
+                const ws = new ws_1.default(this.wsUrl, { headers });
+                this.ws = ws;
+                ws.on('open', () => {
+                    this.isConnected = true;
+                    this.reconnecting = false;
+                    settled = true;
+                    this.emit('connected', this.wsUrl);
+                    resolve();
+                });
+                ws.on('message', (data) => {
+                    try {
+                        const raw = data.toString();
+                        const message = JSON.parse(raw);
+                        this._handleMessage(message);
+                    }
+                    catch (err) {
+                        this.emit('parse_error', err);
+                    }
+                });
+                ws.on('error', (err) => {
+                    this.emit('client_error', err);
+                    if (!settled) {
+                        settled = true;
+                        reject(err);
+                    }
+                });
+                ws.on('close', (code, reason) => {
+                    this.isConnected = false;
+                    if (this.ws === ws) {
+                        this.ws = null;
+                    }
+                    if (!this._isAgentStarting) {
+                        this.emit('disconnected', { code, reason: reason.toString() });
+                    }
+                    if (!this.isExplicitlyClosed && this.autoReconnect && !this._isAgentStarting) {
+                        this._scheduleReconnect();
+                    }
+                    if (!settled) {
+                        settled = true;
+                        reject(new Error(`WebSocket closed prematurely (${code}): ${reason.toString()}`));
+                    }
+                });
+            }
+            catch (err) {
+                if (!settled) {
+                    settled = true;
+                    reject(err);
+                }
+            }
+        });
+    }
+    _scheduleReconnect() {
+        if (this.reconnecting || this.isExplicitlyClosed || this._isAgentStarting)
+            return;
+        this.reconnecting = true;
+        this.failedAttempts++;
+        // If 3 consecutive failures occur, try to auto-launch the local Python agent
+        if (this.failedAttempts >= 3 && !this.autoSpawnAttempted) {
+            this.autoSpawnAttempted = true;
+            this._isAgentStarting = true;
+            this.emit('auto_spawning_agent');
+            (async () => {
+                try {
+                    const { spawnAgentDaemon, waitForAgentReady, getOrGenerateWsToken } = require('./agent-launcher');
+                    const token = getOrGenerateWsToken();
+                    if (!this.wsToken) {
+                        this.wsToken = token;
+                    }
+                    const spawnResult = await spawnAgentDaemon();
+                    if (!spawnResult.success) {
+                        this._isAgentStarting = false;
+                        this.reconnecting = false;
+                        this.emit('agent_start_failed', { error: spawnResult.error });
+                        return;
+                    }
+                    // Lock retries: poll quietly until background service finishes starting up AND auth succeeds
+                    const ready = await waitForAgentReady(8765, this.wsToken, 45000, 1000, (elapsedSec) => {
+                        this.emit('agent_starting_progress', { elapsedSec });
+                    });
+                    this._isAgentStarting = false;
+                    if (ready) {
+                        this.failedAttempts = 0;
+                        this.autoSpawnAttempted = false;
+                        this.reconnecting = false;
+                        this.emit('agent_ready');
+                        try {
+                            await this.connect();
+                        }
+                        catch {
+                            this._scheduleReconnect();
+                        }
+                    }
+                    else {
+                        this.reconnecting = false;
+                        this.emit('agent_start_failed', {
+                            error: 'El servicio del agente no respondió en el puerto 8765 dentro de 45s.',
+                        });
+                        if (!this.isExplicitlyClosed && this.autoReconnect) {
+                            this._scheduleReconnect();
+                        }
+                    }
+                }
+                catch (e) {
+                    this._isAgentStarting = false;
+                    this.reconnecting = false;
+                    this.emit('agent_start_failed', { error: e.message });
+                    if (!this.isExplicitlyClosed && this.autoReconnect) {
+                        this._scheduleReconnect();
+                    }
+                }
+            })();
+            return;
+        }
+        this.emit('reconnecting', {
+            intervalMs: this.reconnectIntervalMs,
+            attempt: this.failedAttempts,
+        });
+        setTimeout(async () => {
+            if (this.isExplicitlyClosed || this._isAgentStarting) {
+                this.reconnecting = false;
+                return;
+            }
+            try {
+                await this.connect();
+                this.failedAttempts = 0;
+                this.autoSpawnAttempted = false;
+                this.reconnecting = false;
+            }
+            catch {
+                this.reconnecting = false;
+                this._scheduleReconnect();
+            }
+        }, this.reconnectIntervalMs);
+    }
+    _handleMessage(message) {
+        // 1. Check if it's a response to a pending request
+        if (message.request_id && this.pendingRequests.has(message.request_id)) {
+            const resolver = this.pendingRequests.get(message.request_id);
+            const timeout = this.requestTimeouts.get(message.request_id);
+            if (timeout)
+                clearTimeout(timeout);
+            this.requestTimeouts.delete(message.request_id);
+            this.pendingRequests.delete(message.request_id);
+            resolver(message.payload, message.error);
+            return;
+        }
+        // 2. Emit corresponding typed events (dispatch once per type)
+        const type = message.type || 'unknown';
+        this.emit('message', message);
+        this.emit(type, message.payload);
+    }
+    request(type, payload = {}, timeoutMs = 15000) {
+        return new Promise((resolve, reject) => {
+            if (!this.connected) {
+                reject(new Error('Agent WebSocket is not connected'));
+                return;
+            }
+            const requestId = `cli_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+            const message = {
+                type,
+                payload,
+                request_id: requestId,
+                timestamp: new Date().toISOString(),
+            };
+            const timeout = setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                this.requestTimeouts.delete(requestId);
+                reject(new Error(`Agent request timeout after ${timeoutMs}ms for ${type}`));
+            }, timeoutMs);
+            this.requestTimeouts.set(requestId, timeout);
+            this.pendingRequests.set(requestId, (data, error) => {
+                if (error) {
+                    reject(new Error(error));
+                }
+                else {
+                    resolve(data);
+                }
+            });
+            this.ws?.send(JSON.stringify(message));
+        });
+    }
+    send(type, payload = {}) {
+        if (!this.connected)
+            return false;
+        const message = {
+            type,
+            payload,
+            timestamp: new Date().toISOString(),
+        };
+        try {
+            this.ws?.send(JSON.stringify(message));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // --- High level client operations ---
+    sendUserText(text, conversationId, history = [], attachments) {
+        const payload = {
+            text,
+            conversation_id: conversationId,
+            conversation_history: history,
+            attachments,
+        };
+        return this.send('USER_TEXT', payload);
+    }
+    async getTasks() {
+        return this.request('GET_TASKS', {});
+    }
+    async getProviders() {
+        return this.request('GET_PROVIDERS', {});
+    }
+    async getModels(requirements = {}) {
+        return this.request('GET_MODELS', { requirements });
+    }
+    async getSettings() {
+        return this.request('GET_SETTINGS', {});
+    }
+    async saveSettings(settings) {
+        return this.request('SAVE_SETTINGS', { settings });
+    }
+    async validateKey(provider, slot, key) {
+        return this.request('VALIDATE_KEY', { provider, slot, key });
+    }
+    async getSkills() {
+        return this.request('GET_SKILLS', {});
+    }
+    async saveSkill(skill) {
+        return this.request('SAVE_SKILL', { skill });
+    }
+    async deleteSkill(name) {
+        return this.request('DELETE_SKILL', { name });
+    }
+    async getMcpServers() {
+        return this.request('GET_MCP_SERVERS', {});
+    }
+    async getMemoryStatus() {
+        return this.request('GET_MEMORY_STATUS', {});
+    }
+    async clearMemory() {
+        return this.request('CLEAR_MEMORY', {});
+    }
+    cancelTask(taskId) {
+        this.send('TASK_CANCEL', { task_id: taskId });
+    }
+    emergencyStop() {
+        this.send('TASK_CANCEL_ALL', {});
+    }
+    confirmAction(requestId) {
+        this.send('CONFIRMATION_GRANTED', { request_id: requestId });
+    }
+    rejectAction(requestId) {
+        this.send('CONFIRMATION_REJECTED', { request_id: requestId });
+    }
+    close() {
+        this.isExplicitlyClosed = true;
+        for (const timeout of this.requestTimeouts.values()) {
+            clearTimeout(timeout);
+        }
+        this.requestTimeouts.clear();
+        for (const resolver of this.pendingRequests.values()) {
+            resolver(undefined, 'Client disconnected');
+        }
+        this.pendingRequests.clear();
+        if (this.ws) {
+            this.ws.removeAllListeners();
+            this.ws.close();
+            this.ws = null;
+        }
+        this.isConnected = false;
+    }
+}
+exports.AgentClient = AgentClient;

package/dist/client/agent-launcher.d.ts

@@ -0,0 +1,30 @@
+export declare function getTokenFilePath(): string;
+export declare function getOrGenerateWsToken(): string;
+export declare function isAgentProcessRunning(): boolean;
+export declare function isAgentStarting(): boolean;
+export declare function findPythonAgentScript(): string | null;
+export declare function findPythonExecutable(repoRoot: string): string;
+/**
+ * Probes a TCP port quietly without initiating a WebSocket handshake.
+ */
+export declare function probePort(port: number, host?: string, timeoutMs?: number): Promise<boolean>;
+/**
+ * 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 declare function probeWebSocketAuth(port?: number, token?: string, host?: string, timeoutMs?: number): Promise<'ready' | 'unauthorized' | 'closed'>;
+/**
+ * Terminates any rogue or orphaned process occupying the specified port.
+ */
+export declare function killProcessOnPort(port?: number): void;
+/**
+ * Waits until the agent service has completed startup and successfully accepts WebSocket authentication.
+ */
+export declare function waitForAgentReady(port?: number, token?: string, maxWaitMs?: number, pollIntervalMs?: number, onProgress?: (elapsedSec: number) => void): Promise<boolean>;
+export declare function spawnAgentDaemon(port?: number): Promise<{
+    success: boolean;
+    error?: string;
+}>;