@hailer/mcp 0.1.8 → 0.1.9

package/dist/client/agents/specialist.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Specialist Daemon
+ *
+ * A lightweight daemon for specialist bots that only responds when @mentioned.
+ * Specialists are invited to discussions by the orchestrator (HAL) to handle
+ * specific complex tasks.
+ *
+ * Key differences from ChatAgentDaemon:
+ * - Only responds when @mentioned (not all messages)
+ * - Has specialized system prompt from Specialist config
+ * - More tool-focused, less conversational
+ */
+import { ChatAgentDaemon, ChatAgentDaemonConfig, IncomingMessage } from "./base";
+import { Specialist } from "./definitions";
+import { HailerSignal } from "../../mcp/signal-handler";
+import { ToolInput } from "../types";
+export interface SpecialistDaemonConfig extends ChatAgentDaemonConfig {
+    /** The specialist configuration */
+    specialist: Specialist;
+}
+export declare class SpecialistDaemon extends ChatAgentDaemon {
+    private specialistLogger;
+    private specialist;
+    private lastResponseTime;
+    private minResponseGap;
+    constructor(config: SpecialistDaemonConfig);
+    /**
+     * Override agent name for Agent Directory - uses specialist's configured name
+     */
+    protected getAgentName(): {
+        firstName: string;
+        lastName: string;
+    };
+    /**
+     * Override agent description for Agent Directory - uses specialist's expertise
+     */
+    protected getAgentDescription(): string;
+    /**
+     * Override Position details for Specialist - uses specialist's expertise
+     */
+    protected getPositionDetails(): {
+        name: string;
+        purpose: string;
+        personaTone: string;
+        coreCapabilities: string;
+        boundaries: string;
+    };
+    /**
+     * Specialist gets more tools for complex operations
+     */
+    protected getToolWhitelist(): string[];
+    /**
+     * Force compact output for schema tools (avoid verbose field dumps in discussions)
+     */
+    protected preprocessToolInput(toolName: string, input: ToolInput): ToolInput;
+    /**
+     * Override to only process messages where we're @mentioned
+     */
+    protected extractIncomingMessage(signal: HailerSignal): Promise<IncomingMessage | null>;
+    /**
+     * Check if this specialist is mentioned in the message
+     * Supports various mention formats:
+     * - @"Specialist Name"
+     * - @SpecialistName (no spaces)
+     * - Direct user tag [hailerTag|Name](userId)
+     */
+    private isMentionedInMessage;
+    /**
+     * Override system prompt with specialist-specific prompt
+     */
+    protected getSystemPrompt(): string;
+    /**
+     * Track response time for rate limiting
+     */
+    protected postResponse(discussionId: string, content: string): Promise<void>;
+    /**
+     * Get specialist status
+     */
+    getSpecialistStatus(): {
+        name: string;
+        expertise: string[];
+        conversationState: ReturnType<ChatAgentDaemon["getConversationState"]>;
+        lastResponseTime: number;
+    };
+}
+//# sourceMappingURL=specialist.d.ts.map

package/dist/client/agents/specialist.js

@@ -0,0 +1,340 @@
+"use strict";
+/**
+ * Specialist Daemon
+ *
+ * A lightweight daemon for specialist bots that only responds when @mentioned.
+ * Specialists are invited to discussions by the orchestrator (HAL) to handle
+ * specific complex tasks.
+ *
+ * Key differences from ChatAgentDaemon:
+ * - Only responds when @mentioned (not all messages)
+ * - Has specialized system prompt from Specialist config
+ * - More tool-focused, less conversational
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpecialistDaemon = void 0;
+const base_1 = require("./base");
+const logger_1 = require("../../lib/logger");
+class SpecialistDaemon extends base_1.ChatAgentDaemon {
+    specialistLogger;
+    specialist;
+    lastResponseTime = 0;
+    minResponseGap = 2000; // 2 seconds minimum between responses
+    constructor(config) {
+        super(config);
+        this.specialist = config.specialist;
+        this.specialistLogger = (0, logger_1.createLogger)({
+            component: "SpecialistDaemon",
+            botId: config.botClient.userId,
+            specialistName: config.specialist.name,
+        });
+    }
+    // ===== AGENT DIRECTORY OVERRIDES =====
+    /**
+     * Override agent name for Agent Directory - uses specialist's configured name
+     */
+    getAgentName() {
+        const nameParts = this.specialist.name.split(" ");
+        const firstName = nameParts[0] || "Specialist";
+        const lastName = nameParts.slice(1).join(" ") || "Bot";
+        return { firstName, lastName };
+    }
+    /**
+     * Override agent description for Agent Directory - uses specialist's expertise
+     */
+    getAgentDescription() {
+        return `${this.specialist.name} - Specialist bot.\n\nExpertise: ${this.specialist.expertise.join(", ")}\n\n${this.specialist.systemPrompt.substring(0, 500)}...`;
+    }
+    /**
+     * Override Position details for Specialist - uses specialist's expertise
+     */
+    getPositionDetails() {
+        return {
+            name: `${this.specialist.name} Position`,
+            purpose: `Specialist bot for: ${this.specialist.expertise.join(", ")}`,
+            personaTone: "Technical, precise, and data-focused. Responds with structured results.",
+            coreCapabilities: this.specialist.expertise.map(e => `- ${e}`).join("\n"),
+            boundaries: "- Only respond when explicitly @mentioned\n- Never fabricate data - always use tools\n- Stay focused on specialty area\n- Hand back to orchestrator when done",
+        };
+    }
+    /**
+     * Specialist gets more tools for complex operations
+     */
+    getToolWhitelist() {
+        return [
+            // All orchestrator tools
+            "list_workflows",
+            "list_workflow_phases",
+            "get_workflow_schema",
+            "list_workflows_minimal",
+            "list_activities",
+            "show_activity_by_id",
+            "count_activities",
+            "create_activity",
+            "update_activity",
+            "join_discussion",
+            "add_discussion_message",
+            "invite_discussion_members",
+            "fetch_discussion_messages",
+            "get_activity_from_discussion",
+            "list_my_discussions",
+            "search_workspace_users",
+            // Insight tools
+            "list_insights",
+            "get_insight_data",
+            "preview_insight",
+            "create_insight",
+            "update_insight",
+            "remove_insight",
+            // Workflow config
+            "update_workflow_field",
+            "update_workflow_phase",
+            "install_workflow",
+            "remove_workflow",
+            // Template tools
+            "list_templates",
+            "get_template",
+            "create_template",
+            "install_template",
+            // Other
+            "upload_files",
+            "test_function_field",
+        ];
+    }
+    /**
+     * Force compact output for schema tools (avoid verbose field dumps in discussions)
+     */
+    preprocessToolInput(toolName, input) {
+        if (toolName === "get_workflow_schema") {
+            return { ...input, compact: true };
+        }
+        return input;
+    }
+    /**
+     * Override to only process messages where we're @mentioned
+     */
+    async extractIncomingMessage(signal) {
+        // Get base message extraction
+        const message = await super.extractIncomingMessage(signal);
+        if (!message)
+            return null;
+        // Specialists only respond when mentioned
+        if (!this.isMentionedInMessage(message)) {
+            this.specialistLogger.debug("Message doesn't mention specialist, ignoring", {
+                discussion: message.discussionId,
+                from: message.senderName,
+            });
+            return null;
+        }
+        // Rate limit responses
+        const now = Date.now();
+        if (now - this.lastResponseTime < this.minResponseGap) {
+            this.specialistLogger.debug("Rate limiting specialist response", {
+                timeSinceLastResponse: now - this.lastResponseTime,
+            });
+            return null;
+        }
+        // Mark as high priority since we're explicitly mentioned
+        message.priority = "high";
+        message.priorityReason = `Specialist ${this.specialist.name} was tagged`;
+        this.specialistLogger.info("Specialist mentioned, processing message", {
+            discussion: message.discussionId,
+            from: message.senderName,
+            preview: message.content.substring(0, 50),
+        });
+        return message;
+    }
+    /**
+     * Check if this specialist is mentioned in the message
+     * Supports various mention formats:
+     * - @"Specialist Name"
+     * - @SpecialistName (no spaces)
+     * - Direct user tag [hailerTag|Name](userId)
+     */
+    isMentionedInMessage(message) {
+        const content = message.content;
+        const name = this.specialist.name;
+        const userId = this.botClient.userId;
+        // Check for hailerTag mention (most reliable)
+        const hailerTagPattern = new RegExp(`\\[hailerTag\\|[^\\]]*\\]\\(${userId}\\)`, "i");
+        if (hailerTagPattern.test(content)) {
+            return true;
+        }
+        // Check for @"Name" mention
+        if (content.includes(`@"${name}"`)) {
+            return true;
+        }
+        // Check for @Name (no spaces version)
+        const nameNoSpaces = name.replace(/\s+/g, "");
+        if (content.includes(`@${nameNoSpaces}`)) {
+            return true;
+        }
+        // Check for @Name (first word)
+        const firstName = name.split(" ")[0];
+        if (content.includes(`@${firstName}`)) {
+            return true;
+        }
+        // Check message.isMention (set by parent class)
+        if (message.isMention) {
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Override system prompt with specialist-specific prompt
+     */
+    getSystemPrompt() {
+        const now = new Date();
+        return `${this.specialist.systemPrompt}
+
+<current_time>${now.toISOString()}</current_time>
+
+<bot_info>
+Bot ID: ${this.botClient.userId}
+Name: ${this.specialist.name}
+</bot_info>
+
+<response_rules>
+- You were invited to this discussion to help with a specific task
+- Read HAL's handoff message to understand what's needed
+- Use MCP tools to complete the task - NEVER fabricate data
+- Respond with clear, structured results
+- Include activity links using #activityId format
+- Be concise and technical - data first, explanation second
+</response_rules>
+
+<tool_parameters>
+<context_ids>
+Extract IDs from the incoming tag and HAL's handoff:
+- activityId attribute → show_activity_by_id, update_activity
+- discussionId attribute → get_activity_from_discussion
+- workflowId, fieldId → insight tools
+</context_ids>
+
+<never_do>
+- Call tools with empty parameters {}
+- Use field LABELS as fieldIds (fieldId must be 24-char hex)
+- Guess IDs - always extract from context
+</never_do>
+
+<update_activity_formats>
+- Single mode: use activityId parameter
+- Bulk mode: use _id inside activities array (NOT activityId)
+</update_activity_formats>
+
+<field_values>
+- numericunit: 78 (NOT {"type":"numericunit","value":78})
+- activitylink: "abc123..." (NOT {"_id":"abc123","name":"..."})
+</field_values>
+</tool_parameters>
+
+<insight_tools>
+<critical>
+- fieldId MUST be 24-character hex ID, NOT the field label!
+- Field names must be SQL-safe: no spaces (use camelCase)
+</critical>
+
+<create_insight_format>
+sources: [{
+  name: "tableAlias",
+  workflowId: "691ffdf84217e9e8434e56ad",
+  fields: [
+    { name: "playerName", fieldId: "691ffdf84217e9e8434e56b1" },
+    { name: "injuryType", fieldId: "691ffdf84217e9e8434e56b2" }
+  ]
+}]
+</create_insight_format>
+
+<hailer_sql_syntax>
+Hailer insights: fields are mapped in sources.fields, then referenced by ALIAS in query.
+
+HOW IT WORKS:
+1. Define fields in sources: { name: "playerName", fieldId: "691fff..." }
+2. Use the NAME (alias) in SQL: SELECT playerName FROM tableName
+
+SELECT columns - use the field ALIAS names you defined:
+- playerName, injuryType    ← custom fields (by alias)
+- name                       ← built-in activity name
+
+Column aliases with spaces need quotes:
+- playerName as "Player Name"
+- injuryType as "Injury Type"
+
+LIMITATIONS - DO NOT USE:
+- Phase filtering (no _phase column)
+- Date functions like NOW(), date('now'), CURRENT_DATE
+- Complex WHERE clauses with dates
+
+Keep queries SIMPLE: SELECT, FROM, basic WHERE (string comparisons), ORDER BY.
+Users can filter via UI "Show Filters" button.
+</hailer_sql_syntax>
+
+<correct_query_example>
+sources: [{
+  name: "injuries",
+  workflowId: "691ffdf84217e9e8434e56ad",
+  fields: [
+    { name: "playerName", fieldId: "691ffdf84217e9e8434e5694" },
+    { name: "injuryType", fieldId: "691ffdf84217e9e8434e5695" }
+  ]
+}]
+
+query: "SELECT playerName as \\"Player\\", injuryType as \\"Injury Type\\" FROM injuries ORDER BY playerName ASC"
+
+WRONG (will fail):
+- WHERE expectedRecovery > date('now')
+- WHERE _phase = 'phaseId'
+- SELECT FIELD(fieldId) as column
+</correct_query_example>
+
+<where_to_get_ids>
+HAL's handoff contains workflowId, fieldIds, and phaseIds. Use them exactly.
+If not provided, call get_workflow_schema AND list_workflow_phases.
+</where_to_get_ids>
+</insight_tools>
+
+<response_format>
+When you complete a task, respond with:
+<respond discussion="DISCUSSION_ID">
+[Status emoji] [Brief summary]
+
+**What I did:**
+- Step 1: ...
+- Step 2: ...
+
+**Results:**
+[Data, links, or confirmation]
+
+**Next steps (if applicable):**
+[Suggestions for follow-up]
+</respond>
+
+If you need clarification:
+<respond discussion="DISCUSSION_ID">
+I need more information to complete this task:
+- Question 1?
+- Question 2?
+</respond>
+</response_format>`;
+    }
+    /**
+     * Track response time for rate limiting
+     */
+    async postResponse(discussionId, content) {
+        await super.postResponse(discussionId, content);
+        this.lastResponseTime = Date.now();
+    }
+    /**
+     * Get specialist status
+     */
+    getSpecialistStatus() {
+        return {
+            name: this.specialist.name,
+            expertise: this.specialist.expertise,
+            conversationState: this.getConversationState(),
+            lastResponseTime: this.lastResponseTime,
+        };
+    }
+}
+exports.SpecialistDaemon = SpecialistDaemon;
+//# sourceMappingURL=specialist.js.map

package/dist/client/bot-manager.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Multi-Bot Client Manager
+ * Manages multiple bot clients, each with their own Hailer connection
+ */
+import { HailerClient } from "../mcp/hailer-clients";
+import { SignalHandler } from "../mcp/signal-handler";
+import { BotClientConfig } from "./types";
+import { WorkspaceCache, UserInfo } from "../mcp/workspace-cache";
+export interface BotClient {
+    userId: string;
+    firstName: string;
+    lastName: string;
+    config: BotClientConfig;
+    client: HailerClient;
+    signalHandler: SignalHandler;
+    workspaceCache?: WorkspaceCache;
+}
+export declare class MultiBotManager {
+    private botConfigs;
+    private botClients;
+    constructor(botConfigs: BotClientConfig[]);
+    initializeAllHailerClientsFromConfig(): Promise<void>;
+    getBotClient(userId: string): BotClient | undefined;
+    getAllBotClients(): BotClient[];
+    getBotIds(): string[];
+    private userNameCache;
+    private static USER_CACHE_TTL;
+    /**
+     * Look up a user's full name by their user ID
+     * Uses workspace cache first, then falls back to socket API call
+     */
+    getUserName(userId: string): string | undefined;
+    /**
+     * Look up a user's full name by their user ID (async version)
+     * Falls back to socket API if not in cache
+     */
+    getUserNameAsync(userId: string): Promise<string | undefined>;
+    /**
+     * Get user info by ID (returns full UserInfo object)
+     */
+    getUserInfo(userId: string): UserInfo | undefined;
+    shutdown(): Promise<void>;
+}
+//# sourceMappingURL=bot-manager.d.ts.map

package/dist/client/bot-manager.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Multi-Bot Client Manager
+ * Manages multiple bot clients, each with their own Hailer connection
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiBotManager = void 0;
+const hailer_clients_1 = require("../mcp/hailer-clients");
+const signal_handler_1 = require("../mcp/signal-handler");
+const workspace_cache_1 = require("../mcp/workspace-cache");
+const config_1 = require("../config");
+class MultiBotManager {
+    botConfigs;
+    botClients = new Map();
+    constructor(botConfigs) {
+        this.botConfigs = botConfigs;
+    }
+    // for client we may put initializeAllConfigClients method to do it at once
+    // in case we only use MCP Server:
+    // for MCP Server it may just get a specific client and this class initialize it specifically and even kill it later if not needed
+    async initializeAllHailerClientsFromConfig() {
+        console.log(`🤖 Initializing ${this.botConfigs.length} bot clients...`);
+        const appConfig = (0, config_1.createApplicationConfig)();
+        for (const config of this.botConfigs) {
+            try {
+                // Use shared connection pool via API key lookup
+                const client = await (0, hailer_clients_1.createHailerClientByApiKey)(config.mcpServerApiKey);
+                // Get user ID automatically from authenticated session
+                const userId = await (0, hailer_clients_1.getCurrentUserId)(client);
+                // Fetch init data to get workspace cache with user names and teams
+                let workspaceCache;
+                try {
+                    const init = await client.socket.request('v2.core.init', [['users', 'network', 'networks', 'teams']]);
+                    workspaceCache = (0, workspace_cache_1.createWorkspaceCache)(init, appConfig.mcpConfig);
+                    const teamCount = Object.keys(init.teams || {}).length;
+                    console.log(`📋 Loaded workspace cache with ${workspaceCache.users.length} users, ${teamCount} teams`);
+                }
+                catch (initError) {
+                    console.warn(`⚠️ Could not load workspace cache for ${config.email}:`, initError);
+                }
+                const signalHandler = new signal_handler_1.SignalHandler(client, workspaceCache);
+                // Look up user's name from workspace cache
+                let firstName = 'Bot';
+                let lastName = '';
+                if (workspaceCache) {
+                    const userInfo = workspaceCache.usersById[userId];
+                    if (userInfo) {
+                        firstName = userInfo.firstname || 'Bot';
+                        lastName = userInfo.lastname || '';
+                    }
+                }
+                const botClient = {
+                    userId,
+                    firstName,
+                    lastName,
+                    config,
+                    client,
+                    signalHandler,
+                    workspaceCache,
+                };
+                this.botClients.set(userId, botClient);
+                console.log(`✅ Bot client initialized for ${config.email} (${userId}) via API key ${config.mcpServerApiKey.substring(0, 8)}...`);
+            }
+            catch (error) {
+                console.error(`❌ Failed to initialize bot client for ${config.email}:`, error);
+                // Continue with other bots even if one fails
+            }
+        }
+        console.log(`✅ Initialized ${this.botClients.size} bot clients successfully`);
+    }
+    getBotClient(userId) {
+        const botClient = this.botClients.get(userId);
+        if (!botClient) {
+            console.warn(`❌ No bot client found for userId: ${userId}`);
+        }
+        return botClient;
+    }
+    getAllBotClients() {
+        return Array.from(this.botClients.values());
+    }
+    getBotIds() {
+        return Array.from(this.botClients.keys());
+    }
+    // Simple in-memory cache for user lookups (refreshed on demand)
+    userNameCache = new Map();
+    static USER_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+    /**
+     * Look up a user's full name by their user ID
+     * Uses workspace cache first, then falls back to socket API call
+     */
+    getUserName(userId) {
+        // Check in-memory cache first (for API-fetched users)
+        const cached = this.userNameCache.get(userId);
+        if (cached && Date.now() - cached.fetchedAt < MultiBotManager.USER_CACHE_TTL) {
+            return cached.name;
+        }
+        // Try each bot client's workspace cache until we find the user
+        for (const botClient of this.botClients.values()) {
+            if (botClient.workspaceCache) {
+                const user = (0, workspace_cache_1.getUserById)(botClient.workspaceCache, userId);
+                if (user) {
+                    const fullName = `${user.firstname || ''} ${user.lastname || ''}`.trim();
+                    return fullName || user.fullName || undefined;
+                }
+            }
+        }
+        return undefined;
+    }
+    /**
+     * Look up a user's full name by their user ID (async version)
+     * Falls back to socket API if not in cache
+     */
+    async getUserNameAsync(userId) {
+        // Try sync lookup first
+        const syncResult = this.getUserName(userId);
+        if (syncResult) {
+            return syncResult;
+        }
+        // Fall back to socket API call
+        const botClient = this.botClients.values().next().value;
+        if (!botClient) {
+            return undefined;
+        }
+        try {
+            // Fetch fresh init data with users
+            const init = await botClient.client.socket.request('v2.core.init', [['users']]);
+            if (init.users && init.users[userId]) {
+                const user = init.users[userId];
+                const fullName = `${user.firstname || ''} ${user.lastname || ''}`.trim();
+                // Cache the result
+                if (fullName) {
+                    this.userNameCache.set(userId, { name: fullName, fetchedAt: Date.now() });
+                    return fullName;
+                }
+            }
+        }
+        catch (error) {
+            console.warn(`⚠️ Could not fetch user info for ${userId}:`, error);
+        }
+        return undefined;
+    }
+    /**
+     * Get user info by ID (returns full UserInfo object)
+     */
+    getUserInfo(userId) {
+        for (const botClient of this.botClients.values()) {
+            if (botClient.workspaceCache) {
+                const user = (0, workspace_cache_1.getUserById)(botClient.workspaceCache, userId);
+                if (user) {
+                    return user;
+                }
+            }
+        }
+        return undefined;
+    }
+    async shutdown() {
+        console.log("🤖 Shutting down all bot clients...");
+        for (const [userId, botClient] of this.botClients) {
+            try {
+                // Properly disconnect from shared connection pool
+                (0, hailer_clients_1.disconnectHailerClientByApiKey)(botClient.config.mcpServerApiKey);
+                console.log(`✅ Bot client ${userId} shut down (API key: ${botClient.config.mcpServerApiKey.substring(0, 8)}...)`);
+            }
+            catch (error) {
+                console.error(`❌ Error shutting down bot client ${userId}:`, error);
+            }
+        }
+        this.botClients.clear();
+        console.log("✅ All bot clients shut down");
+    }
+}
+exports.MultiBotManager = MultiBotManager;
+//# sourceMappingURL=bot-manager.js.map