elsabro 2.2.0 → 3.7.0

package/references/cost-tracking.md

@@ -0,0 +1,1095 @@
+# Cost Tracking & Optimization (v3.3)
+
+Sistema de monitoreo de costos, presupuestos y optimización automática de selección de modelos.
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                      COST TRACKING SYSTEM                                │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    TOKEN TRACKER                                 │    │
+│  │  ┌─────────────────────────────────────────────────────────┐    │    │
+│  │  │              Per-Request Metering                        │    │    │
+│  │  │  ┌───────────┐  ┌───────────┐  ┌───────────┐            │    │    │
+│  │  │  │  Input    │  │  Output   │  │  Cache    │            │    │    │
+│  │  │  │  Tokens   │  │  Tokens   │  │  Hits     │            │    │    │
+│  │  │  └───────────┘  └───────────┘  └───────────┘            │    │    │
+│  │  └─────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    BUDGET MANAGER                                │    │
+│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │    │
+│  │  │   Session   │  │   Daily     │  │   Monthly   │              │    │
+│  │  │   Budget    │  │   Budget    │  │   Budget    │              │    │
+│  │  └─────────────┘  └─────────────┘  └─────────────┘              │    │
+│  │  ┌───────────────────────────────────────────────────────────┐  │    │
+│  │  │  Alerts: warning (80%) │ critical (95%) │ hard_limit      │  │    │
+│  │  └───────────────────────────────────────────────────────────┘  │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                    │                                     │
+│                                    ▼                                     │
+│  ┌─────────────────────────────────────────────────────────────────┐    │
+│  │                    MODEL OPTIMIZER                               │    │
+│  │  ┌─────────────────────────────────────────────────────────┐    │    │
+│  │  │  Task Analysis → Model Selection → Cost Prediction       │    │    │
+│  │  │  ┌─────────┐    ┌─────────┐    ┌─────────┐              │    │    │
+│  │  │  │ Simple  │ →  │ Haiku   │    │ $0.001  │              │    │    │
+│  │  │  │ Medium  │ →  │ Sonnet  │    │ $0.015  │              │    │    │
+│  │  │  │ Complex │ →  │ Opus    │    │ $0.075  │              │    │    │
+│  │  │  └─────────┘    └─────────┘    └─────────┘              │    │    │
+│  │  └─────────────────────────────────────────────────────────┘    │    │
+│  └─────────────────────────────────────────────────────────────────┘    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## TokenTracker
+
+### API Principal
+
+```typescript
+interface TokenUsage {
+  input_tokens: number;
+  output_tokens: number;
+  cache_creation_tokens?: number;
+  cache_read_tokens?: number;
+  total_tokens: number;
+}
+
+interface UsageRecord {
+  id: string;
+  timestamp: string;
+  model: string;
+  agent?: string;
+  task?: string;
+  flow?: string;
+  usage: TokenUsage;
+  cost: CostBreakdown;
+  duration_ms: number;
+  success: boolean;
+}
+
+interface CostBreakdown {
+  input_cost: number;
+  output_cost: number;
+  cache_cost: number;
+  total_cost: number;
+  currency: string;
+}
+
+interface ModelPricing {
+  model: string;
+  input_per_million: number;
+  output_per_million: number;
+  cache_creation_per_million?: number;
+  cache_read_per_million?: number;
+}
+
+class TokenTracker {
+  private records: UsageRecord[] = [];
+  private pricing: Map<string, ModelPricing>;
+  private config: TokenTrackerConfig;
+
+  constructor(config: TokenTrackerConfig) {
+    this.config = config;
+    this.pricing = this.initializePricing();
+  }
+
+  // Record usage from API response
+  record(
+    model: string,
+    usage: TokenUsage,
+    metadata?: UsageMetadata
+  ): UsageRecord {
+    const pricing = this.pricing.get(model);
+    if (!pricing) {
+      throw new Error(`Unknown model: ${model}`);
+    }
+
+    const cost = this.calculateCost(usage, pricing);
+
+    const record: UsageRecord = {
+      id: this.generateId(),
+      timestamp: new Date().toISOString(),
+      model,
+      agent: metadata?.agent,
+      task: metadata?.task,
+      flow: metadata?.flow,
+      usage,
+      cost,
+      duration_ms: metadata?.duration_ms || 0,
+      success: metadata?.success ?? true
+    };
+
+    this.records.push(record);
+
+    // Emit event for real-time tracking
+    EventBus.publish('cost.usage.recorded', record);
+
+    // Check budget alerts
+    BudgetManager.checkAlerts(record);
+
+    return record;
+  }
+
+  // Get usage summary
+  getSummary(options?: SummaryOptions): UsageSummary {
+    const filtered = this.filterRecords(options);
+
+    const summary: UsageSummary = {
+      total_requests: filtered.length,
+      total_tokens: {
+        input: 0,
+        output: 0,
+        cache_creation: 0,
+        cache_read: 0,
+        total: 0
+      },
+      total_cost: {
+        input: 0,
+        output: 0,
+        cache: 0,
+        total: 0,
+        currency: 'USD'
+      },
+      by_model: {},
+      by_agent: {},
+      by_task: {},
+      period: {
+        from: options?.from || this.records[0]?.timestamp,
+        to: options?.to || new Date().toISOString()
+      }
+    };
+
+    for (const record of filtered) {
+      // Total tokens
+      summary.total_tokens.input += record.usage.input_tokens;
+      summary.total_tokens.output += record.usage.output_tokens;
+      summary.total_tokens.cache_creation += record.usage.cache_creation_tokens || 0;
+      summary.total_tokens.cache_read += record.usage.cache_read_tokens || 0;
+      summary.total_tokens.total += record.usage.total_tokens;
+
+      // Total cost
+      summary.total_cost.input += record.cost.input_cost;
+      summary.total_cost.output += record.cost.output_cost;
+      summary.total_cost.cache += record.cost.cache_cost;
+      summary.total_cost.total += record.cost.total_cost;
+
+      // By model
+      if (!summary.by_model[record.model]) {
+        summary.by_model[record.model] = { requests: 0, tokens: 0, cost: 0 };
+      }
+      summary.by_model[record.model].requests++;
+      summary.by_model[record.model].tokens += record.usage.total_tokens;
+      summary.by_model[record.model].cost += record.cost.total_cost;
+
+      // By agent
+      if (record.agent) {
+        if (!summary.by_agent[record.agent]) {
+          summary.by_agent[record.agent] = { requests: 0, tokens: 0, cost: 0 };
+        }
+        summary.by_agent[record.agent].requests++;
+        summary.by_agent[record.agent].tokens += record.usage.total_tokens;
+        summary.by_agent[record.agent].cost += record.cost.total_cost;
+      }
+
+      // By task
+      if (record.task) {
+        if (!summary.by_task[record.task]) {
+          summary.by_task[record.task] = { requests: 0, tokens: 0, cost: 0 };
+        }
+        summary.by_task[record.task].requests++;
+        summary.by_task[record.task].tokens += record.usage.total_tokens;
+        summary.by_task[record.task].cost += record.cost.total_cost;
+      }
+    }
+
+    return summary;
+  }
+
+  // Get usage by time period
+  getTimeSeries(
+    granularity: 'minute' | 'hour' | 'day' | 'week' | 'month',
+    options?: TimeSeriesOptions
+  ): TimeSeriesData[] {
+    const filtered = this.filterRecords(options);
+    const buckets = new Map<string, TimeSeriesData>();
+
+    for (const record of filtered) {
+      const bucket = this.getBucket(record.timestamp, granularity);
+
+      if (!buckets.has(bucket)) {
+        buckets.set(bucket, {
+          timestamp: bucket,
+          requests: 0,
+          tokens: 0,
+          cost: 0
+        });
+      }
+
+      const data = buckets.get(bucket)!;
+      data.requests++;
+      data.tokens += record.usage.total_tokens;
+      data.cost += record.cost.total_cost;
+    }
+
+    return Array.from(buckets.values()).sort((a, b) =>
+      a.timestamp.localeCompare(b.timestamp)
+    );
+  }
+
+  // Estimate cost for task
+  estimate(
+    model: string,
+    estimatedInputTokens: number,
+    estimatedOutputTokens: number
+  ): CostBreakdown {
+    const pricing = this.pricing.get(model);
+    if (!pricing) {
+      throw new Error(`Unknown model: ${model}`);
+    }
+
+    return this.calculateCost(
+      {
+        input_tokens: estimatedInputTokens,
+        output_tokens: estimatedOutputTokens,
+        total_tokens: estimatedInputTokens + estimatedOutputTokens
+      },
+      pricing
+    );
+  }
+
+  // Export data
+  export(format: 'json' | 'csv'): string {
+    if (format === 'csv') {
+      return this.exportCSV();
+    }
+    return JSON.stringify(this.records, null, 2);
+  }
+
+  // Clear old records
+  cleanup(olderThan: Date): number {
+    const cutoff = olderThan.toISOString();
+    const before = this.records.length;
+    this.records = this.records.filter(r => r.timestamp >= cutoff);
+    return before - this.records.length;
+  }
+
+  private calculateCost(usage: TokenUsage, pricing: ModelPricing): CostBreakdown {
+    const input_cost = (usage.input_tokens / 1_000_000) * pricing.input_per_million;
+    const output_cost = (usage.output_tokens / 1_000_000) * pricing.output_per_million;
+
+    let cache_cost = 0;
+    if (usage.cache_creation_tokens && pricing.cache_creation_per_million) {
+      cache_cost += (usage.cache_creation_tokens / 1_000_000) * pricing.cache_creation_per_million;
+    }
+    if (usage.cache_read_tokens && pricing.cache_read_per_million) {
+      cache_cost += (usage.cache_read_tokens / 1_000_000) * pricing.cache_read_per_million;
+    }
+
+    return {
+      input_cost,
+      output_cost,
+      cache_cost,
+      total_cost: input_cost + output_cost + cache_cost,
+      currency: 'USD'
+    };
+  }
+
+  private initializePricing(): Map<string, ModelPricing> {
+    return new Map([
+      ['claude-3-5-haiku-20241022', {
+        model: 'claude-3-5-haiku-20241022',
+        input_per_million: 0.80,
+        output_per_million: 4.00,
+        cache_creation_per_million: 1.00,
+        cache_read_per_million: 0.08
+      }],
+      ['claude-sonnet-4-20250514', {
+        model: 'claude-sonnet-4-20250514',
+        input_per_million: 3.00,
+        output_per_million: 15.00,
+        cache_creation_per_million: 3.75,
+        cache_read_per_million: 0.30
+      }],
+      ['claude-opus-4-5-20251101', {
+        model: 'claude-opus-4-5-20251101',
+        input_per_million: 15.00,
+        output_per_million: 75.00,
+        cache_creation_per_million: 18.75,
+        cache_read_per_million: 1.50
+      }]
+    ]);
+  }
+
+  private filterRecords(options?: SummaryOptions): UsageRecord[] {
+    let filtered = this.records;
+
+    if (options?.from) {
+      filtered = filtered.filter(r => r.timestamp >= options.from!);
+    }
+    if (options?.to) {
+      filtered = filtered.filter(r => r.timestamp <= options.to!);
+    }
+    if (options?.model) {
+      filtered = filtered.filter(r => r.model === options.model);
+    }
+    if (options?.agent) {
+      filtered = filtered.filter(r => r.agent === options.agent);
+    }
+    if (options?.task) {
+      filtered = filtered.filter(r => r.task === options.task);
+    }
+
+    return filtered;
+  }
+
+  private getBucket(timestamp: string, granularity: string): string {
+    const date = new Date(timestamp);
+
+    switch (granularity) {
+      case 'minute':
+        return date.toISOString().slice(0, 16);
+      case 'hour':
+        return date.toISOString().slice(0, 13);
+      case 'day':
+        return date.toISOString().slice(0, 10);
+      case 'week':
+        const week = this.getWeekNumber(date);
+        return `${date.getFullYear()}-W${week.toString().padStart(2, '0')}`;
+      case 'month':
+        return date.toISOString().slice(0, 7);
+      default:
+        return date.toISOString().slice(0, 10);
+    }
+  }
+
+  private getWeekNumber(date: Date): number {
+    const firstDay = new Date(date.getFullYear(), 0, 1);
+    const days = Math.floor((date.getTime() - firstDay.getTime()) / 86400000);
+    return Math.ceil((days + firstDay.getDay() + 1) / 7);
+  }
+
+  private exportCSV(): string {
+    const headers = [
+      'id', 'timestamp', 'model', 'agent', 'task',
+      'input_tokens', 'output_tokens', 'total_tokens',
+      'input_cost', 'output_cost', 'total_cost', 'duration_ms'
+    ];
+
+    const rows = this.records.map(r => [
+      r.id, r.timestamp, r.model, r.agent || '', r.task || '',
+      r.usage.input_tokens, r.usage.output_tokens, r.usage.total_tokens,
+      r.cost.input_cost.toFixed(6), r.cost.output_cost.toFixed(6),
+      r.cost.total_cost.toFixed(6), r.duration_ms
+    ]);
+
+    return [headers.join(','), ...rows.map(r => r.join(','))].join('\n');
+  }
+
+  private generateId(): string {
+    return `usage_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+}
+```
+
+---
+
+## BudgetManager
+
+```typescript
+interface Budget {
+  id: string;
+  name: string;
+  type: 'session' | 'daily' | 'weekly' | 'monthly' | 'total';
+  limit: number;
+  currency: string;
+  spent: number;
+  remaining: number;
+  alerts: BudgetAlert[];
+  action_on_exceed: 'warn' | 'pause' | 'stop' | 'downgrade';
+  created_at: string;
+  reset_at?: string;
+}
+
+interface BudgetAlert {
+  type: 'warning' | 'critical' | 'exceeded';
+  threshold: number;  // Percentage (0-100)
+  triggered: boolean;
+  triggered_at?: string;
+  notified: boolean;
+}
+
+class BudgetManager {
+  private budgets: Map<string, Budget>;
+  private config: BudgetManagerConfig;
+
+  constructor(config: BudgetManagerConfig) {
+    this.config = config;
+    this.budgets = new Map();
+    this.initializeDefaultBudgets();
+  }
+
+  // Create budget
+  createBudget(options: CreateBudgetOptions): Budget {
+    const budget: Budget = {
+      id: this.generateId(),
+      name: options.name,
+      type: options.type,
+      limit: options.limit,
+      currency: options.currency || 'USD',
+      spent: 0,
+      remaining: options.limit,
+      alerts: [
+        { type: 'warning', threshold: 80, triggered: false, notified: false },
+        { type: 'critical', threshold: 95, triggered: false, notified: false },
+        { type: 'exceeded', threshold: 100, triggered: false, notified: false }
+      ],
+      action_on_exceed: options.action_on_exceed || 'warn',
+      created_at: new Date().toISOString(),
+      reset_at: this.calculateResetTime(options.type)
+    };
+
+    this.budgets.set(budget.id, budget);
+    return budget;
+  }
+
+  // Update budget with cost
+  recordSpend(budgetId: string, cost: number): Budget {
+    const budget = this.budgets.get(budgetId);
+    if (!budget) {
+      throw new Error(`Budget not found: ${budgetId}`);
+    }
+
+    budget.spent += cost;
+    budget.remaining = Math.max(0, budget.limit - budget.spent);
+
+    this.checkAlerts(budget);
+
+    return budget;
+  }
+
+  // Check all budgets against usage record
+  checkAlerts(record?: UsageRecord): void {
+    for (const [_, budget] of this.budgets) {
+      if (record) {
+        budget.spent += record.cost.total_cost;
+        budget.remaining = Math.max(0, budget.limit - budget.spent);
+      }
+
+      const percentage = (budget.spent / budget.limit) * 100;
+
+      for (const alert of budget.alerts) {
+        if (percentage >= alert.threshold && !alert.triggered) {
+          alert.triggered = true;
+          alert.triggered_at = new Date().toISOString();
+
+          // Emit alert event
+          EventBus.publish('cost.budget.alert', {
+            budget_id: budget.id,
+            budget_name: budget.name,
+            alert_type: alert.type,
+            threshold: alert.threshold,
+            current_percentage: percentage,
+            spent: budget.spent,
+            limit: budget.limit
+          });
+
+          // Take action if exceeded
+          if (alert.type === 'exceeded') {
+            this.handleExceeded(budget);
+          }
+        }
+      }
+    }
+  }
+
+  // Get budget status
+  getStatus(budgetId?: string): BudgetStatus | BudgetStatus[] {
+    if (budgetId) {
+      const budget = this.budgets.get(budgetId);
+      if (!budget) throw new Error(`Budget not found: ${budgetId}`);
+      return this.formatStatus(budget);
+    }
+
+    return Array.from(this.budgets.values()).map(b => this.formatStatus(b));
+  }
+
+  // Reset budget
+  resetBudget(budgetId: string): Budget {
+    const budget = this.budgets.get(budgetId);
+    if (!budget) {
+      throw new Error(`Budget not found: ${budgetId}`);
+    }
+
+    budget.spent = 0;
+    budget.remaining = budget.limit;
+    budget.alerts.forEach(a => {
+      a.triggered = false;
+      a.triggered_at = undefined;
+      a.notified = false;
+    });
+    budget.reset_at = this.calculateResetTime(budget.type);
+
+    return budget;
+  }
+
+  // Check if operation is allowed
+  canSpend(estimatedCost: number): BudgetDecision {
+    const decisions: BudgetDecision[] = [];
+
+    for (const [_, budget] of this.budgets) {
+      const projectedSpent = budget.spent + estimatedCost;
+      const projectedPercentage = (projectedSpent / budget.limit) * 100;
+
+      if (projectedPercentage >= 100) {
+        decisions.push({
+          allowed: budget.action_on_exceed === 'warn',
+          budget_id: budget.id,
+          budget_name: budget.name,
+          reason: `Would exceed ${budget.name} budget`,
+          projected_percentage: projectedPercentage,
+          recommended_action: budget.action_on_exceed
+        });
+      }
+    }
+
+    // Return most restrictive decision
+    const blocked = decisions.find(d => !d.allowed);
+    if (blocked) return blocked;
+
+    return {
+      allowed: true,
+      reason: 'Within all budgets'
+    };
+  }
+
+  // Auto-reset periodic budgets
+  autoReset(): void {
+    const now = new Date();
+
+    for (const [_, budget] of this.budgets) {
+      if (budget.reset_at && new Date(budget.reset_at) <= now) {
+        this.resetBudget(budget.id);
+      }
+    }
+  }
+
+  private handleExceeded(budget: Budget): void {
+    switch (budget.action_on_exceed) {
+      case 'pause':
+        // Trigger interrupt
+        InterruptManager.trigger({
+          type: 'confirmation',
+          title: 'Budget Exceeded',
+          message: `${budget.name} budget has been exceeded. Continue?`,
+          options: [
+            { id: 'continue', label: 'Continue Anyway' },
+            { id: 'stop', label: 'Stop Execution' }
+          ]
+        });
+        break;
+
+      case 'stop':
+        // Stop all flows
+        FlowEngine.pauseAll('Budget exceeded');
+        break;
+
+      case 'downgrade':
+        // Switch to cheaper model
+        ModelOptimizer.forceDowngrade();
+        break;
+
+      case 'warn':
+      default:
+        // Just log warning
+        console.warn(`Budget exceeded: ${budget.name}`);
+    }
+  }
+
+  private initializeDefaultBudgets(): void {
+    if (this.config.defaultBudgets?.session) {
+      this.createBudget({
+        name: 'Session Budget',
+        type: 'session',
+        limit: this.config.defaultBudgets.session,
+        action_on_exceed: 'warn'
+      });
+    }
+
+    if (this.config.defaultBudgets?.daily) {
+      this.createBudget({
+        name: 'Daily Budget',
+        type: 'daily',
+        limit: this.config.defaultBudgets.daily,
+        action_on_exceed: 'pause'
+      });
+    }
+
+    if (this.config.defaultBudgets?.monthly) {
+      this.createBudget({
+        name: 'Monthly Budget',
+        type: 'monthly',
+        limit: this.config.defaultBudgets.monthly,
+        action_on_exceed: 'stop'
+      });
+    }
+  }
+
+  private calculateResetTime(type: string): string | undefined {
+    const now = new Date();
+
+    switch (type) {
+      case 'daily':
+        return new Date(now.setDate(now.getDate() + 1)).toISOString().slice(0, 10) + 'T00:00:00Z';
+      case 'weekly':
+        return new Date(now.setDate(now.getDate() + 7)).toISOString().slice(0, 10) + 'T00:00:00Z';
+      case 'monthly':
+        return new Date(now.setMonth(now.getMonth() + 1)).toISOString().slice(0, 7) + '-01T00:00:00Z';
+      default:
+        return undefined;
+    }
+  }
+
+  private formatStatus(budget: Budget): BudgetStatus {
+    const percentage = (budget.spent / budget.limit) * 100;
+    return {
+      id: budget.id,
+      name: budget.name,
+      type: budget.type,
+      spent: budget.spent,
+      limit: budget.limit,
+      remaining: budget.remaining,
+      percentage,
+      status: percentage >= 100 ? 'exceeded' :
+              percentage >= 95 ? 'critical' :
+              percentage >= 80 ? 'warning' : 'ok',
+      resets_at: budget.reset_at
+    };
+  }
+
+  private generateId(): string {
+    return `budget_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+  }
+}
+```
+
+---
+
+## ModelOptimizer
+
+```typescript
+interface ModelProfile {
+  model: string;
+  tier: 'economy' | 'standard' | 'premium';
+  strengths: string[];
+  weaknesses: string[];
+  cost_per_1k_tokens: number;
+  quality_score: number;  // 0-100
+  speed_score: number;    // 0-100
+}
+
+interface TaskAnalysis {
+  complexity: 'simple' | 'medium' | 'complex';
+  requires_reasoning: boolean;
+  requires_creativity: boolean;
+  requires_accuracy: boolean;
+  estimated_tokens: number;
+  priority: 'speed' | 'quality' | 'cost';
+}
+
+interface ModelRecommendation {
+  recommended_model: string;
+  tier: string;
+  confidence: number;
+  estimated_cost: number;
+  alternatives: Array<{
+    model: string;
+    cost: number;
+    trade_off: string;
+  }>;
+  reasoning: string;
+}
+
+class ModelOptimizer {
+  private profiles: Map<string, ModelProfile>;
+  private history: Map<string, TaskResult[]>;
+  private config: ModelOptimizerConfig;
+
+  constructor(config: ModelOptimizerConfig) {
+    this.config = config;
+    this.profiles = this.initializeProfiles();
+    this.history = new Map();
+  }
+
+  // Analyze task and recommend model
+  recommend(task: TaskAnalysis, budget?: number): ModelRecommendation {
+    const candidates = this.rankCandidates(task);
+
+    // Filter by budget if provided
+    const affordable = budget
+      ? candidates.filter(c => c.estimated_cost <= budget)
+      : candidates;
+
+    if (affordable.length === 0) {
+      // Force cheapest option
+      const cheapest = candidates.sort((a, b) => a.estimated_cost - b.estimated_cost)[0];
+      return {
+        recommended_model: cheapest.model,
+        tier: cheapest.tier,
+        confidence: 0.5,
+        estimated_cost: cheapest.estimated_cost,
+        alternatives: [],
+        reasoning: 'Budget constraint - using cheapest available model'
+      };
+    }
+
+    const best = affordable[0];
+    const alternatives = affordable.slice(1, 4).map(c => ({
+      model: c.model,
+      cost: c.estimated_cost,
+      trade_off: this.getTradeOff(best, c)
+    }));
+
+    return {
+      recommended_model: best.model,
+      tier: best.tier,
+      confidence: best.score / 100,
+      estimated_cost: best.estimated_cost,
+      alternatives,
+      reasoning: this.generateReasoning(task, best)
+    };
+  }
+
+  // Auto-select model for task type
+  autoSelect(taskType: string, context?: AutoSelectContext): string {
+    const mappings: Record<string, string> = {
+      // Exploration tasks → Haiku
+      'explore': 'claude-3-5-haiku-20241022',
+      'search': 'claude-3-5-haiku-20241022',
+      'list': 'claude-3-5-haiku-20241022',
+      'quick-fix': 'claude-3-5-haiku-20241022',
+
+      // Standard tasks → Sonnet
+      'implement': 'claude-sonnet-4-20250514',
+      'refactor': 'claude-sonnet-4-20250514',
+      'test': 'claude-sonnet-4-20250514',
+      'document': 'claude-sonnet-4-20250514',
+
+      // Complex tasks → Opus
+      'architect': 'claude-opus-4-5-20251101',
+      'review': 'claude-opus-4-5-20251101',
+      'debug-complex': 'claude-opus-4-5-20251101',
+      'security-audit': 'claude-opus-4-5-20251101'
+    };
+
+    let model = mappings[taskType] || 'claude-sonnet-4-20250514';
+
+    // Check budget constraints
+    if (context?.budget) {
+      const decision = BudgetManager.canSpend(this.estimateCost(model, context.estimatedTokens || 1000));
+      if (!decision.allowed && decision.recommended_action === 'downgrade') {
+        model = this.downgrade(model);
+      }
+    }
+
+    // Check mode override
+    if (context?.mode === 'economy') {
+      model = 'claude-3-5-haiku-20241022';
+    } else if (context?.mode === 'quality') {
+      model = 'claude-opus-4-5-20251101';
+    }
+
+    return model;
+  }
+
+  // Force downgrade to cheaper model
+  forceDowngrade(): void {
+    this.config.forceEconomy = true;
+    EventBus.publish('cost.model.downgraded', {
+      reason: 'budget_exceeded',
+      new_default: 'claude-3-5-haiku-20241022'
+    });
+  }
+
+  // Get cost savings report
+  getSavingsReport(options?: ReportOptions): SavingsReport {
+    // Analyze historical usage
+    const summary = TokenTracker.getSummary(options);
+
+    // Calculate potential savings with different strategies
+    const strategies = [
+      this.calculateSavings(summary, 'aggressive'),  // All Haiku
+      this.calculateSavings(summary, 'balanced'),    // Smart routing
+      this.calculateSavings(summary, 'quality')      // Minimal changes
+    ];
+
+    return {
+      current_cost: summary.total_cost.total,
+      strategies,
+      recommendations: this.generateSavingsRecommendations(summary)
+    };
+  }
+
+  // Learn from task results
+  recordResult(model: string, task: string, result: TaskResult): void {
+    if (!this.history.has(model)) {
+      this.history.set(model, []);
+    }
+    this.history.get(model)!.push(result);
+
+    // Update model profile based on results
+    this.updateProfile(model, result);
+  }
+
+  private rankCandidates(task: TaskAnalysis): RankedCandidate[] {
+    const candidates: RankedCandidate[] = [];
+
+    for (const [_, profile] of this.profiles) {
+      const score = this.calculateScore(task, profile);
+      const estimated_cost = this.estimateCost(profile.model, task.estimated_tokens);
+
+      candidates.push({
+        model: profile.model,
+        tier: profile.tier,
+        score,
+        estimated_cost
+      });
+    }
+
+    // Sort by score (descending)
+    return candidates.sort((a, b) => b.score - a.score);
+  }
+
+  private calculateScore(task: TaskAnalysis, profile: ModelProfile): number {
+    let score = 50; // Base score
+
+    // Complexity matching
+    if (task.complexity === 'simple' && profile.tier === 'economy') score += 20;
+    if (task.complexity === 'medium' && profile.tier === 'standard') score += 20;
+    if (task.complexity === 'complex' && profile.tier === 'premium') score += 20;
+
+    // Priority weighting
+    switch (task.priority) {
+      case 'speed':
+        score += profile.speed_score * 0.3;
+        break;
+      case 'quality':
+        score += profile.quality_score * 0.3;
+        break;
+      case 'cost':
+        score += (100 - profile.cost_per_1k_tokens * 10) * 0.3;
+        break;
+    }
+
+    // Requirement bonuses
+    if (task.requires_reasoning && profile.strengths.includes('reasoning')) score += 10;
+    if (task.requires_creativity && profile.strengths.includes('creativity')) score += 10;
+    if (task.requires_accuracy && profile.strengths.includes('accuracy')) score += 10;
+
+    return Math.min(100, score);
+  }
+
+  private estimateCost(model: string, tokens: number): number {
+    const profile = this.profiles.get(model);
+    if (!profile) return 0;
+    return (tokens / 1000) * profile.cost_per_1k_tokens;
+  }
+
+  private downgrade(model: string): string {
+    const downgrades: Record<string, string> = {
+      'claude-opus-4-5-20251101': 'claude-sonnet-4-20250514',
+      'claude-sonnet-4-20250514': 'claude-3-5-haiku-20241022',
+      'claude-3-5-haiku-20241022': 'claude-3-5-haiku-20241022'
+    };
+    return downgrades[model] || model;
+  }
+
+  private initializeProfiles(): Map<string, ModelProfile> {
+    return new Map([
+      ['claude-3-5-haiku-20241022', {
+        model: 'claude-3-5-haiku-20241022',
+        tier: 'economy',
+        strengths: ['speed', 'efficiency', 'simple-tasks'],
+        weaknesses: ['complex-reasoning', 'nuance'],
+        cost_per_1k_tokens: 0.0024,
+        quality_score: 70,
+        speed_score: 95
+      }],
+      ['claude-sonnet-4-20250514', {
+        model: 'claude-sonnet-4-20250514',
+        tier: 'standard',
+        strengths: ['balance', 'coding', 'reasoning'],
+        weaknesses: ['highest-complexity'],
+        cost_per_1k_tokens: 0.009,
+        quality_score: 85,
+        speed_score: 80
+      }],
+      ['claude-opus-4-5-20251101', {
+        model: 'claude-opus-4-5-20251101',
+        tier: 'premium',
+        strengths: ['reasoning', 'creativity', 'accuracy', 'complex-tasks'],
+        weaknesses: ['cost', 'speed'],
+        cost_per_1k_tokens: 0.045,
+        quality_score: 98,
+        speed_score: 60
+      }]
+    ]);
+  }
+
+  private getTradeOff(best: RankedCandidate, alt: RankedCandidate): string {
+    const costDiff = ((alt.estimated_cost - best.estimated_cost) / best.estimated_cost * 100).toFixed(0);
+    if (alt.tier === 'economy') return `${Math.abs(parseInt(costDiff))}% cheaper, less capable`;
+    if (alt.tier === 'premium') return `${costDiff}% more expensive, higher quality`;
+    return 'Similar capability, different cost';
+  }
+
+  private generateReasoning(task: TaskAnalysis, candidate: RankedCandidate): string {
+    return `Selected ${candidate.model} (${candidate.tier}) for ${task.complexity} task. ` +
+           `Priority: ${task.priority}. Estimated cost: $${candidate.estimated_cost.toFixed(4)}`;
+  }
+
+  private calculateSavings(summary: UsageSummary, strategy: string): SavingsStrategy {
+    // Implementation of savings calculation
+    return {
+      strategy,
+      potential_savings: 0,
+      percentage_saved: 0,
+      trade_offs: []
+    };
+  }
+
+  private generateSavingsRecommendations(summary: UsageSummary): string[] {
+    const recommendations: string[] = [];
+
+    // Check for Opus overuse
+    const opusUsage = summary.by_model['claude-opus-4-5-20251101'];
+    if (opusUsage && opusUsage.requests > 10) {
+      recommendations.push('Consider using Sonnet for standard coding tasks to reduce costs by ~70%');
+    }
+
+    // Check for exploration with expensive models
+    const explorerUsage = summary.by_agent['Explore'];
+    if (explorerUsage && explorerUsage.cost > 1) {
+      recommendations.push('Switch exploration agents to Haiku for ~85% cost reduction');
+    }
+
+    return recommendations;
+  }
+
+  private updateProfile(model: string, result: TaskResult): void {
+    // Dynamic profile updates based on actual performance
+  }
+}
+```
+
+---
+
+## Dashboard de Costos
+
+```
+╔═══════════════════════════════════════════════════════════════════════════╗
+║                        COST DASHBOARD                                      ║
+╠═══════════════════════════════════════════════════════════════════════════╣
+║                                                                            ║
+║  SESSION SUMMARY                     BUDGET STATUS                         ║
+║  ───────────────                     ─────────────                         ║
+║  Total Requests: 47                  Session:  ████████░░ 78% ($7.80/$10)  ║
+║  Total Tokens:   125,432             Daily:    ████░░░░░░ 42% ($21/$50)    ║
+║  Total Cost:     $7.82               Monthly:  ██░░░░░░░░ 15% ($78/$500)   ║
+║                                                                            ║
+║  COST BY MODEL                       COST BY AGENT                         ║
+║  ─────────────                       ─────────────                         ║
+║  Haiku   ████░░░░░░  $0.45 (6%)     Explore      ████░░░░░░  $1.20        ║
+║  Sonnet  ██████░░░░  $2.87 (37%)    Executor     ██████████  $4.50        ║
+║  Opus    ████████░░  $4.50 (57%)    Reviewer     ████░░░░░░  $1.12        ║
+║                                      QA           ██░░░░░░░░  $1.00        ║
+║                                                                            ║
+║  RECENT ACTIVITY                                                           ║
+║  ───────────────                                                           ║
+║  12:45:32  Opus     implement-feature   $0.85   ✓                         ║
+║  12:44:15  Sonnet   review-code         $0.32   ✓                         ║
+║  12:43:01  Haiku    explore-codebase    $0.08   ✓                         ║
+║  12:42:30  Opus     architect-solution  $1.20   ✓                         ║
+║                                                                            ║
+║  RECOMMENDATIONS                                                           ║
+║  ───────────────                                                           ║
+║  ⚡ Switch exploration to Haiku: Save ~$0.90/session                       ║
+║  💡 Use Sonnet for standard reviews: Save ~$0.45/review                    ║
+║                                                                            ║
+╚═══════════════════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Configuración
+
+```json
+{
+  "costTracking": {
+    "enabled": true,
+    "tokenTracker": {
+      "enabled": true,
+      "persistence": "file",
+      "retentionDays": 90
+    },
+    "budgets": {
+      "session": {
+        "limit": 10.00,
+        "action_on_exceed": "warn"
+      },
+      "daily": {
+        "limit": 50.00,
+        "action_on_exceed": "pause"
+      },
+      "monthly": {
+        "limit": 500.00,
+        "action_on_exceed": "stop"
+      }
+    },
+    "optimizer": {
+      "enabled": true,
+      "autoSelect": true,
+      "mode": "balanced"
+    },
+    "alerts": {
+      "warning": 80,
+      "critical": 95
+    },
+    "reporting": {
+      "dailySummary": true,
+      "weeklyReport": true
+    }
+  }
+}
+```
+
+---
+
+## Comandos
+
+```bash
+/elsabro:cost                    # Ver dashboard de costos
+/elsabro:cost summary            # Resumen de sesión
+/elsabro:cost budget             # Estado de presupuestos
+/elsabro:cost export csv         # Exportar datos
+/elsabro:cost optimize           # Recomendaciones de ahorro
+/elsabro:cost set-budget daily 100  # Configurar presupuesto
+```
+
+---
+
+## Changelog
+
+- **v3.3.0**: Initial Cost Tracking System
+  - TokenTracker with per-request metering
+  - BudgetManager with alerts
+  - ModelOptimizer for smart model selection
+  - Cost dashboard ASCII