@hailer/mcp 1.1.11 → 1.1.13

package/dist/mcp/hailer-clients.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.subscribeToSignal = exports.clearAllConnections = exports.disconnectHailerClientByApiKey = exports.createHailerClientByApiKey = exports.HailerClientManager = void 0;
+exports.subscribeToSignal = exports.clearAllConnections = exports.disconnectHailerClientByApiKey = exports.createHailerClientByApiKey = exports.HailerClientManager = exports.RestOnlySocket = void 0;
 exports.getCurrentUserId = getCurrentUserId;
 exports.registerBotCredentials = registerBotCredentials;
 exports.unregisterBotCredentials = unregisterBotCredentials;
@@ -9,6 +9,70 @@ const auth_1 = require("./auth");
 const logger_1 = require("../lib/logger");
 const config_1 = require("../config");
 const logger = (0, logger_1.createLogger)({ component: 'hailer-clients' });
+// Default API base URL for OAuth sessions (User API Keys)
+const DEFAULT_API_BASE_URL = process.env.BOT_API_BASE_URL || 'https://api.hailer.com';
+/**
+ * REST-only socket mock for User API Key sessions
+ * User API Keys require IP for validation, which socket.resume() doesn't provide.
+ * This mock implements the socket.request() interface using REST API calls.
+ */
+class RestOnlySocket {
+    host;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.host = baseUrl;
+        this.apiKey = apiKey;
+    }
+    /**
+     * Make RPC request via REST API instead of socket
+     * Hailer's /api endpoint accepts the same RPC format as socket
+     */
+    async request(method, args = []) {
+        const url = `${this.host}/api/${method.replace(/\./g, '/')}`;
+        logger.debug('RestOnlySocket making request', {
+            url,
+            method,
+            apiKeyPrefix: this.apiKey.substring(0, 20) + '...',
+        });
+        const response = await (0, auth_1.safeFetch)(url, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'hlrkey': this.apiKey,
+            },
+            body: JSON.stringify({ args }),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            logger.error('RestOnlySocket request failed', {
+                url,
+                method,
+                status: response.status,
+                errorText,
+            });
+            throw new Error(`REST API request failed: ${response.status} ${errorText}`);
+        }
+        const result = await response.json();
+        logger.debug('RestOnlySocket request succeeded', { method });
+        return result;
+    }
+    // Stub methods for socket interface compatibility
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    on(_event, _handler) {
+        // REST-only client doesn't support real-time events
+        logger.debug('RestOnlySocket.on() called - events not supported for User API Key sessions');
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    off(_event, _handler) {
+        // REST-only client doesn't support real-time events
+        logger.debug('RestOnlySocket.off() called - events not supported for User API Key sessions');
+    }
+    disconnect() {
+        // Nothing to disconnect for REST-only client
+        logger.debug('RestOnlySocket.disconnect() called - no-op for REST client');
+    }
+}
+exports.RestOnlySocket = RestOnlySocket;
 /**
  * Get the current user ID from the authenticated session
  * This is called after authentication to retrieve the user ID automatically
@@ -91,24 +155,23 @@ class HailerClientManager {
             password: this.password,
             ...(isLocalDev && { rejectUnauthorized: false }), // Add for local dev with self-signed certs
         };
-        // Track timeout with single settled flag to prevent race conditions
+        // Track timeout for proper cleanup
         let timeoutId = null;
-        let settled = false;
+        let timeoutCleared = false;
         try {
             // Create socket client using @hailer/cli with cancellable timeout
             this.socketClient = (await Promise.race([
                 cli_1.Client.create(clientOptions).then(client => {
-                    if (!settled) {
-                        settled = true;
-                        if (timeoutId)
-                            clearTimeout(timeoutId);
+                    // Clear timeout on success
+                    if (timeoutId && !timeoutCleared) {
+                        clearTimeout(timeoutId);
+                        timeoutCleared = true;
                     }
                     return client;
                 }),
                 new Promise((_, reject) => {
                     timeoutId = setTimeout(() => {
-                        if (!settled) {
-                            settled = true;
+                        if (!timeoutCleared) {
                             reject(new Error(`Timeout connecting to: ${this.host}`));
                         }
                     }, 30000);
@@ -116,10 +179,10 @@ class HailerClientManager {
             ]));
         }
         catch (error) {
-            // Ensure timeout is cleared on error
-            if (timeoutId && !settled) {
-                settled = true;
+            // Ensure timeout is cleared on error too
+            if (timeoutId && !timeoutCleared) {
                 clearTimeout(timeoutId);
+                timeoutCleared = true;
             }
             logger.error('Failed to create socket client', error, { username: this.username });
             throw error;
@@ -163,13 +226,13 @@ class HailerClientManager {
             logger.info('Socket reconnected and session resumed', { username: this.username });
         });
         this.socketClient.on("connect", () => {
-            logger.debug('Socket connected', { username: this.username });
+            logger.info('Socket connected', { username: this.username });
         });
         this.socketClient.on("connect_error", (error) => {
             logger.error('Socket connection error', { error: error.message, username: this.username });
         });
         this.socketClient.on("reconnect_attempt", (attempt) => {
-            logger.debug('Socket reconnection attempt', { attempt, username: this.username });
+            logger.info('Socket reconnection attempt', { attempt, username: this.username });
         });
         this.socketClient.on("reconnect_failed", () => {
             logger.error('Socket reconnection failed permanently', { username: this.username });
@@ -244,12 +307,86 @@ class HailerClientManager {
 exports.HailerClientManager = HailerClientManager;
 // Connection pool for the MCP server
 const connectionPool = new Map();
+// Pool for User API Key socket clients
+const userApiKeyClients = new Map();
+/**
+ * Create a REST-only client for User API Keys
+ *
+ * User API Keys require IP address for validation (see validateApiKey in backend).
+ * Socket.IO resume() doesn't pass IP, so we use REST API with hlrkey header instead.
+ * The REST API passes req.ip to core.getSession() which then validates the key.
+ */
+async function createUserApiKeyClient(userApiKey) {
+    // Check if we already have this client
+    const existing = userApiKeyClients.get(userApiKey);
+    if (existing) {
+        logger.debug('Reusing existing User API Key client', {
+            apiKey: userApiKey.substring(0, 20) + '...'
+        });
+        return existing;
+    }
+    logger.info('Creating REST-only client for User API Key', {
+        apiKey: userApiKey.substring(0, 20) + '...',
+        apiBaseUrl: DEFAULT_API_BASE_URL
+    });
+    try {
+        // Create REST-only socket mock that uses HTTP API instead of WebSocket
+        const restSocket = new RestOnlySocket(DEFAULT_API_BASE_URL, userApiKey);
+        // Verify the API key works by making a test request
+        logger.debug('Verifying User API Key via REST...');
+        const testResult = await restSocket.request('v2.core.init', [['user']]);
+        if (!testResult?.user?._id) {
+            throw new Error('User API Key validation failed - could not get user info');
+        }
+        logger.info('User API Key validated successfully via REST', {
+            apiKey: userApiKey.substring(0, 20) + '...',
+            userId: testResult.user._id
+        });
+        // Create REST client
+        const restClient = {
+            fetch: (url, options = {}) => {
+                const fullUrl = url.startsWith('http') ? url : `${DEFAULT_API_BASE_URL}${url}`;
+                const headers = {
+                    ...options.headers,
+                    hlrkey: userApiKey,
+                    'Content-Type': 'application/json',
+                };
+                return (0, auth_1.safeFetch)(fullUrl, { ...options, headers });
+            },
+            sessionKey: userApiKey,
+        };
+        const client = {
+            socket: restSocket,
+            rest: restClient,
+            sessionKey: userApiKey,
+        };
+        userApiKeyClients.set(userApiKey, client);
+        return client;
+    }
+    catch (error) {
+        const errorMsg = error instanceof Error
+            ? error.message
+            : (typeof error === 'object' && error !== null)
+                ? JSON.stringify(error)
+                : String(error);
+        logger.error('Failed to create User API Key client', {
+            error: errorMsg,
+            errorType: typeof error,
+        });
+        throw new Error(`Failed to create User API Key session: ${errorMsg}`);
+    }
+}
 /**
  * Create Hailer client by API key (O(1) lookup)
  * This is the new efficient method for MCP Server to get connections
  */
 const createHailerClientByApiKey = async (apiKey) => {
-    // O(1) lookup in Map-based CLIENT_CONFIGS
+    // Check if this is a User API Key (from OAuth flow)
+    // User API Keys start with "userapikey_" and can authenticate via socket resume()
+    if (apiKey.startsWith('userapikey_')) {
+        return await createUserApiKeyClient(apiKey);
+    }
+    // O(1) lookup in Map-based CLIENT_CONFIGS (for bot accounts)
     const account = config_1.environment.CLIENT_CONFIGS[apiKey];
     if (!account) {
         throw new Error(`No Hailer account found for API key: ${apiKey}`);
@@ -280,7 +417,7 @@ const createHailerClientByApiKey = async (apiKey) => {
         connectionPool.delete(connectionKey);
     }
     // Create new connection
-    logger.debug('Creating new connection', {
+    logger.info('Creating new connection', {
         apiKey: apiKey.substring(0, 8) + '...',
         email: (0, config_1.maskEmail)(account.email),
         host: account.apiBaseUrl
@@ -312,7 +449,7 @@ const clearAllConnections = () => {
         clientManager.disconnect();
     }
     connectionPool.clear();
-    logger.debug('Cleared Hailer connections', { count });
+    logger.info('Cleared Hailer connections', { count });
 };
 exports.clearAllConnections = clearAllConnections;
 /**
@@ -346,10 +483,10 @@ function registerBotCredentials(botId, email, password, options) {
     config_1.environment.CLIENT_CONFIGS[apiKey] = {
         email,
         password,
-        apiBaseUrl: config_1.environment.BOT_API_BASE_URL || 'https://api.hailer.com',
+        apiBaseUrl: 'https://api.hailer.com',
         ...(options?.allowedGroups && { allowedGroups: options.allowedGroups }),
     };
-    logger.debug('Bot credentials registered', {
+    logger.info('Bot credentials registered', {
         botId,
         hasAllowedGroups: !!options?.allowedGroups
     });
@@ -361,6 +498,6 @@ function registerBotCredentials(botId, email, password, options) {
 function unregisterBotCredentials(apiKey) {
     delete config_1.environment.CLIENT_CONFIGS[apiKey];
     (0, exports.disconnectHailerClientByApiKey)(apiKey);
-    logger.debug('Bot credentials unregistered');
+    logger.info('Bot credentials unregistered');
 }
 //# sourceMappingURL=hailer-clients.js.map

package/dist/mcp/session-store.d.ts

@@ -0,0 +1,68 @@
+/**
+ * SessionStore - Maps key_id to real api_key for Claude App authentication
+ *
+ * Purpose: Keep real Hailer API keys on server side, Claude only gets a reference (key_id).
+ * Multiple concurrent sessions supported - each user gets their own key_id.
+ *
+ * Flow:
+ * 1. User logs in via Hailer auth page
+ * 2. Frontend generates key_id, sends {key_id, api_key} to MCP /auth/register
+ * 3. Frontend redirects to Claude with key_id as "access_token"
+ * 4. Claude sends key_id in Authorization header
+ * 5. MCP looks up real api_key from this store
+ */
+export interface Session {
+    apiKey: string;
+    workspaceId: string;
+    createdAt: number;
+    lastAccessedAt: number;
+}
+export declare class SessionStore {
+    private store;
+    private maxTtlMs;
+    private inactivityTtlMs;
+    private cleanupInterval;
+    /**
+     * @param maxTtlHours - Maximum session lifetime in hours (default 24)
+     * @param inactivityMinutes - Session expires after this many minutes of inactivity (default 30)
+     */
+    constructor(maxTtlHours?: number, inactivityMinutes?: number);
+    /**
+     * Register a new session (called by /auth/register endpoint)
+     */
+    set(keyId: string, apiKey: string, workspaceId: string): void;
+    /**
+     * Get session by key_id (returns null if expired or not found)
+     * Updates lastAccessedAt to extend inactivity timeout
+     */
+    get(keyId: string): Session | null;
+    /**
+     * Delete session (logout)
+     */
+    delete(keyId: string): boolean;
+    /**
+     * Remove all expired sessions (both max TTL and inactivity)
+     */
+    cleanup(): void;
+    /**
+     * Get store statistics
+     */
+    getStats(): {
+        size: number;
+        config: {
+            maxTtlHours: number;
+            inactivityMinutes: number;
+        };
+        sessions: Array<{
+            keyId: string;
+            ageMinutes: number;
+            inactivityMinutes: number;
+        }>;
+    };
+    /**
+     * Stop cleanup interval (for graceful shutdown)
+     */
+    destroy(): void;
+}
+export declare const sessionStore: SessionStore;
+//# sourceMappingURL=session-store.d.ts.map

package/dist/mcp/session-store.js

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * SessionStore - Maps key_id to real api_key for Claude App authentication
+ *
+ * Purpose: Keep real Hailer API keys on server side, Claude only gets a reference (key_id).
+ * Multiple concurrent sessions supported - each user gets their own key_id.
+ *
+ * Flow:
+ * 1. User logs in via Hailer auth page
+ * 2. Frontend generates key_id, sends {key_id, api_key} to MCP /auth/register
+ * 3. Frontend redirects to Claude with key_id as "access_token"
+ * 4. Claude sends key_id in Authorization header
+ * 5. MCP looks up real api_key from this store
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionStore = exports.SessionStore = void 0;
+const logger_1 = require("../lib/logger");
+const logger = (0, logger_1.createLogger)({ component: 'session-store' });
+class SessionStore {
+    store = new Map();
+    maxTtlMs; // Maximum session lifetime (absolute)
+    inactivityTtlMs; // Session expires after inactivity
+    cleanupInterval = null;
+    /**
+     * @param maxTtlHours - Maximum session lifetime in hours (default 24)
+     * @param inactivityMinutes - Session expires after this many minutes of inactivity (default 30)
+     */
+    constructor(maxTtlHours = 24, inactivityMinutes = 30) {
+        this.maxTtlMs = maxTtlHours * 60 * 60 * 1000;
+        this.inactivityTtlMs = inactivityMinutes * 60 * 1000;
+        // Cleanup expired sessions every 5 minutes (more frequent for inactivity-based expiry)
+        this.cleanupInterval = setInterval(() => this.cleanup(), 5 * 60 * 1000);
+        logger.info('SessionStore initialized', {
+            maxTtlHours,
+            inactivityMinutes,
+            maxTtlMs: this.maxTtlMs,
+            inactivityTtlMs: this.inactivityTtlMs
+        });
+    }
+    /**
+     * Register a new session (called by /auth/register endpoint)
+     */
+    set(keyId, apiKey, workspaceId) {
+        const now = Date.now();
+        const session = {
+            apiKey,
+            workspaceId,
+            createdAt: now,
+            lastAccessedAt: now,
+        };
+        this.store.set(keyId, session);
+        logger.info('Session registered', {
+            keyId: keyId.substring(0, 8) + '...',
+            workspaceId: workspaceId.substring(0, 8) + '...',
+            totalSessions: this.store.size,
+        });
+    }
+    /**
+     * Get session by key_id (returns null if expired or not found)
+     * Updates lastAccessedAt to extend inactivity timeout
+     */
+    get(keyId) {
+        const session = this.store.get(keyId);
+        if (!session) {
+            logger.debug('Session not found', { keyId: keyId.substring(0, 8) + '...' });
+            return null;
+        }
+        const now = Date.now();
+        const age = now - session.createdAt;
+        const inactivity = now - session.lastAccessedAt;
+        // Check if max lifetime exceeded (absolute expiry)
+        if (age > this.maxTtlMs) {
+            logger.info('Session expired (max TTL)', {
+                keyId: keyId.substring(0, 8) + '...',
+                ageHours: Math.round(age / (1000 * 60 * 60)),
+            });
+            this.store.delete(keyId);
+            return null;
+        }
+        // Check if inactivity timeout exceeded
+        if (inactivity > this.inactivityTtlMs) {
+            logger.info('Session expired (inactivity)', {
+                keyId: keyId.substring(0, 8) + '...',
+                inactivityMinutes: Math.round(inactivity / (1000 * 60)),
+            });
+            this.store.delete(keyId);
+            return null;
+        }
+        // Update lastAccessedAt to extend session
+        session.lastAccessedAt = now;
+        logger.debug('Session found', {
+            keyId: keyId.substring(0, 8) + '...',
+            ageMinutes: Math.round(age / (1000 * 60)),
+            inactivityMinutes: Math.round(inactivity / (1000 * 60)),
+        });
+        return session;
+    }
+    /**
+     * Delete session (logout)
+     */
+    delete(keyId) {
+        const existed = this.store.delete(keyId);
+        if (existed) {
+            logger.info('Session deleted', { keyId: keyId.substring(0, 8) + '...' });
+        }
+        return existed;
+    }
+    /**
+     * Remove all expired sessions (both max TTL and inactivity)
+     */
+    cleanup() {
+        const now = Date.now();
+        let removedMaxTtl = 0;
+        let removedInactivity = 0;
+        for (const [keyId, session] of this.store.entries()) {
+            const age = now - session.createdAt;
+            const inactivity = now - session.lastAccessedAt;
+            if (age > this.maxTtlMs) {
+                this.store.delete(keyId);
+                removedMaxTtl++;
+            }
+            else if (inactivity > this.inactivityTtlMs) {
+                this.store.delete(keyId);
+                removedInactivity++;
+            }
+        }
+        const totalRemoved = removedMaxTtl + removedInactivity;
+        if (totalRemoved > 0) {
+            logger.info('Cleanup completed', {
+                removedMaxTtl,
+                removedInactivity,
+                remaining: this.store.size
+            });
+        }
+    }
+    /**
+     * Get store statistics
+     */
+    getStats() {
+        const now = Date.now();
+        const sessions = Array.from(this.store.entries()).map(([keyId, session]) => ({
+            keyId: keyId.substring(0, 8) + '...',
+            ageMinutes: Math.round((now - session.createdAt) / (1000 * 60)),
+            inactivityMinutes: Math.round((now - session.lastAccessedAt) / (1000 * 60)),
+        }));
+        return {
+            size: this.store.size,
+            config: {
+                maxTtlHours: Math.round(this.maxTtlMs / (1000 * 60 * 60)),
+                inactivityMinutes: Math.round(this.inactivityTtlMs / (1000 * 60)),
+            },
+            sessions,
+        };
+    }
+    /**
+     * Stop cleanup interval (for graceful shutdown)
+     */
+    destroy() {
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        logger.info('SessionStore destroyed');
+    }
+}
+exports.SessionStore = SessionStore;
+// Singleton instance
+exports.sessionStore = new SessionStore();
+//# sourceMappingURL=session-store.js.map

package/dist/mcp/signal-handler.js

@@ -2,6 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SignalHandler = void 0;
 const logger_1 = require("../lib/logger");
+const webhooks_1 = require("../bot-config/webhooks");
+const types_1 = require("./utils/types");
 // Optional: bot-config only available in bot server mode, not MCP terminal
 let reloadConfigFromHailer = null;
 let setActiveWorkspace = null;
@@ -169,18 +171,15 @@ class SignalHandler {
             prevPhase: data.prevPhase || data.meta?.prevPhase
         });
         // Handle Agent Directory phase changes for bot enable/disable
-        // DISABLED: Now using webhook instead of socket signals for Agent Directory updates
-        // The webhook handler (src/mcp/webhook-handler.ts) handles bot config updates
-        // Keeping this code for potential fallback if webhook is unavailable
-        // if (processId && phase && activityIdRaw) {
-        //   const activityIds = Array.isArray(activityIdRaw)
-        //     ? activityIdRaw
-        //     : [activityIdRaw];
-        //
-        //   handleActivityPhaseChange(processId, activityIds, phase).catch(err => {
-        //     logger.error('Failed to handle activity phase change', err);
-        //   });
-        // }
+        // Socket signals as primary path, webhook as backup
+        if (processId && phase && activityIdRaw) {
+            const activityIds = Array.isArray(activityIdRaw)
+                ? activityIdRaw
+                : [activityIdRaw];
+            (0, webhooks_1.handleActivityPhaseChange)(processId, activityIds, phase).catch(err => {
+                logger.error('Failed to handle activity phase change', err);
+            });
+        }
     }
     handleActivityCreated(signal) {
         const data = signal.data;
@@ -241,6 +240,7 @@ class SignalHandler {
             // Refresh cache by fetching fresh data - API requires array of keys to fetch
             // IMPORTANT: Include 'processes' to get updated workflow list (e.g., after template install)
             const init = await this.client.socket.request('v2.core.init', [['users', 'network', 'networks', 'processes']]);
+            (0, types_1.normalizeInitProcesses)(init);
             // Update workspace cache with fresh data
             if (init.processes) {
                 this.workspaceCache.rawInit.processes = init.processes;

package/dist/mcp/tool-registry.d.ts

@@ -10,7 +10,6 @@
  * - Enables Claude's strict mode validation with actual workspace values
  */
 import { z } from 'zod';
-import { UserContext } from './UserContextCache';
 import { McpResponse } from './utils/types';
 /**
  * Tool groups for access control
@@ -27,6 +26,12 @@ export declare enum ToolGroup {
     NUCLEAR = "nuclear",
     BOT_INTERNAL = "bot_internal"
 }
+/**
+ * Context type for tool execution
+ * - 'hailer': Requires Hailer authentication via UserContextCache (default)
+ * - 'none': No authentication needed (e.g., Weaviate tools with their own auth)
+ */
+export type ToolContextType = 'hailer' | 'none';
 /**
  * Tool definition interface
  */
@@ -35,7 +40,11 @@ export interface Tool<TSchema extends z.ZodType = z.ZodType> {
     group: ToolGroup;
     description: string;
     schema: TSchema;
-    execute: (args: z.infer<TSchema>, context: UserContext) => Promise<McpResponse>;
+    /** What authentication context this tool needs. Defaults to 'hailer'. */
+    contextType?: ToolContextType;
+    /** Context is UserContext for Hailer tools, VipunenContext for contextType:'none' tools.
+     *  Type safety is enforced at the mcp-server dispatch boundary, not here. */
+    execute: (args: z.infer<TSchema>, context: any) => Promise<McpResponse>;
 }
 /**
  * Tool definition for MCP protocol (JSON-RPC)
@@ -56,10 +65,10 @@ export interface ToolDefinition {
  */
 export declare class ToolRegistry {
     private tools;
+    private _lazyGuard?;
     private enableNuclearTools;
     private workspaceSchemas;
     private workspaceSchemasLoaded;
-    private static readonly TOOL_TO_SCHEMA_MAP;
     constructor(options?: {
         enableNuclearTools?: boolean;
     });
@@ -80,6 +89,10 @@ export declare class ToolRegistry {
      * Add a tool to the registry
      */
     addTool(tool: Tool): void;
+    /**
+     * Get tool definitions filtered by contextType — single-pass, no secondary lookups
+     */
+    getToolDefinitionsByContextType(contextType: ToolContextType): ToolDefinition[];
     /**
      * Get tool definitions with optional filtering
      *
@@ -108,7 +121,7 @@ export declare class ToolRegistry {
     /**
      * Execute tool with validation
      */
-    executeTool(name: string, args: any, context: UserContext): Promise<any>;
+    executeTool(name: string, args: any, context: any): Promise<any>;
     /**
      * Pre-transform install_workflow args to fix common LLM mistakes BEFORE validation
      */