@hailer/mcp 0.0.1

package/dist/client/token-pricing.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Token Pricing Utility
+ *
+ * Calculates cost estimates for LLM API usage based on token consumption.
+ * Pricing data is accurate as of January 2025 and should be updated periodically.
+ *
+ * Anthropic pricing: https://www.anthropic.com/pricing
+ * OpenAI pricing: https://openai.com/pricing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateTokenCost = calculateTokenCost;
+/**
+ * Pricing table for supported models
+ * All prices are per 1 million tokens in USD
+ */
+const MODEL_PRICING = {
+    // Anthropic Claude models
+    'claude-3-5-sonnet-20241022': {
+        input: 3.00,
+        output: 15.00,
+        cacheWrite: 3.75,
+        cacheRead: 0.30,
+    },
+    'claude-3-5-sonnet-20240620': {
+        input: 3.00,
+        output: 15.00,
+        cacheWrite: 3.75,
+        cacheRead: 0.30,
+    },
+    'claude-sonnet-4-20250514': {
+        input: 3.00,
+        output: 15.00,
+        cacheWrite: 3.75,
+        cacheRead: 0.30,
+    },
+    'claude-3-5-haiku-20241022': {
+        input: 0.80,
+        output: 4.00,
+        cacheWrite: 1.00,
+        cacheRead: 0.08,
+    },
+    'claude-3-opus-20240229': {
+        input: 15.00,
+        output: 75.00,
+        cacheWrite: 18.75,
+        cacheRead: 1.50,
+    },
+    // OpenAI GPT-4 models
+    'gpt-4o': {
+        input: 2.50,
+        output: 10.00,
+    },
+    'gpt-4o-mini': {
+        input: 0.15,
+        output: 0.60,
+    },
+    'gpt-4-turbo': {
+        input: 10.00,
+        output: 30.00,
+    },
+    'gpt-4': {
+        input: 30.00,
+        output: 60.00,
+    },
+    // Default fallback pricing (conservative estimate)
+    'default': {
+        input: 3.00,
+        output: 15.00,
+    },
+};
+/**
+ * Normalize model name to match pricing table
+ * Handles version suffixes and aliases
+ */
+function normalizeModelName(model) {
+    const normalized = model.toLowerCase();
+    // Check for exact match first
+    if (MODEL_PRICING[normalized]) {
+        return normalized;
+    }
+    // Check for partial matches (e.g., "claude-3-5-sonnet" matches "claude-3-5-sonnet-20241022")
+    for (const pricingModel of Object.keys(MODEL_PRICING)) {
+        if (normalized.includes(pricingModel) || pricingModel.includes(normalized)) {
+            return pricingModel;
+        }
+    }
+    return 'default';
+}
+/**
+ * Calculate the cost of token usage for a specific model
+ *
+ * @param usage - Token usage from API response
+ * @param model - Model identifier (e.g., "claude-sonnet-4-20250514")
+ * @returns Estimated cost in USD
+ *
+ * @example
+ * ```typescript
+ * const usage = {
+ *   input_tokens: 24567,
+ *   output_tokens: 412,
+ *   cache_read_input_tokens: 22000
+ * };
+ * const cost = calculateTokenCost(usage, 'claude-sonnet-4-20250514');
+ * // Returns: 0.038
+ * ```
+ */
+function calculateTokenCost(usage, model) {
+    const modelKey = normalizeModelName(model);
+    const pricing = MODEL_PRICING[modelKey];
+    // Base input/output costs
+    const inputCost = (usage.input_tokens / 1_000_000) * pricing.input;
+    const outputCost = (usage.output_tokens / 1_000_000) * pricing.output;
+    // Cache costs (if applicable)
+    let cacheWriteCost = 0;
+    let cacheReadCost = 0;
+    if (usage.cache_creation_input_tokens && pricing.cacheWrite) {
+        cacheWriteCost = (usage.cache_creation_input_tokens / 1_000_000) * pricing.cacheWrite;
+    }
+    if (usage.cache_read_input_tokens && pricing.cacheRead) {
+        cacheReadCost = (usage.cache_read_input_tokens / 1_000_000) * pricing.cacheRead;
+    }
+    const totalCost = inputCost + outputCost + cacheWriteCost + cacheReadCost;
+    // Round to 4 decimal places (tenth of a cent)
+    return Math.round(totalCost * 10000) / 10000;
+}
+//# sourceMappingURL=token-pricing.js.map

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

@@ -0,0 +1,232 @@
+/**
+ * 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
+ */
+import { Logger } from '../lib/logger';
+/**
+ * Token usage event - raw data point
+ */
+export interface TokenUsageEvent {
+    timestamp: string;
+    botId: string;
+    botName?: string;
+    provider: string;
+    conversationId: string;
+    toolsCalled: string[];
+    tokens: {
+        input: number;
+        output: number;
+        total: number;
+        cacheCreation?: number;
+        cacheRead?: number;
+        cost: number;
+    };
+    duration: number;
+    success: boolean;
+}
+/**
+ * Per-bot usage statistics
+ */
+export interface BotUsageStats {
+    botId: string;
+    botName?: string;
+    totalCost: number;
+    totalTokens: number;
+    conversations: number;
+    averageCostPerConversation: number;
+    averageTokensPerConversation: number;
+    tools: Record<string, {
+        calls: number;
+        tokens: number;
+        cost: number;
+    }>;
+    cacheEfficiency?: {
+        totalCacheRead: number;
+        totalCacheCreation: number;
+        savingsPercent: number;
+    };
+    firstSeen: string;
+    lastSeen: string;
+}
+/**
+ * Per-tool usage statistics
+ */
+export interface ToolUsageStats {
+    toolName: string;
+    totalCost: number;
+    totalTokens: number;
+    calls: number;
+    averageCostPerCall: number;
+    averageTokensPerCall: number;
+    usedByBots: string[];
+}
+/**
+ * Daily usage summary
+ */
+export interface DailySummary {
+    date: string;
+    cost: number;
+    tokens: number;
+    conversations: number;
+    uniqueBots: number;
+    topBot: string;
+    topTool: string;
+}
+/**
+ * Root token usage data structure
+ * Optimized for LLM consumption and human readability
+ */
+export interface TokenUsageData {
+    /** High-level summary for quick overview */
+    summary: {
+        totalCost: number;
+        totalTokens: number;
+        totalConversations: number;
+        totalBots: number;
+        totalTools: number;
+        mostExpensiveBot: string | null;
+        mostExpensiveTool: string | null;
+        period: {
+            start: string;
+            end: string;
+        };
+        lastUpdated: string;
+    };
+    /** Per-bot detailed statistics */
+    bots: Record<string, BotUsageStats>;
+    /** Per-tool detailed statistics */
+    tools: Record<string, ToolUsageStats>;
+    /** Daily rollup summaries for trend analysis */
+    dailySummaries: DailySummary[];
+    /** Recent events (last 100) for context */
+    recentEvents: TokenUsageEvent[];
+}
+/**
+ * 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);
+ * ```
+ */
+export declare class TokenTracker {
+    private logger;
+    private dataFilePath;
+    private data;
+    private maxRecentEvents;
+    private maxDailySummaries;
+    constructor(logger?: Logger, logDir?: string);
+    /**
+     * Load existing data or initialize new structure
+     */
+    private loadData;
+    /**
+     * Save data to disk
+     */
+    private saveData;
+    /**
+     * Log a token usage event from a bot interaction
+     */
+    logUsage(event: Omit<TokenUsageEvent, 'timestamp'>): void;
+    /**
+     * Update per-bot statistics
+     */
+    private updateBotStats;
+    /**
+     * Update per-tool statistics
+     */
+    private updateToolStats;
+    /**
+     * Update daily summary
+     */
+    private updateDailySummary;
+    /**
+     * Update global summary statistics
+     */
+    private updateGlobalSummary;
+    /**
+     * Get usage statistics for a specific bot
+     * Useful for analyzer agents to investigate specific bots
+     */
+    getBotUsage(botId: string): BotUsageStats | null;
+    /**
+     * Get usage statistics for a specific tool
+     */
+    getToolUsage(toolName: string): ToolUsageStats | null;
+    /**
+     * Get N most expensive bots
+     */
+    getMostExpensiveBots(limit?: number): BotUsageStats[];
+    /**
+     * Get N most expensive tools
+     */
+    getMostExpensiveTools(limit?: number): ToolUsageStats[];
+    /**
+     * Get daily summaries for a date range
+     */
+    getDailySummaries(startDate?: string, endDate?: string): DailySummary[];
+    /**
+     * Get full data dump for analyzer agents
+     * This gives the agent complete context
+     */
+    getFullData(): TokenUsageData;
+    /**
+     * Get summary statistics
+     */
+    getSummary(): {
+        totalCost: number;
+        totalTokens: number;
+        totalConversations: number;
+        totalBots: number;
+        totalTools: number;
+        mostExpensiveBot: string | null;
+        mostExpensiveTool: string | null;
+        period: {
+            start: string;
+            end: string;
+        };
+        lastUpdated: string;
+    };
+    /**
+     * Generate human-readable report
+     */
+    generateReport(): string;
+}
+/**
+ * Factory function to create a new TokenTracker instance
+ */
+export declare function createTokenTracker(logger?: Logger, logDir?: string): TokenTracker;
+//# sourceMappingURL=token-tracker.d.ts.map