@hailer/mcp 0.0.1

package/dist/client/token-tracker.js

@@ -0,0 +1,457 @@
+"use strict";
+/**
+ * Token Usage Tracker
+ *
+ * Dedicated tracking system for token usage and costs across all bots.
+ * Optimized for both human readability and LLM analysis.
+ *
+ * Use Cases:
+ * - Monitor per-bot token budgets
+ * - Identify expensive tools/operations
+ * - Feed data to optimizer agents
+ * - Generate cost reports
+ */
+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.TokenTracker = void 0;
+exports.createTokenTracker = createTokenTracker;
+const logger_1 = require("../lib/logger");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * Token Usage Tracker
+ *
+ * Tracks token usage across all bots and tools for cost optimization.
+ * Data is stored in a structured format for easy analysis by humans and agents.
+ *
+ * @example
+ * ```typescript
+ * const tracker = new TokenTracker();
+ *
+ * // Log bot activity
+ * tracker.logUsage({
+ *   botId: 'bot_sales_789',
+ *   botName: 'Sales Bot',
+ *   provider: 'anthropic',
+ *   conversationId: 'disc_123',
+ *   toolsCalled: ['list_activities', 'create_activity'],
+ *   tokens: {
+ *     input: 24567,
+ *     output: 412,
+ *     total: 24979,
+ *     cacheRead: 22000,
+ *     cost: 0.038
+ *   },
+ *   duration: 2450,
+ *   success: true
+ * });
+ *
+ * // Query for analyzer agent
+ * const botUsage = tracker.getBotUsage('bot_sales_789');
+ * const expensiveTools = tracker.getMostExpensiveTools(5);
+ * ```
+ */
+class TokenTracker {
+    logger;
+    dataFilePath;
+    data;
+    maxRecentEvents = 100;
+    maxDailySummaries = 90; // Keep 90 days
+    constructor(logger, logDir = 'logs') {
+        this.logger = logger || (0, logger_1.createLogger)({ component: 'token-tracker' });
+        this.dataFilePath = path.join(logDir, 'token-usage.json');
+        // Initialize or load existing data
+        this.data = this.loadData();
+        this.logger.info('Token tracker initialized', {
+            dataFile: this.dataFilePath,
+            totalBots: this.data.summary.totalBots,
+            totalCost: this.data.summary.totalCost,
+        });
+    }
+    /**
+     * Load existing data or initialize new structure
+     */
+    loadData() {
+        try {
+            if (fs.existsSync(this.dataFilePath)) {
+                const fileContent = fs.readFileSync(this.dataFilePath, 'utf8');
+                const data = JSON.parse(fileContent);
+                this.logger.info('Loaded existing token usage data', {
+                    totalCost: data.summary.totalCost,
+                    totalConversations: data.summary.totalConversations,
+                });
+                return data;
+            }
+        }
+        catch (error) {
+            this.logger.error('Failed to load token usage data, initializing new', error);
+        }
+        // Initialize new data structure
+        return {
+            summary: {
+                totalCost: 0,
+                totalTokens: 0,
+                totalConversations: 0,
+                totalBots: 0,
+                totalTools: 0,
+                mostExpensiveBot: null,
+                mostExpensiveTool: null,
+                period: {
+                    start: new Date().toISOString().split('T')[0],
+                    end: new Date().toISOString().split('T')[0],
+                },
+                lastUpdated: new Date().toISOString(),
+            },
+            bots: {},
+            tools: {},
+            dailySummaries: [],
+            recentEvents: [],
+        };
+    }
+    /**
+     * Save data to disk
+     */
+    saveData() {
+        try {
+            // Ensure directory exists
+            const dir = path.dirname(this.dataFilePath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            // Update last updated timestamp
+            this.data.summary.lastUpdated = new Date().toISOString();
+            // Write with pretty formatting for human readability
+            fs.writeFileSync(this.dataFilePath, JSON.stringify(this.data, null, 2), 'utf8');
+        }
+        catch (error) {
+            this.logger.error('Failed to save token usage data', error);
+        }
+    }
+    /**
+     * Log a token usage event from a bot interaction
+     */
+    logUsage(event) {
+        const fullEvent = {
+            ...event,
+            timestamp: new Date().toISOString(),
+        };
+        try {
+            // Add to recent events (with rotation)
+            this.data.recentEvents.push(fullEvent);
+            if (this.data.recentEvents.length > this.maxRecentEvents) {
+                this.data.recentEvents.shift();
+            }
+            // Update bot statistics
+            this.updateBotStats(fullEvent);
+            // Update tool statistics
+            this.updateToolStats(fullEvent);
+            // Update daily summary
+            this.updateDailySummary(fullEvent);
+            // Update global summary
+            this.updateGlobalSummary(fullEvent);
+            // Save to disk
+            this.saveData();
+            this.logger.info('Token usage logged', {
+                botId: event.botId,
+                cost: event.tokens.cost,
+                tokens: event.tokens.total,
+                tools: event.toolsCalled.length,
+            });
+        }
+        catch (error) {
+            this.logger.error('Failed to log token usage', error, {
+                botId: event.botId,
+            });
+        }
+    }
+    /**
+     * Update per-bot statistics
+     */
+    updateBotStats(event) {
+        const { botId, botName, tokens, toolsCalled } = event;
+        if (!this.data.bots[botId]) {
+            // Initialize new bot
+            this.data.bots[botId] = {
+                botId,
+                botName,
+                totalCost: 0,
+                totalTokens: 0,
+                conversations: 0,
+                averageCostPerConversation: 0,
+                averageTokensPerConversation: 0,
+                tools: {},
+                firstSeen: event.timestamp,
+                lastSeen: event.timestamp,
+            };
+            this.data.summary.totalBots++;
+        }
+        const bot = this.data.bots[botId];
+        // Update totals
+        bot.totalCost += tokens.cost;
+        bot.totalTokens += tokens.total;
+        bot.conversations++;
+        bot.lastSeen = event.timestamp;
+        // Update averages
+        bot.averageCostPerConversation = bot.totalCost / bot.conversations;
+        bot.averageTokensPerConversation = bot.totalTokens / bot.conversations;
+        // Update cache efficiency (if applicable)
+        if (tokens.cacheRead !== undefined || tokens.cacheCreation !== undefined) {
+            if (!bot.cacheEfficiency) {
+                bot.cacheEfficiency = {
+                    totalCacheRead: 0,
+                    totalCacheCreation: 0,
+                    savingsPercent: 0,
+                };
+            }
+            bot.cacheEfficiency.totalCacheRead += tokens.cacheRead || 0;
+            bot.cacheEfficiency.totalCacheCreation += tokens.cacheCreation || 0;
+            const totalInput = bot.totalTokens;
+            const cacheReads = bot.cacheEfficiency.totalCacheRead;
+            bot.cacheEfficiency.savingsPercent = totalInput > 0
+                ? Math.round((cacheReads / totalInput) * 100)
+                : 0;
+        }
+        // Update per-tool stats within this bot
+        for (const toolName of toolsCalled) {
+            if (!bot.tools[toolName]) {
+                bot.tools[toolName] = {
+                    calls: 0,
+                    tokens: 0,
+                    cost: 0,
+                };
+            }
+            const toolStat = bot.tools[toolName];
+            toolStat.calls++;
+            // Distribute tokens/cost evenly across tools (approximation)
+            toolStat.tokens += Math.round(tokens.total / toolsCalled.length);
+            toolStat.cost += tokens.cost / toolsCalled.length;
+        }
+    }
+    /**
+     * Update per-tool statistics
+     */
+    updateToolStats(event) {
+        const { botId, tokens, toolsCalled } = event;
+        for (const toolName of toolsCalled) {
+            if (!this.data.tools[toolName]) {
+                this.data.tools[toolName] = {
+                    toolName,
+                    totalCost: 0,
+                    totalTokens: 0,
+                    calls: 0,
+                    averageCostPerCall: 0,
+                    averageTokensPerCall: 0,
+                    usedByBots: [],
+                };
+                this.data.summary.totalTools++;
+            }
+            const tool = this.data.tools[toolName];
+            // Update totals (distribute evenly across tools)
+            tool.calls++;
+            tool.totalTokens += Math.round(tokens.total / toolsCalled.length);
+            tool.totalCost += tokens.cost / toolsCalled.length;
+            // Update averages
+            tool.averageCostPerCall = tool.totalCost / tool.calls;
+            tool.averageTokensPerCall = tool.totalTokens / tool.calls;
+            // Track which bots use this tool
+            if (!tool.usedByBots.includes(botId)) {
+                tool.usedByBots.push(botId);
+            }
+        }
+    }
+    /**
+     * Update daily summary
+     */
+    updateDailySummary(event) {
+        const date = event.timestamp.split('T')[0]; // YYYY-MM-DD
+        let daily = this.data.dailySummaries.find(d => d.date === date);
+        if (!daily) {
+            daily = {
+                date,
+                cost: 0,
+                tokens: 0,
+                conversations: 0,
+                uniqueBots: 0,
+                topBot: '',
+                topTool: '',
+            };
+            this.data.dailySummaries.push(daily);
+            // Sort by date and trim old entries
+            this.data.dailySummaries.sort((a, b) => a.date.localeCompare(b.date));
+            if (this.data.dailySummaries.length > this.maxDailySummaries) {
+                this.data.dailySummaries.shift();
+            }
+        }
+        daily.cost += event.tokens.cost;
+        daily.tokens += event.tokens.total;
+        daily.conversations++;
+        // Update period range
+        if (date < this.data.summary.period.start) {
+            this.data.summary.period.start = date;
+        }
+        if (date > this.data.summary.period.end) {
+            this.data.summary.period.end = date;
+        }
+    }
+    /**
+     * Update global summary statistics
+     */
+    updateGlobalSummary(event) {
+        this.data.summary.totalCost += event.tokens.cost;
+        this.data.summary.totalTokens += event.tokens.total;
+        this.data.summary.totalConversations++;
+        // Find most expensive bot
+        let maxBotCost = 0;
+        let maxBotId = null;
+        for (const [botId, bot] of Object.entries(this.data.bots)) {
+            if (bot.totalCost > maxBotCost) {
+                maxBotCost = bot.totalCost;
+                maxBotId = botId;
+            }
+        }
+        this.data.summary.mostExpensiveBot = maxBotId;
+        // Find most expensive tool
+        let maxToolCost = 0;
+        let maxToolName = null;
+        for (const [toolName, tool] of Object.entries(this.data.tools)) {
+            if (tool.totalCost > maxToolCost) {
+                maxToolCost = tool.totalCost;
+                maxToolName = toolName;
+            }
+        }
+        this.data.summary.mostExpensiveTool = maxToolName;
+    }
+    /**
+     * Get usage statistics for a specific bot
+     * Useful for analyzer agents to investigate specific bots
+     */
+    getBotUsage(botId) {
+        return this.data.bots[botId] || null;
+    }
+    /**
+     * Get usage statistics for a specific tool
+     */
+    getToolUsage(toolName) {
+        return this.data.tools[toolName] || null;
+    }
+    /**
+     * Get N most expensive bots
+     */
+    getMostExpensiveBots(limit = 5) {
+        return Object.values(this.data.bots)
+            .sort((a, b) => b.totalCost - a.totalCost)
+            .slice(0, limit);
+    }
+    /**
+     * Get N most expensive tools
+     */
+    getMostExpensiveTools(limit = 5) {
+        return Object.values(this.data.tools)
+            .sort((a, b) => b.totalCost - a.totalCost)
+            .slice(0, limit);
+    }
+    /**
+     * Get daily summaries for a date range
+     */
+    getDailySummaries(startDate, endDate) {
+        let summaries = this.data.dailySummaries;
+        if (startDate) {
+            summaries = summaries.filter(s => s.date >= startDate);
+        }
+        if (endDate) {
+            summaries = summaries.filter(s => s.date <= endDate);
+        }
+        return summaries;
+    }
+    /**
+     * Get full data dump for analyzer agents
+     * This gives the agent complete context
+     */
+    getFullData() {
+        return this.data;
+    }
+    /**
+     * Get summary statistics
+     */
+    getSummary() {
+        return this.data.summary;
+    }
+    /**
+     * Generate human-readable report
+     */
+    generateReport() {
+        const { summary, bots, tools } = this.data;
+        const report = `
+Token Usage Report
+==================
+Period: ${summary.period.start} to ${summary.period.end}
+Last Updated: ${summary.lastUpdated}
+
+OVERALL SUMMARY
+---------------
+Total Cost: $${summary.totalCost.toFixed(2)}
+Total Tokens: ${summary.totalTokens.toLocaleString()}
+Total Conversations: ${summary.totalConversations}
+Active Bots: ${summary.totalBots}
+Tools Used: ${summary.totalTools}
+
+TOP CONSUMERS
+-------------
+Most Expensive Bot: ${summary.mostExpensiveBot || 'N/A'}
+Most Expensive Tool: ${summary.mostExpensiveTool || 'N/A'}
+
+TOP 5 BOTS BY COST
+------------------
+${this.getMostExpensiveBots(5).map((bot, i) => `${i + 1}. ${bot.botName || bot.botId}: $${bot.totalCost.toFixed(2)} (${bot.conversations} conversations)`).join('\n')}
+
+TOP 5 TOOLS BY COST
+-------------------
+${this.getMostExpensiveTools(5).map((tool, i) => `${i + 1}. ${tool.toolName}: $${tool.totalCost.toFixed(2)} (${tool.calls} calls)`).join('\n')}
+
+RECENT DAILY USAGE
+------------------
+${this.data.dailySummaries.slice(-7).map(day => `${day.date}: $${day.cost.toFixed(2)} (${day.conversations} conversations)`).join('\n')}
+`;
+        return report;
+    }
+}
+exports.TokenTracker = TokenTracker;
+/**
+ * Factory function to create a new TokenTracker instance
+ */
+function createTokenTracker(logger, logDir) {
+    return new TokenTracker(logger, logDir);
+}
+//# sourceMappingURL=token-tracker.js.map

package/dist/client/token-usage-bot.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Token Usage Bot
+ *
+ * Monitors token usage and posts summaries to discussions.
+ * Can respond to queries about token costs and usage details.
+ */
+import { TokenTracker } from './token-tracker';
+import { AgentTracker } from './agent-tracker';
+export interface TokenUsageBotConfig {
+    enabled: boolean;
+    postSummaryAfterConversation: boolean;
+    minCostThreshold?: number;
+}
+export declare class TokenUsageBot {
+    private tokenTracker;
+    private agentTracker;
+    private config;
+    private lastPostedConversation;
+    constructor(tokenTracker: TokenTracker, agentTracker: AgentTracker, config: TokenUsageBotConfig);
+    /**
+     * Generate a summary message for the last conversation in a discussion
+     */
+    generateSummary(discussionId: string, conversationCost: number, conversationTokens: number): Promise<string>;
+    /**
+     * Format a concise summary message
+     */
+    private formatSummaryMessage;
+    /**
+     * Generate detailed token usage report
+     */
+    generateDetailedReport(discussionId?: string): string;
+    /**
+     * Check if message is asking for token details
+     */
+    isTokenQuery(messageContent: string): boolean;
+    /**
+     * Should post summary after this conversation?
+     */
+    shouldPostSummary(discussionId: string, cost: number): boolean;
+    /**
+     * Mark that we posted a summary for this discussion
+     */
+    markPosted(discussionId: string): void;
+    /**
+     * Get token tracker instance
+     */
+    getTokenTracker(): TokenTracker;
+}
+/**
+ * Factory function to create TokenUsageBot
+ */
+export declare function createTokenUsageBot(tokenTracker: TokenTracker, agentTracker: AgentTracker, config: TokenUsageBotConfig): TokenUsageBot;
+//# sourceMappingURL=token-usage-bot.d.ts.map

package/dist/client/token-usage-bot.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * Token Usage Bot
+ *
+ * Monitors token usage and posts summaries to discussions.
+ * Can respond to queries about token costs and usage details.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenUsageBot = void 0;
+exports.createTokenUsageBot = createTokenUsageBot;
+const logger_1 = require("../lib/logger");
+const logger = (0, logger_1.createLogger)({ component: 'token-usage-bot' });
+class TokenUsageBot {
+    tokenTracker;
+    agentTracker;
+    config;
+    lastPostedConversation = new Map(); // discussionId -> timestamp
+    constructor(tokenTracker, agentTracker, config) {
+        this.tokenTracker = tokenTracker;
+        this.agentTracker = agentTracker;
+        this.config = {
+            minCostThreshold: 0.01,
+            ...config
+        };
+        if (this.config.enabled) {
+            logger.info('Token Usage Bot initialized', {
+                postSummaries: this.config.postSummaryAfterConversation,
+                minThreshold: this.config.minCostThreshold
+            });
+        }
+    }
+    /**
+     * Generate a summary message for the last conversation in a discussion
+     */
+    async generateSummary(discussionId, conversationCost, conversationTokens) {
+        const summary = this.tokenTracker.getSummary();
+        const recentEvents = this.tokenTracker.getFullData().recentEvents.filter(e => e.conversationId === discussionId);
+        if (recentEvents.length === 0) {
+            return `💰 **Token Usage Summary**\n\nNo recent token data available for this conversation.`;
+        }
+        // Get the most recent event for this discussion
+        const lastEvent = recentEvents[recentEvents.length - 1];
+        return this.formatSummaryMessage(lastEvent, conversationCost, conversationTokens);
+    }
+    /**
+     * Format a concise summary message
+     */
+    formatSummaryMessage(event, cost, tokens) {
+        const cacheInfo = event.tokens.cacheRead > 0
+            ? ` (${event.tokens.cacheRead.toLocaleString()} cached)`
+            : '';
+        return `💰 **Token Usage**
+Cost: $${cost.toFixed(4)} | Tokens: ${tokens.toLocaleString()}${cacheInfo}
+Tools: ${event.toolsCalled.length > 0 ? event.toolsCalled.join(', ') : 'none'}`;
+    }
+    /**
+     * Generate detailed token usage report
+     */
+    generateDetailedReport(discussionId) {
+        const summary = this.tokenTracker.getSummary();
+        const data = this.tokenTracker.getFullData();
+        let report = `📊 **Detailed Token Usage Report**\n\n`;
+        if (discussionId) {
+            // Filter for specific discussion
+            const discussionEvents = data.recentEvents.filter(e => e.conversationId === discussionId);
+            const discussionCost = discussionEvents.reduce((sum, e) => sum + e.tokens.cost, 0);
+            const discussionTokens = discussionEvents.reduce((sum, e) => sum + e.tokens.total, 0);
+            report += `**This Conversation:**\n`;
+            report += `- Total Cost: $${discussionCost.toFixed(4)}\n`;
+            report += `- Total Tokens: ${discussionTokens.toLocaleString()}\n`;
+            report += `- Messages: ${discussionEvents.length}\n`;
+            report += `- Avg per message: $${(discussionCost / discussionEvents.length).toFixed(4)}\n\n`;
+            // Show last 5 events
+            report += `**Recent Messages:**\n`;
+            discussionEvents.slice(-5).forEach((event, i) => {
+                report += `${i + 1}. $${event.tokens.cost.toFixed(4)} - ${event.tokens.total.toLocaleString()} tokens`;
+                if (event.toolsCalled.length > 0) {
+                    report += ` - Tools: ${event.toolsCalled.slice(0, 3).join(', ')}`;
+                    if (event.toolsCalled.length > 3)
+                        report += `...`;
+                }
+                report += `\n`;
+            });
+            report += `\n`;
+        }
+        // Overall stats
+        report += `**Overall Stats:**\n`;
+        report += `- Total Cost: $${summary.totalCost.toFixed(2)}\n`;
+        report += `- Total Tokens: ${summary.totalTokens.toLocaleString()}\n`;
+        report += `- Total Conversations: ${summary.totalConversations}\n`;
+        report += `- Avg per conversation: $${(summary.totalCost / summary.totalConversations).toFixed(4)}\n\n`;
+        // Top tools
+        const topTools = this.tokenTracker.getMostExpensiveTools(5);
+        if (topTools.length > 0) {
+            report += `**Most Expensive Tools:**\n`;
+            topTools.forEach((tool, i) => {
+                report += `${i + 1}. ${tool.toolName}: $${tool.totalCost.toFixed(4)} (${tool.calls} calls)\n`;
+            });
+        }
+        return report;
+    }
+    /**
+     * Check if message is asking for token details
+     */
+    isTokenQuery(messageContent) {
+        const lower = messageContent.toLowerCase();
+        return (lower.includes('token') && (lower.includes('usage') ||
+            lower.includes('cost') ||
+            lower.includes('price') ||
+            lower.includes('detail') ||
+            lower.includes('report') ||
+            lower.includes('how much') ||
+            lower.includes('expensive')));
+    }
+    /**
+     * Should post summary after this conversation?
+     */
+    shouldPostSummary(discussionId, cost) {
+        if (!this.config.enabled || !this.config.postSummaryAfterConversation) {
+            return false;
+        }
+        // Check cost threshold
+        if (cost < (this.config.minCostThreshold || 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 token tracker instance
+     */
+    getTokenTracker() {
+        return this.tokenTracker;
+    }
+}
+exports.TokenUsageBot = TokenUsageBot;
+/**
+ * Factory function to create TokenUsageBot
+ */
+function createTokenUsageBot(tokenTracker, agentTracker, config) {
+    return new TokenUsageBot(tokenTracker, agentTracker, config);
+}
+//# sourceMappingURL=token-usage-bot.js.map