@hailer/mcp 0.0.1

package/dist/client/agent-activity-bot.js

@@ -0,0 +1,166 @@
+"use strict";
+/**
+ * Agent Activity Bot
+ *
+ * Monitors agent activity and posts summaries to discussions.
+ * Can respond to queries about agent performance and tool usage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentActivityBot = void 0;
+exports.createAgentActivityBot = createAgentActivityBot;
+const logger_1 = require("../lib/logger");
+const logger = (0, logger_1.createLogger)({ component: 'agent-activity-bot' });
+class AgentActivityBot {
+    agentTracker;
+    config;
+    lastPostedConversation = new Map(); // discussionId -> timestamp
+    constructor(agentTracker, config) {
+        this.agentTracker = agentTracker;
+        this.config = {
+            minDurationThreshold: 1000,
+            ...config
+        };
+        if (this.config.enabled) {
+            logger.info('Agent Activity Bot initialized', {
+                postSummaries: this.config.postSummaryAfterConversation,
+                minThreshold: this.config.minDurationThreshold
+            });
+        }
+    }
+    /**
+     * Generate a summary message for the last conversation in a discussion
+     */
+    generateSummary(requestId, discussionId, duration, toolsCalled) {
+        const recentActivity = this.agentTracker.getRecentActivity(50);
+        // Find the specific request
+        const trigger = recentActivity.find(e => e.type === 'trigger' && e.requestId === requestId);
+        const completion = recentActivity.find(e => e.type === 'completion' && e.requestId === requestId);
+        if (!trigger || !completion || trigger.type !== 'trigger' || completion.type !== 'completion') {
+            return `🤖 **Agent Activity**\n\nProcessing completed but details unavailable.`;
+        }
+        return this.formatSummaryMessage(trigger.trigger.type, completion.completion.success, duration, toolsCalled, completion.completion.provider || 'unknown');
+    }
+    /**
+     * Format a concise summary message
+     */
+    formatSummaryMessage(triggerType, success, duration, toolsCalled, provider) {
+        const statusIcon = success ? '✅' : '❌';
+        const triggerIcon = triggerType === 'mention' ? '💬' : '📩';
+        return `🤖 **Agent Activity**
+${statusIcon} ${success ? 'Completed' : 'Failed'} ${triggerIcon} ${triggerType === 'mention' ? 'Mention' : 'Direct message'}
+⏱️ Duration: ${(duration / 1000).toFixed(2)}s | 🔧 Tools: ${toolsCalled.length > 0 ? toolsCalled.slice(0, 3).join(', ') : 'none'}${toolsCalled.length > 3 ? '...' : ''}
+🧠 Provider: ${provider}`;
+    }
+    /**
+     * Generate detailed agent activity report
+     */
+    generateDetailedReport(discussionId) {
+        const stats = this.agentTracker.getStats();
+        const recentActivity = this.agentTracker.getRecentActivity(100);
+        let report = `📊 **Detailed Agent Activity Report**\n\n`;
+        if (discussionId) {
+            // Filter for specific discussion
+            const discussionActivity = recentActivity.filter(e => {
+                if (e.type === 'trigger')
+                    return e.trigger.discussionId === discussionId;
+                if (e.type === 'tool_call')
+                    return e.toolCall.discussionId === discussionId;
+                return false;
+            });
+            const discussionTriggers = discussionActivity.filter(e => e.type === 'trigger');
+            const discussionToolCalls = discussionActivity.filter(e => e.type === 'tool_call');
+            report += `**This Conversation:**\n`;
+            report += `- Total Interactions: ${discussionTriggers.length}\n`;
+            report += `- Tool Calls: ${discussionToolCalls.length}\n`;
+            report += `\n`;
+            // Show last 5 interactions
+            if (discussionTriggers.length > 0) {
+                report += `**Recent Interactions:**\n`;
+                discussionTriggers.slice(-5).forEach((event, i) => {
+                    if (event.type === 'trigger') {
+                        report += `${i + 1}. ${event.trigger.type} - ${event.trigger.messagePreview}\n`;
+                    }
+                });
+                report += `\n`;
+            }
+        }
+        // Overall stats
+        report += `**Overall Stats:**\n`;
+        report += `- Total Triggers: ${stats.totalTriggers}\n`;
+        report += `- Total Completions: ${stats.totalCompletions}\n`;
+        report += `- Success Rate: ${stats.successRate.toFixed(1)}%\n`;
+        report += `- Avg Response Time: ${(stats.averageResponseTime / 1000).toFixed(2)}s\n`;
+        report += `- Total Tool Calls: ${stats.totalToolCalls}\n\n`;
+        // Most active agent
+        if (stats.mostActiveBot) {
+            report += `**Most Active Agent:**\n`;
+            report += `- Bot ID: ${stats.mostActiveBot.substring(0, 8)}...\n\n`;
+        }
+        // Top tools
+        if (stats.mostUsedTool) {
+            report += `**Most Used Tool:** ${stats.mostUsedTool}\n\n`;
+        }
+        // Recent tool calls
+        const recentToolCalls = this.agentTracker.getRecentToolCalls(5);
+        if (recentToolCalls.length > 0) {
+            report += `**Recent Tool Calls:**\n`;
+            recentToolCalls.forEach((call, i) => {
+                const status = call.toolCall.response.success ? '✅' : '❌';
+                report += `${i + 1}. ${status} ${call.toolCall.toolName} (${(call.toolCall.duration / 1000).toFixed(2)}s)\n`;
+            });
+        }
+        return report;
+    }
+    /**
+     * Check if message is asking for agent activity details
+     */
+    isActivityQuery(messageContent) {
+        const lower = messageContent.toLowerCase();
+        return ((lower.includes('agent') || lower.includes('bot') || lower.includes('activity')) && (lower.includes('activity') ||
+            lower.includes('stats') ||
+            lower.includes('performance') ||
+            lower.includes('detail') ||
+            lower.includes('report') ||
+            lower.includes('how') ||
+            lower.includes('what tools') ||
+            lower.includes('tool usage')));
+    }
+    /**
+     * Should post summary after this conversation?
+     */
+    shouldPostSummary(discussionId, duration) {
+        if (!this.config.enabled || !this.config.postSummaryAfterConversation) {
+            return false;
+        }
+        // Check duration threshold
+        if (duration < (this.config.minDurationThreshold || 0)) {
+            return false;
+        }
+        // Debounce: Don't post if we posted recently (within 30 seconds)
+        const lastPosted = this.lastPostedConversation.get(discussionId);
+        if (lastPosted && Date.now() - lastPosted < 30000) {
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Mark that we posted a summary for this discussion
+     */
+    markPosted(discussionId) {
+        this.lastPostedConversation.set(discussionId, Date.now());
+    }
+    /**
+     * Get agent tracker instance
+     */
+    getAgentTracker() {
+        return this.agentTracker;
+    }
+}
+exports.AgentActivityBot = AgentActivityBot;
+/**
+ * Factory function to create AgentActivityBot
+ */
+function createAgentActivityBot(agentTracker, config) {
+    return new AgentActivityBot(agentTracker, config);
+}
+//# sourceMappingURL=agent-activity-bot.js.map

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

@@ -0,0 +1,499 @@
+/**
+ * Agent Activity Tracker
+ *
+ * Provides comprehensive tracking and analytics for AI agent interactions within
+ * the Hailer MCP ecosystem. This module captures conversation flows, performance
+ * metrics, and usage patterns to enable business intelligence and system optimization.
+ *
+ * Key Features:
+ * - End-to-end conversation flow tracking (trigger → completion correlation)
+ * - Detailed tool usage analytics with request/response data
+ * - Performance metrics (response times, success rates)
+ * - Agent usage statistics and behavioral insights
+ * - Persistent JSON-based storage with automatic rotation
+ *
+ * Environment Behavior:
+ * - Development (NODE_ENV !== 'production'): JSON file tracking enabled by default
+ * - Production (NODE_ENV === 'production'): JSON file tracking disabled by default
+ * - Override: Set AGENT_TRACKING_ENABLED=true to force enable in production
+ *
+ * In production, all tracking events are still logged via the unified logger
+ * (OTLP) but no JSON files are created to avoid disk I/O and storage costs.
+ */
+import { Logger } from '../lib/logger';
+/**
+ * Represents an agent trigger event when a user activates an AI agent
+ * Links to completion events via requestId for end-to-end flow analysis
+ */
+export interface AgentTriggerLog {
+    type: 'trigger';
+    /** Unique identifier linking trigger to completion events */
+    requestId: string;
+    /** ISO timestamp when the trigger occurred */
+    timestamp: string;
+    /** Details about how and why the agent was triggered */
+    trigger: {
+        /** Method of agent activation */
+        type: 'mention' | 'direct';
+        /** Conversation thread identifier */
+        discussionId: string;
+        /** User who triggered the agent */
+        userId: string;
+        /** Display name of the triggering user */
+        userName: string;
+        /** Unique identifier of the responding agent */
+        botId: string;
+        /** Truncated preview of the message that triggered the agent */
+        messagePreview: string;
+        /** Optional workspace context */
+        workspaceId?: string;
+    };
+}
+/**
+ * Represents an agent completion event when processing finishes
+ * Correlated with trigger events to measure end-to-end performance
+ */
+export interface AgentCompletionLog {
+    type: 'completion';
+    /** Unique identifier linking to original trigger event */
+    requestId: string;
+    /** ISO timestamp when processing completed */
+    timestamp: string;
+    /** Results and metrics from the agent's processing */
+    completion: {
+        /** Whether the agent completed successfully */
+        success: boolean;
+        /** LLM provider used (anthropic, openai, etc) */
+        provider?: string;
+        /** List of tools/functions called during processing */
+        toolsCalled: string[];
+        /** Truncated preview of the agent's response */
+        responsePreview?: string;
+        /** Total processing time in milliseconds */
+        duration: number;
+        /** Error message if processing failed */
+        error?: string;
+    };
+}
+/**
+ * Represents a detailed tool/function call made during agent processing
+ * Provides granular visibility into agent decision-making and API usage
+ */
+export interface AgentToolCallLog {
+    type: 'tool_call';
+    /** Request identifier (may be shared across multiple tool calls) */
+    requestId: string;
+    /** ISO timestamp when the tool call was made */
+    timestamp: string;
+    /** Detailed information about the tool invocation */
+    toolCall: {
+        /** Name of the tool/function called */
+        toolName: string;
+        /** Provider handling the tool call */
+        provider: string;
+        /** Input data sent to the tool */
+        request: {
+            /** Arguments passed to the tool */
+            arguments: any;
+            /** API endpoint if applicable */
+            endpoint?: string;
+            /** HTTP method if applicable */
+            method?: string;
+        };
+        /** Output data received from the tool */
+        response: {
+            /** Whether the tool call succeeded */
+            success: boolean;
+            /** Response data if successful */
+            data?: any;
+            /** Error details if failed */
+            error?: string;
+        };
+        /** Tool execution time in milliseconds */
+        duration: number;
+        /** Agent that made the tool call */
+        botId?: string;
+        /** Conversation context */
+        discussionId?: string;
+        /** Workspace context */
+        workspaceId?: string;
+    };
+}
+/**
+ * Represents system-level events related to agent operations
+ * Captures infrastructure events, initialization, errors, etc.
+ */
+export interface AgentSystemLog {
+    type: 'system';
+    /** Unique identifier for the system event */
+    requestId: string;
+    /** ISO timestamp when the system event occurred */
+    timestamp: string;
+    /** Details about the system event */
+    system: {
+        /** Whether the system operation succeeded */
+        success: boolean;
+        /** Human-readable description of the event */
+        message: string;
+        /** Additional technical details */
+        details?: string;
+        /** Error information if the operation failed */
+        error?: string;
+    };
+}
+/** Union type for all possible agent log entry types */
+export type AgentLogEntry = AgentTriggerLog | AgentCompletionLog | AgentToolCallLog | AgentSystemLog;
+/**
+ * Root structure of the agent activity log file
+ * Contains all tracked events with automatic rotation
+ */
+export interface AgentActivityLog {
+    /** Array of all logged agent activity events */
+    entries: AgentLogEntry[];
+}
+/**
+ * Agent Activity Tracker
+ *
+ * Main class for tracking AI agent interactions, performance, and usage patterns.
+ * Provides both real-time logging capabilities and historical analytics.
+ *
+ * @example
+ * ```typescript
+ * const logger = createLogger({ component: 'my-component' });
+ * const tracker = new AgentTracker(logger);
+ *
+ * // Track a conversation flow
+ * const requestId = tracker.logTrigger({
+ *   triggerType: 'mention',
+ *   discussionId: 'disc_123',
+ *   userId: 'user_456',
+ *   userName: 'John Doe',
+ *   botId: 'bot_789',
+ *   messageContent: '@bot help me with this task'
+ * });
+ *
+ * // Later, track completion
+ * tracker.logCompletion({
+ *   requestId,
+ *   success: true,
+ *   provider: 'anthropic',
+ *   toolsCalled: ['list_activities', 'create_activity'],
+ *   duration: 2500
+ * });
+ * ```
+ */
+export declare class AgentTracker {
+    private logger;
+    private logFilePath?;
+    private maxEntries;
+    private isProduction;
+    private isTrackingEnabled;
+    /**
+     * Creates a new Agent Activity Tracker instance
+     *
+     * @param logger - Optional logger instance for operational logging. If not provided, creates a new logger
+     * @param logDir - Directory where agent activity logs will be stored (default: 'logs')
+     * @param maxEntries - Maximum number of log entries before rotation (default: 1000)
+     */
+    constructor(logger?: Logger, logDir?: string, maxEntries?: number);
+    /**
+     * Initializes the agent activity log file if it doesn't exist
+     * Creates the necessary directory structure and empty log file
+     * Only runs in development mode or when explicitly enabled
+     *
+     * @private
+     */
+    private initializeLogFile;
+    /**
+     * Reads the current agent activity log from disk
+     * Returns empty log in production mode or when tracking is disabled
+     *
+     * @private
+     * @returns The current log data, or empty log if file cannot be read or tracking is disabled
+     */
+    private readLogFile;
+    /**
+     * Writes the agent activity log to disk with automatic rotation
+     * Skips file writing in production mode unless explicitly enabled
+     *
+     * @private
+     * @param log - The log data to write
+     */
+    private writeLogFile;
+    /**
+     * Generates a unique request identifier for correlation
+     *
+     * @private
+     * @returns A unique request ID string
+     */
+    private generateRequestId;
+    /**
+     * Truncates text to a specified maximum length for preview purposes
+     *
+     * @private
+     * @param text - The text to truncate
+     * @param maxLength - Maximum length before truncation (default: 50)
+     * @returns Truncated text with ellipsis if needed
+     */
+    private truncateText;
+    /**
+     * Logs when an AI agent is triggered to respond to a user message
+     *
+     * Creates a correlation ID that links trigger events to completion events,
+     * enabling end-to-end conversation flow analysis and performance tracking.
+     *
+     * @param params - Trigger event details
+     * @param params.triggerType - How the agent was activated ('mention' | 'direct')
+     * @param params.discussionId - Unique identifier for the conversation thread
+     * @param params.userId - User who triggered the agent
+     * @param params.userName - Display name of the triggering user
+     * @param params.botId - Unique identifier of the responding agent
+     * @param params.messageContent - Original message content that triggered the agent
+     * @param params.workspaceId - Optional workspace context
+     *
+     * @returns {string} requestId - Unique correlation ID for linking with completion events
+     *
+     * @example
+     * ```typescript
+     * const requestId = agentTracker.logTrigger({
+     *   triggerType: 'mention',
+     *   discussionId: 'disc_123',
+     *   userId: 'user_456',
+     *   userName: 'John Doe',
+     *   botId: 'bot_789',
+     *   messageContent: '@bot help me with this task'
+     * });
+     * ```
+     */
+    logTrigger(params: {
+        triggerType: 'mention' | 'direct';
+        discussionId: string;
+        userId: string;
+        userName: string;
+        botId: string;
+        messageContent: string;
+        workspaceId?: string;
+    }): string;
+    /**
+     * Logs when an AI agent completes processing a user request
+     *
+     * Records the final outcome, performance metrics, and tools used during processing.
+     * Must be correlated with a trigger event using the same requestId for complete
+     * conversation flow analysis.
+     *
+     * @param params - Completion event details
+     * @param params.requestId - Correlation ID from the original trigger event
+     * @param params.success - Whether the agent completed successfully
+     * @param params.provider - LLM provider used (anthropic, openai, etc)
+     * @param params.toolsCalled - Array of tool names that were invoked
+     * @param params.responseContent - The agent's response content
+     * @param params.duration - Total processing time in milliseconds
+     * @param params.error - Error message if processing failed
+     *
+     * @example
+     * ```typescript
+     * agentTracker.logCompletion({
+     *   requestId: 'req-123-abc',
+     *   success: true,
+     *   provider: 'anthropic',
+     *   toolsCalled: ['list_activities', 'create_activity'],
+     *   responseContent: 'I created the task for you',
+     *   duration: 2500
+     * });
+     * ```
+     */
+    logCompletion(params: {
+        requestId: string;
+        success: boolean;
+        provider?: string;
+        toolsCalled?: string[];
+        responseContent?: string;
+        duration: number;
+        error?: string;
+    }): void;
+    /**
+     * Logs individual tool calls made during agent processing
+     *
+     * Provides granular visibility into agent decision-making by recording each
+     * tool invocation with full request/response data. Essential for debugging
+     * agent behavior and optimizing tool usage patterns.
+     *
+     * @param params - Tool call event details
+     * @param params.requestId - Optional correlation ID (generates new one if not provided)
+     * @param params.toolName - Name of the tool/function that was called
+     * @param params.provider - Provider handling the tool execution
+     * @param params.request - Input data sent to the tool
+     * @param params.request.arguments - Arguments passed to the tool
+     * @param params.request.endpoint - API endpoint if applicable
+     * @param params.request.method - HTTP method if applicable
+     * @param params.response - Output data received from the tool
+     * @param params.response.success - Whether the tool call succeeded
+     * @param params.response.data - Response data if successful
+     * @param params.response.error - Error details if failed
+     * @param params.duration - Tool execution time in milliseconds
+     * @param params.botId - Agent that made the tool call
+     * @param params.discussionId - Conversation context
+     * @param params.workspaceId - Workspace context
+     *
+     * @returns {string} requestId - The correlation ID used for this tool call
+     *
+     * @example
+     * ```typescript
+     * agentTracker.logToolCall({
+     *   requestId: 'req-123-abc',
+     *   toolName: 'list_activities',
+     *   provider: 'hailer-mcp',
+     *   request: {
+     *     arguments: { workflowId: 'wf_456', limit: 10 }
+     *   },
+     *   response: {
+     *     success: true,
+     *     data: { activities: [...] }
+     *   },
+     *   duration: 850,
+     *   botId: 'bot_789'
+     * });
+     * ```
+     */
+    logToolCall(params: {
+        requestId?: string;
+        toolName: string;
+        provider: string;
+        request: {
+            arguments: any;
+            endpoint?: string;
+            method?: string;
+        };
+        response: {
+            success: boolean;
+            data?: any;
+            error?: string;
+        };
+        duration: number;
+        botId?: string;
+        discussionId?: string;
+        workspaceId?: string;
+    }): string;
+    /**
+     * Logs system-level events related to agent operations
+     *
+     * Captures infrastructure events such as agent initialization, shutdown,
+     * configuration changes, and other system-level activities that affect
+     * agent behavior but aren't directly part of user conversations.
+     *
+     * @param params - System event details
+     * @param params.success - Whether the system operation succeeded
+     * @param params.message - Human-readable description of the event
+     * @param params.details - Additional technical details about the event
+     * @param params.error - Error information if the operation failed
+     *
+     * @example
+     * ```typescript
+     * agentTracker.logSystem({
+     *   success: true,
+     *   message: 'Agent client initialized',
+     *   details: 'Connected to MCP server with 5 tools available'
+     * });
+     * ```
+     */
+    logSystem(params: {
+        success: boolean;
+        message: string;
+        details?: string;
+        error?: string;
+    }): void;
+    /**
+     * Retrieves recent agent activity entries for monitoring and debugging
+     *
+     * Returns the most recent log entries in chronological order (newest last).
+     * Useful for real-time monitoring dashboards and recent activity analysis.
+     *
+     * @param limit - Maximum number of entries to return (default: 10)
+     * @returns Array of recent agent log entries
+     *
+     * @example
+     * ```typescript
+     * const recentActivity = agentTracker.getRecentActivity(20);
+     * console.log(`Found ${recentActivity.length} recent events`);
+     * ```
+     */
+    getRecentActivity(limit?: number): AgentLogEntry[];
+    /**
+     * Retrieves recent tool call logs for analysis and debugging
+     *
+     * Filters the log entries to return only tool call events, providing
+     * focused visibility into agent decision-making and API usage patterns.
+     *
+     * @param limit - Maximum number of tool call entries to return (default: 50)
+     * @returns Array of recent tool call log entries
+     *
+     * @example
+     * ```typescript
+     * const recentToolCalls = agentTracker.getRecentToolCalls(100);
+     * const failedCalls = recentToolCalls.filter(call => !call.toolCall.response.success);
+     * ```
+     */
+    getRecentToolCalls(limit?: number): AgentToolCallLog[];
+    /**
+     * Generates comprehensive statistics about agent activity and performance
+     *
+     * Analyzes all logged events to provide business intelligence metrics including
+     * success rates, performance trends, usage patterns, and identifying top
+     * performers. Essential for monitoring agent effectiveness and optimization.
+     *
+     * @returns Comprehensive statistics object with performance and usage metrics
+     *
+     * @example
+     * ```typescript
+     * const stats = agentTracker.getStats();
+     * console.log(`Success rate: ${stats.successRate}%`);
+     * console.log(`Average response time: ${stats.averageResponseTime}ms`);
+     * console.log(`Most active agent: ${stats.mostActiveBot}`);
+     * console.log(`Most used tool: ${stats.mostUsedTool}`);
+     * ```
+     */
+    getStats(): {
+        /** Total number of agent trigger events */
+        totalTriggers: number;
+        /** Total number of agent completion events */
+        totalCompletions: number;
+        /** Total number of tool calls made by agents */
+        totalToolCalls: number;
+        /** Percentage of successful agent completions (0-100) */
+        successRate: number;
+        /** Average response time in milliseconds */
+        averageResponseTime: number;
+        /** ID of the most frequently triggered agent */
+        mostActiveBot: string | null;
+        /** Number of system-level events logged */
+        systemEvents: number;
+        /** Name of the most frequently used tool */
+        mostUsedTool: string | null;
+    };
+}
+/**
+ * Factory function to create a new AgentTracker instance
+ *
+ * Provides a clean way to instantiate agent trackers with dependency injection.
+ * Follows modern patterns and makes testing easier by allowing logger mocking.
+ *
+ * @param logger - Optional logger instance for operational logging
+ * @param logDir - Directory where agent activity logs will be stored
+ * @param maxEntries - Maximum number of log entries before rotation
+ * @returns A new AgentTracker instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const agentTracker = createAgentTracker();
+ *
+ * // With custom logger
+ * const logger = createLogger({ component: 'my-service' });
+ * const agentTracker = createAgentTracker(logger);
+ *
+ * // With custom configuration
+ * const agentTracker = createAgentTracker(logger, '/var/log/agents', 5000);
+ * ```
+ */
+export declare function createAgentTracker(logger?: Logger, logDir?: string, maxEntries?: number): AgentTracker;
+//# sourceMappingURL=agent-tracker.d.ts.map