@hailer/mcp 0.1.15 → 0.1.16

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

@@ -0,0 +1,91 @@
+/**
+ * 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 "../hal/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;
+    };
+    /**
+     * Trigger specialist to respond in a discussion with specific context
+     * Used for proactive responses (e.g., bug detection triggering Giuseppe)
+     */
+    respondWithContext(discussionId: string, activityId: string, contextMessage: string): Promise<void>;
+}
+//# sourceMappingURL=specialist.d.ts.map

package/dist/agents/shared/specialist.js

@@ -0,0 +1,399 @@
+"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,
+        };
+    }
+    /**
+     * Trigger specialist to respond in a discussion with specific context
+     * Used for proactive responses (e.g., bug detection triggering Giuseppe)
+     */
+    async respondWithContext(discussionId, activityId, contextMessage) {
+        this.specialistLogger.info('Triggering contextual response', { discussionId, activityId });
+        try {
+            // Join the discussion first using MCP tool
+            // Note: join_discussion expects activityId to find the linked discussion
+            const joinResult = await this.callMcpTool("join_discussion", { activityId });
+            const joinResultText = joinResult?.content?.[0]?.text || '';
+            this.specialistLogger.debug('Join discussion result', {
+                activityId,
+                resultPreview: joinResultText.substring(0, 200)
+            });
+            // Get workspace ID from bot client cache
+            const workspaceId = this.botClient.workspaceCache?.currentWorkspace?._id || '';
+            if (!workspaceId) {
+                this.specialistLogger.warn('No workspace ID available from cache');
+            }
+            // Create a synthetic incoming message with the context
+            const syntheticMessage = {
+                id: `synthetic-${Date.now()}`,
+                discussionId,
+                linkedActivityId: activityId,
+                workspaceId,
+                content: contextMessage,
+                senderName: 'System',
+                senderId: 'system',
+                timestamp: Date.now(),
+                priority: 'high',
+                priorityReason: 'system_notification',
+                isReplyToBot: false,
+                isMention: true, // Treat as mention so specialist responds
+                isDirectMessage: false,
+            };
+            this.specialistLogger.info('Queuing synthetic message for LLM pipeline', {
+                discussionId,
+                activityId,
+                contentLength: contextMessage.length
+            });
+            // Process through normal LLM pipeline
+            await this['processMessage'](syntheticMessage);
+            this.specialistLogger.info('Contextual response completed', { discussionId, activityId });
+        }
+        catch (error) {
+            // Properly serialize error for logging
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const errorStack = error instanceof Error ? error.stack : undefined;
+            this.specialistLogger.error('Failed to respond with context', {
+                discussionId,
+                activityId,
+                errorMessage,
+                errorStack
+            });
+            // Re-throw so caller knows it failed
+            throw error;
+        }
+    }
+}
+exports.SpecialistDaemon = SpecialistDaemon;
+//# sourceMappingURL=specialist.js.map

package/dist/agents/shared/tool-schema-loader.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Tool Schema Loader
+ *
+ * Manages MCP tool discovery, schema loading, and filtering.
+ * Shared between all LLM providers (Anthropic, OpenAI, etc.)
+ *
+ * Key Features:
+ * - Load lightweight tool index from MCP server
+ * - Filter tools by groups (READ, WRITE, PLAYGROUND)
+ * - Load full schemas on-demand (token-efficient)
+ * - Cache loaded schemas
+ */
+import { ToolGroup } from '../../mcp/tool-registry';
+import { JsonSchema } from './types';
+import Anthropic from '@anthropic-ai/sdk';
+export interface ToolIndexEntry {
+    name: string;
+    category: string;
+    description: string;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    input_schema: JsonSchema;
+}
+export interface LoadToolsOptions {
+    mcpServerUrl: string;
+    mcpServerApiKey: string;
+    allowedGroups: ToolGroup[];
+    allowedTools?: string[];
+    excludeMessageFetchTools?: boolean;
+}
+export declare class ToolSchemaLoader {
+    private toolSchemaCache;
+    /**
+     * Load tool index with filtering
+     * Returns lightweight tool list with optional exclusions
+     */
+    loadToolIndex(options: LoadToolsOptions): Promise<ToolIndexEntry[]>;
+    /**
+     * Load full schema for a specific tool on-demand
+     */
+    loadToolSchema(mcpServerUrl: string, mcpServerApiKey: string, toolName: string): Promise<any>;
+    /**
+     * Convert tool index to minimal tool definitions (stubs)
+     * Full schemas will be loaded on-demand when needed
+     */
+    toMinimalToolDefinitions(toolIndex: ToolIndexEntry[]): Anthropic.Tool[];
+    /**
+     * Get count of loaded schemas
+     */
+    getLoadedSchemaCount(): number;
+    /**
+     * Clear schema cache
+     */
+    clearCache(): void;
+    /**
+     * Fetch tool index from MCP server
+     */
+    private fetchMcpToolIndex;
+}
+//# sourceMappingURL=tool-schema-loader.d.ts.map