teleportation-cli 1.0.0

package/lib/router/models.js

@@ -0,0 +1,188 @@
+/**
+ * Model Registry
+ * 
+ * Static model definitions with cost and capability metadata.
+ * This serves as a fallback when the llms.mechdna.net registry is unavailable,
+ * and provides the tier classification logic.
+ * 
+ * Pricing is per 1M tokens (as of Dec 2024).
+ */
+
+// Quality tiers (from llms.mechdna.net)
+export const QUALITY_TIERS = {
+  FLAGSHIP: 'flagship',  // Best quality, highest cost
+  HIGH: 'high',          // Very good quality, moderate-high cost
+  STANDARD: 'standard',  // Good balance of quality and cost
+  FAST: 'fast',          // Optimized for speed, lower cost
+  BUDGET: 'budget'       // Cheapest, acceptable quality for simple tasks
+};
+
+// Map our simple tiers to quality tiers
+export const TIER_TO_QUALITY = {
+  cheap: [QUALITY_TIERS.BUDGET, QUALITY_TIERS.FAST],
+  mid: [QUALITY_TIERS.STANDARD, QUALITY_TIERS.HIGH],
+  best: [QUALITY_TIERS.FLAGSHIP]
+};
+
+// Fallback model definitions (used when API is unavailable)
+export const FALLBACK_MODELS = [
+  // Budget tier - cheapest options
+  {
+    id: 'gpt-4o-mini',
+    provider: 'openai',
+    quality: QUALITY_TIERS.FAST,
+    pricing: { input: 0.15, output: 0.60 }, // per 1M tokens
+    contextWindow: 128000,
+    maxOutputTokens: 16384,
+    capabilities: ['streaming', 'tools', 'vision'],
+    speed: 'very_fast',
+    goodFor: ['simple-qa', 'small-edit', 'classification', 'extraction']
+  },
+  {
+    id: 'claude-3-5-haiku-latest',
+    provider: 'anthropic',
+    quality: QUALITY_TIERS.FAST,
+    pricing: { input: 0.80, output: 4.00 },
+    contextWindow: 200000,
+    maxOutputTokens: 8192,
+    capabilities: ['streaming', 'tools', 'vision'],
+    speed: 'very_fast',
+    goodFor: ['simple-qa', 'small-edit', 'code-review', 'summarization']
+  },
+  {
+    id: 'gemini-2.0-flash',
+    provider: 'google',
+    quality: QUALITY_TIERS.FAST,
+    pricing: { input: 0.10, output: 0.40 },
+    contextWindow: 1000000,
+    maxOutputTokens: 8192,
+    capabilities: ['streaming', 'tools', 'vision', 'grounding', 'multimodal'],
+    speed: 'very_fast',
+    goodFor: ['simple-qa', 'search-grounded', 'multimodal']
+  },
+
+  // Standard/High tier - good balance
+  {
+    id: 'gpt-4o',
+    provider: 'openai',
+    quality: QUALITY_TIERS.HIGH,
+    pricing: { input: 2.50, output: 10.00 },
+    contextWindow: 128000,
+    maxOutputTokens: 16384,
+    capabilities: ['streaming', 'tools', 'vision'],
+    speed: 'fast',
+    goodFor: ['refactor', 'multi-file', 'code-generation', 'analysis']
+  },
+  {
+    id: 'claude-sonnet-4-20250514',
+    provider: 'anthropic',
+    quality: QUALITY_TIERS.HIGH,
+    pricing: { input: 3.00, output: 15.00 },
+    contextWindow: 200000,
+    maxOutputTokens: 8192,
+    capabilities: ['streaming', 'tools', 'vision', 'thinking'],
+    speed: 'fast',
+    goodFor: ['refactor', 'multi-file', 'code-generation', 'debugging']
+  },
+  {
+    id: 'gemini-2.5-pro-preview-06-05',
+    provider: 'google',
+    quality: QUALITY_TIERS.HIGH,
+    pricing: { input: 2.50, output: 15.00 },
+    contextWindow: 1000000,
+    maxOutputTokens: 65536,
+    capabilities: ['streaming', 'tools', 'vision', 'thinking', 'grounding'],
+    speed: 'medium',
+    goodFor: ['large-context', 'analysis', 'research', 'code-generation']
+  },
+
+  // Flagship tier - best quality
+  {
+    id: 'claude-opus-4-20250514',
+    provider: 'anthropic',
+    quality: QUALITY_TIERS.FLAGSHIP,
+    pricing: { input: 15.00, output: 75.00 },
+    contextWindow: 200000,
+    maxOutputTokens: 32000,
+    capabilities: ['streaming', 'tools', 'vision', 'thinking'],
+    speed: 'slow',
+    goodFor: ['architecture', 'planning', 'complex-reasoning', 'ambiguous-tasks']
+  },
+  {
+    id: 'o1',
+    provider: 'openai',
+    quality: QUALITY_TIERS.FLAGSHIP,
+    pricing: { input: 15.00, output: 60.00 },
+    contextWindow: 200000,
+    maxOutputTokens: 100000,
+    capabilities: ['reasoning'],
+    speed: 'slow',
+    goodFor: ['complex-reasoning', 'math', 'planning', 'architecture']
+  },
+  {
+    id: 'o3',
+    provider: 'openai',
+    quality: QUALITY_TIERS.FLAGSHIP,
+    pricing: { input: 10.00, output: 40.00 },
+    contextWindow: 200000,
+    maxOutputTokens: 100000,
+    capabilities: ['reasoning', 'tools'],
+    speed: 'slow',
+    goodFor: ['complex-reasoning', 'math', 'planning', 'architecture']
+  }
+];
+
+/**
+ * Get models by quality tier from fallback registry
+ */
+export function getModelsByQuality(quality) {
+  return FALLBACK_MODELS
+    .filter(m => m.quality === quality)
+    .sort((a, b) => a.pricing.input - b.pricing.input);
+}
+
+/**
+ * Get models by simple tier (cheap/mid/best)
+ */
+export function getModelsByTier(tier) {
+  const qualities = TIER_TO_QUALITY[tier] || [QUALITY_TIERS.STANDARD];
+  return FALLBACK_MODELS
+    .filter(m => qualities.includes(m.quality))
+    .sort((a, b) => a.pricing.input - b.pricing.input);
+}
+
+/**
+ * Get the cheapest model for a tier
+ */
+export function getCheapestForTier(tier) {
+  const models = getModelsByTier(tier);
+  return models[0] || null;
+}
+
+/**
+ * Get all tiers in escalation order
+ */
+export function getEscalationOrder() {
+  return ['cheap', 'mid', 'best'];
+}
+
+/**
+ * Get next tier for escalation
+ */
+export function getNextTier(currentTier) {
+  const order = getEscalationOrder();
+  const idx = order.indexOf(currentTier);
+  if (idx === -1 || idx >= order.length - 1) return null;
+  return order[idx + 1];
+}
+
+export default {
+  QUALITY_TIERS,
+  TIER_TO_QUALITY,
+  FALLBACK_MODELS,
+  getModelsByQuality,
+  getModelsByTier,
+  getCheapestForTier,
+  getEscalationOrder,
+  getNextTier
+};

package/lib/router/router.js

@@ -0,0 +1,382 @@
+/**
+ * Cost-Aware Model Router
+ * 
+ * Routes coding tasks to the cheapest capable model, with automatic escalation
+ * on failure. Uses llms.mechdna.net for model registry and completions.
+ * 
+ * Flow:
+ * 1. Classify task → determine tier (cheap/mid/best)
+ * 2. Get cheapest model for that tier
+ * 3. Execute completion
+ * 4. If result looks bad, escalate to next tier
+ * 5. Return result with cost info
+ */
+
+import { MechLLMsClient } from './mech-llms-client.js';
+import { classifyTask, buildUseCaseString } from './classifier.js';
+import { 
+  getCheapestForTier, 
+  getNextTier, 
+  getModelsByTier,
+  TIER_TO_QUALITY 
+} from './models.js';
+
+// Map simple tiers to quality tiers for API
+const TIER_TO_API_QUALITY = {
+  cheap: 'fast',      // fast/budget tier
+  mid: 'high',        // high/standard tier
+  best: 'flagship'    // flagship tier
+};
+
+/**
+ * Model Router
+ */
+export class Router {
+  /**
+   * @param {Object} options
+   * @param {string} [options.apiKey] - Mech API key
+   * @param {boolean} [options.useRecommendations] - Use /recommend API instead of local classification
+   * @param {number} [options.maxEscalations] - Max escalation attempts (default: 2)
+   * @param {boolean} [options.verbose] - Enable verbose logging
+   */
+  constructor(options = {}) {
+    this.client = new MechLLMsClient({ apiKey: options.apiKey });
+    this.useRecommendations = options.useRecommendations || false;
+    this.maxEscalations = options.maxEscalations || 2;
+    this.verbose = options.verbose || false;
+    
+    // Cache for model registry
+    this._modelCache = null;
+    this._modelCacheTime = 0;
+    this._modelCacheTTL = 5 * 60 * 1000; // 5 minutes
+  }
+
+  /**
+   * Log message if verbose mode is enabled
+   */
+  _log(...args) {
+    if (this.verbose) {
+      console.log('[Router]', ...args);
+    }
+  }
+
+  /**
+   * Get model registry (cached)
+   */
+  async _getModelRegistry() {
+    const now = Date.now();
+    if (this._modelCache && (now - this._modelCacheTime) < this._modelCacheTTL) {
+      return this._modelCache;
+    }
+
+    try {
+      const result = await this.client.getModelRegistry({ sortBy: 'cost', sortOrder: 'asc' });
+      this._modelCache = result.models || [];
+      this._modelCacheTime = now;
+      return this._modelCache;
+    } catch (err) {
+      this._log('Failed to fetch model registry, using fallback:', err.message);
+      return null; // Will use fallback models
+    }
+  }
+
+  /**
+   * Get the cheapest model for a tier
+   * Tries API first, falls back to local registry
+   */
+  async _getCheapestModel(tier) {
+    const quality = TIER_TO_API_QUALITY[tier];
+    
+    try {
+      // Try API first
+      const model = await this.client.getCheapestModel(quality);
+      if (model) {
+        this._log(`API returned cheapest ${quality} model: ${model.id}`);
+        return model;
+      }
+    } catch (err) {
+      this._log('API model lookup failed:', err.message);
+    }
+
+    // Fallback to local registry
+    const fallback = getCheapestForTier(tier);
+    if (fallback) {
+      this._log(`Using fallback model: ${fallback.id}`);
+      return fallback;
+    }
+
+    throw new Error(`No model found for tier: ${tier}`);
+  }
+
+  /**
+   * Get model recommendation from API
+   */
+  async _getRecommendedModel(prompt, context) {
+    const useCase = buildUseCaseString(prompt, context);
+    
+    try {
+      const result = await this.client.getRecommendations({ useCase });
+      if (result.recommendations?.length > 0) {
+        const rec = result.recommendations[0];
+        this._log(`API recommended: ${rec.model.id} (score: ${rec.score}, reason: ${rec.reasoning})`);
+        return rec.model;
+      }
+    } catch (err) {
+      this._log('Recommendation API failed:', err.message);
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if a completion result looks bad (should escalate)
+   * 
+   * @param {Object} result - Completion result
+   * @param {Object} options - Original request options
+   * @returns {boolean} True if should escalate
+   */
+  _shouldEscalate(result, options = {}) {
+    // No content
+    if (!result.choices?.[0]?.message?.content) {
+      this._log('Escalating: No content in response');
+      return true;
+    }
+
+    const content = result.choices[0].message.content;
+
+    // Very short response for a complex task
+    if (options.expectLongResponse && content.length < 100) {
+      this._log('Escalating: Response too short for expected complexity');
+      return true;
+    }
+
+    // Model explicitly says it can't do something
+    const cantDoPatterns = [
+      /i (?:can't|cannot|am unable to)/i,
+      /i don't (?:have|know)/i,
+      /beyond my (?:capabilities|ability)/i,
+      /i'm not (?:able|capable)/i
+    ];
+    
+    for (const pattern of cantDoPatterns) {
+      if (pattern.test(content)) {
+        this._log('Escalating: Model indicated inability');
+        return true;
+      }
+    }
+
+    // Content filter or safety stop
+    if (result.choices[0].finish_reason === 'content_filter') {
+      this._log('Escalating: Content filter triggered');
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Route a request to the appropriate model
+   * 
+   * @param {Object} options
+   * @param {string} options.prompt - User prompt (for classification)
+   * @param {Array} options.messages - Chat messages
+   * @param {Object} [options.context] - Context for classification
+   * @param {number} [options.maxTokens] - Max tokens
+   * @param {number} [options.temperature] - Temperature
+   * @param {Array} [options.tools] - Tools for function calling
+   * @param {string} [options.forceTier] - Force a specific tier
+   * @param {string} [options.forceModel] - Force a specific model
+   * @returns {Promise<Object>} Result with content, model, cost, usage
+   */
+  async route(options) {
+    const {
+      prompt,
+      messages,
+      context = {},
+      maxTokens = 4096,
+      temperature,
+      tools,
+      forceTier,
+      forceModel
+    } = options;
+
+    // If model is forced, just use it
+    if (forceModel) {
+      this._log(`Using forced model: ${forceModel}`);
+      return this._executeCompletion(forceModel, messages, { maxTokens, temperature, tools });
+    }
+
+    // Determine starting tier
+    let tier;
+    let model;
+    let classification;
+
+    if (forceTier) {
+      tier = forceTier;
+      this._log(`Using forced tier: ${tier}`);
+    } else if (this.useRecommendations) {
+      // Use API recommendations
+      model = await this._getRecommendedModel(prompt, context);
+      if (model) {
+        return this._executeWithEscalation(model, messages, options);
+      }
+      // Fallback to local classification
+      classification = classifyTask(prompt, context);
+      tier = classification.tier;
+    } else {
+      // Local classification
+      classification = classifyTask(prompt, context);
+      tier = classification.tier;
+      this._log(`Classified as ${tier}: ${classification.reason} (confidence: ${classification.confidence})`);
+    }
+
+    // Get cheapest model for tier
+    model = await this._getCheapestModel(tier);
+    
+    return this._executeWithEscalation(model, messages, { 
+      ...options, 
+      startingTier: tier,
+      classification 
+    });
+  }
+
+  /**
+   * Execute completion with automatic escalation on failure
+   */
+  async _executeWithEscalation(model, messages, options) {
+    const { startingTier, maxTokens, temperature, tools } = options;
+    let currentTier = startingTier || 'cheap';
+    let currentModel = model;
+    let attempts = 0;
+
+    while (attempts <= this.maxEscalations) {
+      this._log(`Attempt ${attempts + 1}: Using ${currentModel.id} (${currentModel.provider})`);
+      
+      try {
+        const result = await this._executeCompletion(
+          currentModel.id, 
+          messages, 
+          { maxTokens, temperature, tools }
+        );
+
+        // Check if we should escalate
+        if (this._shouldEscalate(result, options) && attempts < this.maxEscalations) {
+          const nextTier = getNextTier(currentTier);
+          if (nextTier) {
+            this._log(`Escalating from ${currentTier} to ${nextTier}`);
+            currentTier = nextTier;
+            currentModel = await this._getCheapestModel(nextTier);
+            attempts++;
+            continue;
+          }
+        }
+
+        // Return successful result
+        return this._formatResult(result, currentModel, attempts, currentTier);
+
+      } catch (err) {
+        this._log(`Error with ${currentModel.id}:`, err.message);
+        
+        // Try escalating on error
+        if (attempts < this.maxEscalations) {
+          const nextTier = getNextTier(currentTier);
+          if (nextTier) {
+            this._log(`Escalating due to error: ${currentTier} → ${nextTier}`);
+            currentTier = nextTier;
+            currentModel = await this._getCheapestModel(nextTier);
+            attempts++;
+            continue;
+          }
+        }
+        
+        throw err;
+      }
+    }
+
+    throw new Error('Max escalation attempts reached');
+  }
+
+  /**
+   * Execute a single completion
+   */
+  async _executeCompletion(modelId, messages, options = {}) {
+    const { maxTokens, temperature, tools } = options;
+    
+    return this.client.createCompletion({
+      model: modelId,
+      messages,
+      maxTokens,
+      temperature,
+      tools
+    });
+  }
+
+  /**
+   * Format the result for return
+   */
+  _formatResult(result, model, escalationCount, tier) {
+    const content = result.choices?.[0]?.message?.content || '';
+    const cost = result.x_llm_cost?.total || 0;
+    
+    return {
+      content,
+      model: model.id,
+      provider: model.provider || result.x_llm_provider,
+      tier,
+      cost,
+      costBreakdown: result.x_llm_cost,
+      usage: result.usage,
+      escalations: escalationCount,
+      finishReason: result.choices?.[0]?.finish_reason,
+      raw: result
+    };
+  }
+
+  /**
+   * Simple completion without routing (direct model call)
+   */
+  async complete(options) {
+    const { model, messages, maxTokens, temperature, tools } = options;
+    
+    const result = await this.client.createCompletion({
+      model,
+      messages,
+      maxTokens,
+      temperature,
+      tools
+    });
+
+    return {
+      content: result.choices?.[0]?.message?.content || '',
+      model,
+      cost: result.x_llm_cost?.total || 0,
+      costBreakdown: result.x_llm_cost,
+      usage: result.usage,
+      raw: result
+    };
+  }
+
+  /**
+   * Get usage summary
+   */
+  async getUsageSummary(filters = {}) {
+    return this.client.getUsageSummary(filters);
+  }
+}
+
+/**
+ * Create a router instance
+ */
+export function createRouter(options = {}) {
+  return new Router(options);
+}
+
+/**
+ * Quick route function for simple use cases
+ */
+export async function route(prompt, messages, options = {}) {
+  const router = new Router(options);
+  return router.route({ prompt, messages, ...options });
+}
+
+export default Router;

package/lib/session/cleanup.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Session cleanup utilities
+ * Handles cleanup of session-related caches and resources
+ */
+
+/**
+ * Clean up all session-related caches and resources
+ * @param {string} sessionId - Session ID to clean up
+ * @returns {Promise<void>}
+ */
+export async function cleanupSession(sessionId) {
+  if (!sessionId) {
+    return;
+  }
+
+  // 1. Clear mute cache
+  try {
+    const { clearMuteCache } = await import('./mute-checker.js');
+    if (clearMuteCache) {
+      clearMuteCache(sessionId);
+    }
+  } catch (e) {
+    // Mute checker might not be available, ignore
+  }
+
+  // 2. Clear any other session-specific caches
+  // (Add more cleanup tasks here as needed)
+  // Note: If adding async cleanup tasks, use Promise.allSettled() here
+}
+
+/**
+ * Clean up all sessions (used for global cleanup)
+ * @returns {Promise<void>}
+ */
+export async function cleanupAllSessions() {
+  try {
+    const { clearAllMuteCache } = await import('./mute-checker.js');
+    if (clearAllMuteCache) {
+      clearAllMuteCache();
+    }
+  } catch (e) {
+    // Mute checker might not be available, ignore
+  }
+}
+
+/**
+ * Check if a session has timed out based on last activity
+ * @param {number} lastActivityTimestamp - Last activity timestamp (milliseconds)
+ * @param {number} timeoutMs - Timeout in milliseconds (default: 1 hour)
+ * @returns {boolean} - True if session has timed out
+ */
+export function isSessionTimedOut(lastActivityTimestamp, timeoutMs = 3600000) {
+  if (lastActivityTimestamp == null) { // null or undefined, but not 0
+    return false; // No timestamp means can't determine timeout
+  }
+  const now = Date.now();
+  const age = now - lastActivityTimestamp;
+  return age > timeoutMs;
+}
+
+/**
+ * Get session age in milliseconds
+ * @param {number} lastActivityTimestamp - Last activity timestamp (milliseconds)
+ * @returns {number} - Age in milliseconds, or 0 if no timestamp
+ */
+export function getSessionAge(lastActivityTimestamp) {
+  if (lastActivityTimestamp == null) { // null or undefined, but not 0
+    return 0;
+  }
+  return Date.now() - lastActivityTimestamp;
+}
+
+/**
+ * Format session age as human-readable string
+ * @param {number} lastActivityTimestamp - Last activity timestamp (milliseconds)
+ * @returns {string} - Human-readable age string
+ */
+export function formatSessionAge(lastActivityTimestamp) {
+  const age = getSessionAge(lastActivityTimestamp);
+  if (age === 0) {
+    return 'unknown';
+  }
+
+  const seconds = Math.floor(age / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+  const days = Math.floor(hours / 24);
+
+  if (days > 0) {
+    return `${days}d ${hours % 24}h`;
+  } else if (hours > 0) {
+    return `${hours}h ${minutes % 60}m`;
+  } else if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`;
+  } else {
+    return `${seconds}s`;
+  }
+}
+