@hailer/mcp 0.0.1

package/dist/client/agent-tracker.js

@@ -0,0 +1,659 @@
+"use strict";
+/**
+ * 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.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentTracker = void 0;
+exports.createAgentTracker = createAgentTracker;
+const logger_1 = require("../lib/logger");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * 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
+ * });
+ * ```
+ */
+class AgentTracker {
+    logger;
+    logFilePath;
+    maxEntries;
+    isProduction;
+    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, logDir = 'logs', maxEntries = 1000) {
+        this.logger = logger || (0, logger_1.createLogger)({ component: 'agent-tracker' });
+        this.maxEntries = maxEntries;
+        this.isProduction = process.env.NODE_ENV === 'production';
+        // Only enable JSON file tracking in development or when explicitly enabled
+        this.isTrackingEnabled = !this.isProduction || process.env.AGENT_TRACKING_ENABLED === 'true';
+        if (this.isTrackingEnabled) {
+            this.logFilePath = path.join(logDir, 'agent-activity.json');
+            this.initializeLogFile();
+        }
+        else {
+            this.logger.info('Agent activity tracking disabled in production environment');
+        }
+    }
+    /**
+     * 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
+     */
+    initializeLogFile() {
+        if (!this.isTrackingEnabled || !this.logFilePath) {
+            return;
+        }
+        try {
+            // Ensure log directory exists
+            const logDir = path.dirname(this.logFilePath);
+            if (!fs.existsSync(logDir)) {
+                fs.mkdirSync(logDir, { recursive: true });
+            }
+            if (!fs.existsSync(this.logFilePath)) {
+                const initialLog = { entries: [] };
+                fs.writeFileSync(this.logFilePath, JSON.stringify(initialLog, null, 2));
+                this.logger.info('Agent activity tracker initialized', {
+                    logFile: this.logFilePath,
+                    maxEntries: this.maxEntries
+                });
+            }
+        }
+        catch (error) {
+            this.logger.error('Failed to initialize agent activity log file', error, {
+                logFilePath: this.logFilePath
+            });
+        }
+    }
+    /**
+     * 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
+     */
+    readLogFile() {
+        if (!this.isTrackingEnabled || !this.logFilePath) {
+            return { entries: [] };
+        }
+        try {
+            const data = fs.readFileSync(this.logFilePath, 'utf8');
+            return JSON.parse(data);
+        }
+        catch (error) {
+            this.logger.error('Failed to read agent activity log file', error, {
+                logFilePath: this.logFilePath
+            });
+            return { entries: [] };
+        }
+    }
+    /**
+     * 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
+     */
+    writeLogFile(log) {
+        if (!this.isTrackingEnabled || !this.logFilePath) {
+            return;
+        }
+        try {
+            // Rotate entries if we exceed max limit
+            if (log.entries.length > this.maxEntries) {
+                const removedCount = log.entries.length - this.maxEntries;
+                log.entries = log.entries.slice(-this.maxEntries);
+                this.logger.debug('Agent activity log rotated', {
+                    removedEntries: removedCount,
+                    remainingEntries: log.entries.length
+                });
+            }
+            fs.writeFileSync(this.logFilePath, JSON.stringify(log, null, 2));
+        }
+        catch (error) {
+            this.logger.error('Failed to write agent activity log file', error, {
+                logFilePath: this.logFilePath,
+                entriesCount: log.entries.length
+            });
+        }
+    }
+    /**
+     * Generates a unique request identifier for correlation
+     *
+     * @private
+     * @returns A unique request ID string
+     */
+    generateRequestId() {
+        return `req-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * 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
+     */
+    truncateText(text, maxLength = 50) {
+        if (text.length <= maxLength)
+            return text;
+        return text.substring(0, maxLength) + '...';
+    }
+    /**
+     * 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) {
+        const requestId = this.generateRequestId();
+        try {
+            const log = this.readLogFile();
+            const triggerEntry = {
+                type: 'trigger',
+                requestId,
+                timestamp: new Date().toISOString(),
+                trigger: {
+                    type: params.triggerType,
+                    discussionId: params.discussionId,
+                    userId: params.userId,
+                    userName: params.userName,
+                    botId: params.botId,
+                    messagePreview: this.truncateText(params.messageContent),
+                    workspaceId: params.workspaceId,
+                }
+            };
+            log.entries.push(triggerEntry);
+            this.writeLogFile(log);
+            this.logger.info('Agent trigger logged', {
+                requestId,
+                triggerType: params.triggerType,
+                botId: params.botId,
+                userId: params.userId,
+                discussionId: params.discussionId
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to log agent trigger event', error, {
+                requestId,
+                triggerType: params.triggerType,
+                botId: params.botId
+            });
+        }
+        return requestId;
+    }
+    /**
+     * 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) {
+        try {
+            const log = this.readLogFile();
+            const completionEntry = {
+                type: 'completion',
+                requestId: params.requestId,
+                timestamp: new Date().toISOString(),
+                completion: {
+                    success: params.success,
+                    provider: params.provider,
+                    toolsCalled: params.toolsCalled || [],
+                    responsePreview: params.responseContent ? this.truncateText(params.responseContent) : undefined,
+                    duration: params.duration,
+                    error: params.error,
+                }
+            };
+            log.entries.push(completionEntry);
+            this.writeLogFile(log);
+            const status = params.success ? 'SUCCESS' : 'FAILED';
+            this.logger.info('Agent completion logged', {
+                requestId: params.requestId,
+                success: params.success,
+                provider: params.provider,
+                toolsCount: params.toolsCalled?.length || 0,
+                duration: params.duration,
+                status
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to log agent completion event', error, {
+                requestId: params.requestId,
+                success: params.success
+            });
+        }
+    }
+    /**
+     * 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) {
+        const requestId = params.requestId || this.generateRequestId();
+        try {
+            const log = this.readLogFile();
+            const toolCallEntry = {
+                type: 'tool_call',
+                requestId,
+                timestamp: new Date().toISOString(),
+                toolCall: {
+                    toolName: params.toolName,
+                    provider: params.provider,
+                    request: params.request,
+                    response: params.response,
+                    duration: params.duration,
+                    botId: params.botId,
+                    discussionId: params.discussionId,
+                    workspaceId: params.workspaceId,
+                }
+            };
+            log.entries.push(toolCallEntry);
+            this.writeLogFile(log);
+            const status = params.response.success ? 'SUCCESS' : 'FAILED';
+            this.logger.info('Agent tool call logged', {
+                requestId,
+                toolName: params.toolName,
+                provider: params.provider,
+                success: params.response.success,
+                duration: params.duration,
+                status
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to log agent tool call', error, {
+                requestId,
+                toolName: params.toolName,
+                provider: params.provider
+            });
+        }
+        return requestId;
+    }
+    /**
+     * 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) {
+        const requestId = this.generateRequestId();
+        try {
+            const log = this.readLogFile();
+            const systemEntry = {
+                type: 'system',
+                requestId,
+                timestamp: new Date().toISOString(),
+                system: {
+                    success: params.success,
+                    message: params.message,
+                    details: params.details,
+                    error: params.error,
+                }
+            };
+            log.entries.push(systemEntry);
+            this.writeLogFile(log);
+            const status = params.success ? 'SUCCESS' : 'FAILED';
+            this.logger.info('Agent system event logged', {
+                requestId,
+                success: params.success,
+                message: params.message,
+                status
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to log agent system event', error, {
+                requestId,
+                message: params.message
+            });
+        }
+    }
+    /**
+     * 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 = 10) {
+        try {
+            const log = this.readLogFile();
+            return log.entries.slice(-limit);
+        }
+        catch (error) {
+            this.logger.error('Failed to get recent agent activity', error, { limit });
+            return [];
+        }
+    }
+    /**
+     * 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 = 50) {
+        try {
+            const log = this.readLogFile();
+            const toolCalls = log.entries.filter(e => e.type === 'tool_call');
+            return toolCalls.slice(-limit);
+        }
+        catch (error) {
+            this.logger.error('Failed to get recent agent tool calls', error, { limit });
+            return [];
+        }
+    }
+    /**
+     * 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() {
+        try {
+            const log = this.readLogFile();
+            const triggers = log.entries.filter(e => e.type === 'trigger');
+            const completions = log.entries.filter(e => e.type === 'completion');
+            const toolCalls = log.entries.filter(e => e.type === 'tool_call');
+            const systemEvents = log.entries.filter(e => e.type === 'system');
+            const successfulCompletions = completions.filter(c => c.completion.success);
+            const successRate = completions.length > 0 ? (successfulCompletions.length / completions.length) * 100 : 0;
+            const averageResponseTime = completions.length > 0
+                ? completions.reduce((sum, c) => sum + c.completion.duration, 0) / completions.length
+                : 0;
+            // Find most active bot
+            const botCounts = new Map();
+            triggers.forEach(t => {
+                const count = botCounts.get(t.trigger.botId) || 0;
+                botCounts.set(t.trigger.botId, count + 1);
+            });
+            let mostActiveBot = null;
+            let maxCount = 0;
+            for (const [botId, count] of botCounts) {
+                if (count > maxCount) {
+                    maxCount = count;
+                    mostActiveBot = botId;
+                }
+            }
+            // Find most used tool
+            const toolCounts = new Map();
+            toolCalls.forEach(t => {
+                const count = toolCounts.get(t.toolCall.toolName) || 0;
+                toolCounts.set(t.toolCall.toolName, count + 1);
+            });
+            let mostUsedTool = null;
+            let maxToolCount = 0;
+            for (const [toolName, count] of toolCounts) {
+                if (count > maxToolCount) {
+                    maxToolCount = count;
+                    mostUsedTool = toolName;
+                }
+            }
+            const stats = {
+                totalTriggers: triggers.length,
+                totalCompletions: completions.length,
+                totalToolCalls: toolCalls.length,
+                successRate: Math.round(successRate * 100) / 100,
+                averageResponseTime: Math.round(averageResponseTime),
+                mostActiveBot,
+                systemEvents: systemEvents.length,
+                mostUsedTool,
+            };
+            this.logger.debug('Agent statistics calculated', stats);
+            return stats;
+        }
+        catch (error) {
+            this.logger.error('Failed to calculate agent statistics', error);
+            return {
+                totalTriggers: 0,
+                totalCompletions: 0,
+                totalToolCalls: 0,
+                successRate: 0,
+                averageResponseTime: 0,
+                mostActiveBot: null,
+                systemEvents: 0,
+                mostUsedTool: null,
+            };
+        }
+    }
+}
+exports.AgentTracker = AgentTracker;
+/**
+ * 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);
+ * ```
+ */
+function createAgentTracker(logger, logDir, maxEntries) {
+    return new AgentTracker(logger, logDir, maxEntries);
+}
+//# sourceMappingURL=agent-tracker.js.map