@game_ryo/lsji 0.1.0 → 0.3.0

package/src/execution/budget/circuit-breaker.js

@@ -0,0 +1,245 @@
+/**
+ * Circuit Breaker
+ * 
+ * Prevents runaway costs by automatically stopping execution when thresholds are exceeded.
+ * Implements the circuit breaker pattern for budget protection.
+ */
+
+import { globalCostTracker } from './cost-tracker.js';
+
+/**
+ * Circuit breaker states
+ */
+export const CircuitState = {
+  CLOSED: 'closed',     // Normal operation
+  OPEN: 'open',         // Blocking requests
+  HALF_OPEN: 'half_open', // Testing if service recovered
+};
+
+/**
+ * Circuit Breaker Configuration
+ * @typedef {Object} CircuitBreakerConfig
+ * @property {number} [costThreshold] - Cost threshold to open circuit (USD)
+ * @property {number} [tokenThreshold] - Token threshold to open circuit
+ * @property {number} [timeWindow] - Time window for threshold (ms), default 1 hour
+ * @property {number} [resetTimeout] - Time before trying half-open (ms), default 5 min
+ * @property {number} [failureThreshold] - Number of failures before opening
+ */
+
+/**
+ * Circuit Breaker for budget protection
+ */
+export class CircuitBreaker {
+  constructor(config = {}) {
+    this.config = {
+      costThreshold: config.costThreshold || 50.00, // $50 per hour
+      tokenThreshold: config.tokenThreshold || 500000, // 500k tokens per hour
+      timeWindow: config.timeWindow || 3600000, // 1 hour
+      resetTimeout: config.resetTimeout || 300000, // 5 minutes
+      failureThreshold: config.failureThreshold || 5,
+    };
+    
+    this.state = CircuitState.CLOSED;
+    this.failureCount = 0;
+    this.lastFailureTime = null;
+    this.lastStateChange = Date.now();
+    this.costTracker = globalCostTracker;
+    this.listeners = new Map(); // event -> callbacks
+  }
+
+  /**
+   * Check if circuit allows execution
+   */
+  async checkBudget(budgetId, estimatedCost = 0, estimatedTokens = 0) {
+    // Check cost tracker budget
+    const budgetCheck = this.costTracker.checkBudget(budgetId, estimatedCost, estimatedTokens);
+    
+    if (!budgetCheck.allowed) {
+      this.recordFailure('budget_exceeded', budgetCheck.errors);
+      return { allowed: false, reason: 'budget_exceeded', details: budgetCheck.errors };
+    }
+    
+    // Check circuit breaker thresholds
+    const now = Date.now();
+    const windowStart = now - this.config.timeWindow;
+    
+    // Get recent costs
+    const recentCost = this.costTracker.getCostSince(new Date(windowStart));
+    const recentTokens = this.getRecentTokens(windowStart);
+    
+    if (recentCost >= this.config.costThreshold) {
+      this.recordFailure('cost_threshold_exceeded', { 
+        current: recentCost, 
+        threshold: this.config.costThreshold 
+      });
+      return { allowed: false, reason: 'cost_threshold_exceeded', details: { current: recentCost, threshold: this.config.costThreshold } };
+    }
+    
+    if (recentTokens >= this.config.tokenThreshold) {
+      this.recordFailure('token_threshold_exceeded', { 
+        current: recentTokens, 
+        threshold: this.config.tokenThreshold 
+      });
+      return { allowed: false, reason: 'token_threshold_exceeded', details: { current: recentTokens, threshold: this.config.tokenThreshold } };
+    }
+    
+    // Check circuit state
+    if (this.state === CircuitState.OPEN) {
+      if (now - this.lastStateChange >= this.config.resetTimeout) {
+        this.transitionToHalfOpen();
+      } else {
+        return { allowed: false, reason: 'circuit_open', details: { resetIn: this.config.resetTimeout - (now - this.lastStateChange) } };
+      }
+    }
+    
+    if (this.state === CircuitState.HALF_OPEN) {
+      // Allow one request to test
+      return { allowed: true, reason: 'half_open_test' };
+    }
+    
+    return { allowed: true, reason: 'ok' };
+  }
+
+  /**
+   * Record successful execution
+   */
+  recordSuccess() {
+    if (this.state === CircuitState.HALF_OPEN) {
+      this.transitionToClosed();
+    }
+    this.failureCount = 0;
+  }
+
+  /**
+   * Record failure
+   */
+  recordFailure(reason, details = {}) {
+    this.failureCount++;
+    this.lastFailureTime = Date.now();
+    
+    this.emit('failure', { reason, details, failureCount: this.failureCount });
+    
+    if (this.failureCount >= this.config.failureThreshold) {
+      this.transitionToOpen(reason, details);
+    }
+  }
+
+  /**
+   * Transition to OPEN state
+   */
+  transitionToOpen(reason, details) {
+    if (this.state !== CircuitState.OPEN) {
+      this.state = CircuitState.OPEN;
+      this.lastStateChange = Date.now();
+      this.emit('open', { reason, details, timestamp: this.lastStateChange });
+    }
+  }
+
+  /**
+   * Transition to HALF_OPEN state
+   */
+  transitionToHalfOpen() {
+    this.state = CircuitState.HALF_OPEN;
+    this.lastStateChange = Date.now();
+    this.emit('half_open', { timestamp: this.lastStateChange });
+  }
+
+  /**
+   * Transition to CLOSED state
+   */
+  transitionToClosed() {
+    this.state = CircuitState.CLOSED;
+    this.lastStateChange = Date.now();
+    this.failureCount = 0;
+    this.emit('closed', { timestamp: this.lastStateChange });
+  }
+
+  /**
+   * Get recent token count
+   */
+  getRecentTokens(since) {
+    const history = this.costTracker.costHistory || [];
+    return history
+      .filter(r => r.timestamp >= new Date(since))
+      .reduce((sum, r) => sum + (r.totalTokens || 0), 0);
+  }
+
+  /**
+   * Get current state
+   */
+  getState() {
+    return {
+      state: this.state,
+      failureCount: this.failureCount,
+      lastFailureTime: this.lastFailureTime,
+      lastStateChange: this.lastStateChange,
+      config: this.config,
+    };
+  }
+
+  /**
+   * Reset circuit breaker
+   */
+  reset() {
+    this.state = CircuitState.CLOSED;
+    this.failureCount = 0;
+    this.lastFailureTime = null;
+    this.lastStateChange = Date.now();
+    this.emit('reset', { timestamp: this.lastStateChange });
+  }
+
+  /**
+   * Force open the circuit
+   */
+  forceOpen(reason = 'manual') {
+    this.transitionToOpen(reason, { manual: true });
+  }
+
+  /**
+   * Force close the circuit
+   */
+  forceClose() {
+    this.transitionToClosed();
+  }
+
+  /**
+   * Add event listener
+   */
+  on(event, callback) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, []);
+    }
+    this.listeners.get(event).push(callback);
+  }
+
+  /**
+   * Remove event listener
+   */
+  off(event, callback) {
+    if (this.listeners.has(event)) {
+      const callbacks = this.listeners.get(event);
+      const index = callbacks.indexOf(callback);
+      if (index >= 0) callbacks.splice(index, 1);
+    }
+  }
+
+  /**
+   * Emit event
+   */
+  emit(event, data) {
+    if (this.listeners.has(event)) {
+      for (const callback of this.listeners.get(event)) {
+        try {
+          callback(data);
+        } catch (e) {
+          console.error(`Circuit breaker listener error:`, e);
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Global circuit breaker instance
+ */
+export const globalCircuitBreaker = new CircuitBreaker();

package/src/execution/budget/cost-tracker.js

@@ -0,0 +1,387 @@
+/**
+ * Cost Tracker
+ * 
+ * Tracks API costs with provider-specific pricing and budget limits.
+ */
+
+import { globalTokenCounter } from './token-counter.js';
+
+/**
+ * Cost record
+ * @typedef {Object} CostRecord
+ * @property {number} cost - Cost in USD
+ * @property {number} inputTokens
+ * @property {number} outputTokens
+ * @property {string} model
+ * @property {string} provider
+ * @property {Date} timestamp
+ * @property {string} [operation] - Operation identifier
+ * @property {string} [budgetId] - Budget identifier
+ */
+
+/**
+ * Budget configuration
+ * @typedef {Object} BudgetConfig
+ * @property {number} [maxCostPerRun] - Maximum cost per run (USD)
+ * @property {number} [maxCostPerDay] - Maximum cost per day (USD)
+ * @property {number} [maxCostPerMonth] - Maximum cost per month (USD)
+ * @property {number} [maxTokensPerRun] - Maximum tokens per run
+ * @property {number} [alertThreshold] - Alert threshold (0-1), default 0.8
+ */
+
+/**
+ * Cost Tracker - Tracks costs and enforces budgets
+ */
+export class CostTracker {
+  constructor(config = {}) {
+    this.config = {
+      maxCostPerRun: config.maxCostPerRun || 10.00,
+      maxCostPerDay: config.maxCostPerDay || 50.00,
+      maxCostPerMonth: config.maxCostPerMonth || 500.00,
+      maxTokensPerRun: config.maxTokensPerRun || 100000,
+      alertThreshold: config.alertThreshold || 0.8,
+    };
+    
+    this.costHistory = [];
+    this.runCosts = new Map(); // budgetId -> accumulated cost
+    this.runTokens = new Map(); // budgetId -> accumulated tokens
+    this.alerts = [];
+  }
+
+  /**
+   * Record cost from LLM usage
+   */
+  recordCost(record) {
+    const costRecord = {
+      ...record,
+      timestamp: record.timestamp || new Date(),
+    };
+    this.costHistory.push(costRecord);
+    
+    // Track per budget
+    if (record.budgetId) {
+      const currentCost = this.runCosts.get(record.budgetId) || 0;
+      this.runCosts.set(record.budgetId, currentCost + costRecord.cost);
+      
+      const currentTokens = this.runTokens.get(record.budgetId) || 0;
+      this.runTokens.set(record.budgetId, currentTokens + (record.totalTokens || 0));
+    }
+    
+    // Check alerts
+    this.checkAlerts(costRecord);
+    
+    return costRecord;
+  }
+
+  /**
+   * Check and trigger alerts
+   */
+  checkAlerts(record) {
+    if (!record.budgetId) return;
+    
+    const runCost = this.runCosts.get(record.budgetId) || 0;
+    const runTokens = this.runTokens.get(record.budgetId) || 0;
+    
+    // Check run cost limit
+    if (this.config.maxCostPerRun > 0) {
+      const ratio = runCost / this.config.maxCostPerRun;
+      if (ratio >= 1.0) {
+        this.triggerAlert('run_cost_exceeded', {
+          budgetId: record.budgetId,
+          current: runCost,
+          limit: this.config.maxCostPerRun,
+          ratio,
+        });
+      } else if (ratio >= this.config.alertThreshold) {
+        this.triggerAlert('run_cost_warning', {
+          budgetId: record.budgetId,
+          current: runCost,
+          limit: this.config.maxCostPerRun,
+          ratio,
+        });
+      }
+    }
+    
+    // Check run token limit
+    if (this.config.maxTokensPerRun > 0) {
+      const ratio = runTokens / this.config.maxTokensPerRun;
+      if (ratio >= 1.0) {
+        this.triggerAlert('run_tokens_exceeded', {
+          budgetId: record.budgetId,
+          current: runTokens,
+          limit: this.config.maxTokensPerRun,
+          ratio,
+        });
+      } else if (ratio >= this.config.alertThreshold) {
+        this.triggerAlert('run_tokens_warning', {
+          budgetId: record.budgetId,
+          current: runTokens,
+          limit: this.config.maxTokensPerRun,
+          ratio,
+        });
+      }
+    }
+    
+    // Check daily limit
+    const todayStart = new Date();
+    todayStart.setHours(0, 0, 0, 0);
+    const todayCost = this.getCostSince(todayStart);
+    if (this.config.maxCostPerDay > 0) {
+      const ratio = todayCost / this.config.maxCostPerDay;
+      if (ratio >= 1.0) {
+        this.triggerAlert('daily_cost_exceeded', { current: todayCost, limit: this.config.maxCostPerDay, ratio });
+      } else if (ratio >= this.config.alertThreshold) {
+        this.triggerAlert('daily_cost_warning', { current: todayCost, limit: this.config.maxCostPerDay, ratio });
+      }
+    }
+    
+    // Check monthly limit
+    const monthStart = new Date();
+    monthStart.setDate(1);
+    monthStart.setHours(0, 0, 0, 0);
+    const monthCost = this.getCostSince(monthStart);
+    if (this.config.maxCostPerMonth > 0) {
+      const ratio = monthCost / this.config.maxCostPerMonth;
+      if (ratio >= 1.0) {
+        this.triggerAlert('monthly_cost_exceeded', { current: monthCost, limit: this.config.maxCostPerMonth, ratio });
+      } else if (ratio >= this.config.alertThreshold) {
+        this.triggerAlert('monthly_cost_warning', { current: monthCost, limit: this.config.maxCostPerMonth, ratio });
+      }
+    }
+  }
+
+  /**
+   * Trigger alert
+   */
+  triggerAlert(type, data) {
+    const alert = { type, data, timestamp: new Date() };
+    this.alerts.push(alert);
+    
+    // Emit event for external handlers
+    if (typeof window !== 'undefined' && window.dispatchEvent) {
+      window.dispatchEvent(new CustomEvent('lsji:budget-alert', { detail: alert }));
+    }
+    
+    return alert;
+  }
+
+  /**
+   * Get alerts
+   */
+  getAlerts(since = null) {
+    let filtered = this.alerts;
+    if (since) {
+      filtered = this.alerts.filter(a => a.timestamp >= since);
+    }
+    return filtered;
+  }
+
+  /**
+   * Clear alerts
+   */
+  clearAlerts() {
+    this.alerts = [];
+  }
+
+  /**
+   * Get cost since a date
+   */
+  getCostSince(since) {
+    return this.costHistory
+      .filter(r => r.timestamp >= since)
+      .reduce((sum, r) => sum + r.cost, 0);
+  }
+
+  /**
+   * Get cost for a specific budget
+   */
+  getRunCost(budgetId) {
+    return this.runCosts.get(budgetId) || 0;
+  }
+
+  /**
+   * Get tokens for a specific budget
+   */
+  getRunTokens(budgetId) {
+    return this.runTokens.get(budgetId) || 0;
+  }
+
+  /**
+   * Check if budget allows an operation
+   */
+  checkBudget(budgetId, estimatedCost = 0, estimatedTokens = 0) {
+    const currentCost = this.getRunCost(budgetId);
+    const currentTokens = this.getRunTokens(budgetId);
+    
+    const projectedCost = currentCost + estimatedCost;
+    const projectedTokens = currentTokens + estimatedTokens;
+    
+    const result = {
+      allowed: true,
+      warnings: [],
+      errors: [],
+    };
+    
+    if (this.config.maxCostPerRun > 0 && projectedCost > this.config.maxCostPerRun) {
+      result.allowed = false;
+      result.errors.push({
+        type: 'max_cost_per_run_exceeded',
+        current: currentCost,
+        projected: projectedCost,
+        limit: this.config.maxCostPerRun,
+      });
+    }
+    
+    if (this.config.maxTokensPerRun > 0 && projectedTokens > this.config.maxTokensPerRun) {
+      result.allowed = false;
+      result.errors.push({
+        type: 'max_tokens_per_run_exceeded',
+        current: currentTokens,
+        projected: projectedTokens,
+        limit: this.config.maxTokensPerRun,
+      });
+    }
+    
+    // Check daily limit
+    const todayStart = new Date();
+    todayStart.setHours(0, 0, 0, 0);
+    const todayCost = this.getCostSince(todayStart);
+    if (this.config.maxCostPerDay > 0 && todayCost + estimatedCost > this.config.maxCostPerDay) {
+      result.allowed = false;
+      result.errors.push({
+        type: 'max_daily_cost_exceeded',
+        current: todayCost,
+        projected: todayCost + estimatedCost,
+        limit: this.config.maxCostPerDay,
+      });
+    }
+    
+    // Check monthly limit
+    const monthStart = new Date();
+    monthStart.setDate(1);
+    monthStart.setHours(0, 0, 0, 0);
+    const monthCost = this.getCostSince(monthStart);
+    if (this.config.maxCostPerMonth > 0 && monthCost + estimatedCost > this.config.maxCostPerMonth) {
+      result.allowed = false;
+      result.errors.push({
+        type: 'max_monthly_cost_exceeded',
+        current: monthCost,
+        projected: monthCost + estimatedCost,
+        limit: this.config.maxCostPerMonth,
+      });
+    }
+    
+    // Warnings
+    if (this.config.maxCostPerRun > 0) {
+      const ratio = projectedCost / this.config.maxCostPerRun;
+      if (ratio >= this.config.alertThreshold) {
+        result.warnings.push({
+          type: 'cost_warning',
+          ratio,
+          current: projectedCost,
+          limit: this.config.maxCostPerRun,
+        });
+      }
+    }
+    
+    return result;
+  }
+
+  /**
+   * Reset run budget (for new run)
+   */
+  resetRunBudget(budgetId) {
+    this.runCosts.delete(budgetId);
+    this.runTokens.delete(budgetId);
+  }
+
+  /**
+   * Get total cost
+   */
+  getTotalCost(since = null) {
+    return this.getCostSince(since);
+  }
+
+  /**
+   * Get cost breakdown by model
+   */
+  getCostByModel(since = null) {
+    let filtered = this.costHistory;
+    if (since) {
+      filtered = this.costHistory.filter(r => r.timestamp >= since);
+    }
+    
+    const byModel = {};
+    for (const r of filtered) {
+      const model = r.model || 'unknown';
+      if (!byModel[model]) {
+        byModel[model] = { cost: 0, requests: 0, inputTokens: 0, outputTokens: 0 };
+      }
+      byModel[model].cost += r.cost || 0;
+      byModel[model].requests += 1;
+      byModel[model].inputTokens += r.inputTokens || 0;
+      byModel[model].outputTokens += r.outputTokens || 0;
+    }
+    return byModel;
+  }
+
+  /**
+   * Get cost breakdown by provider
+   */
+  getCostByProvider(since = null) {
+    let filtered = this.costHistory;
+    if (since) {
+      filtered = this.costHistory.filter(r => r.timestamp >= since);
+    }
+    
+    const byProvider = {};
+    for (const r of filtered) {
+      const provider = r.provider || 'unknown';
+      if (!byProvider[provider]) {
+        byProvider[provider] = { cost: 0, requests: 0, inputTokens: 0, outputTokens: 0 };
+      }
+      byProvider[provider].cost += r.cost || 0;
+      byProvider[provider].requests += 1;
+      byProvider[provider].inputTokens += r.inputTokens || 0;
+      byProvider[provider].outputTokens += r.outputTokens || 0;
+    }
+    return byProvider;
+  }
+
+  /**
+   * Get status summary
+   */
+  getStatus(budgetId = null) {
+    const todayStart = new Date();
+    todayStart.setHours(0, 0, 0, 0);
+    const monthStart = new Date();
+    monthStart.setDate(1);
+    monthStart.setHours(0, 0, 0, 0);
+    
+    return {
+      config: this.config,
+      runCost: budgetId ? this.getRunCost(budgetId) : null,
+      runTokens: budgetId ? this.getRunTokens(budgetId) : null,
+      todayCost: this.getCostSince(todayStart),
+      monthCost: this.getCostSince(monthStart),
+      totalCost: this.getTotalCost(),
+      recentAlerts: this.alerts.slice(-10),
+      budgetStatus: budgetId ? this.checkBudget(budgetId) : null,
+    };
+  }
+
+  /**
+   * Clear all data
+   */
+  clear() {
+    this.costHistory = [];
+    this.runCosts.clear();
+    this.runTokens.clear();
+    this.alerts = [];
+  }
+}
+
+/**
+ * Global cost tracker instance
+ */
+export const globalCostTracker = new CostTracker();

package/src/execution/budget/index.js

@@ -0,0 +1,63 @@
+/**
+ * Budget Control System
+ * 
+ * Exports all budget-related components:
+ * - TokenCounter: Tracks token usage
+ * - CostTracker: Tracks costs with limits and alerts
+ * - CircuitBreaker: Prevents runaway costs
+ */
+
+import { TokenCounter } from './token-counter.js';
+import { CostTracker } from './cost-tracker.js';
+import { CircuitBreaker } from './circuit-breaker.js';
+
+export { TokenCounter, globalTokenCounter } from './token-counter.js';
+export { CostTracker, globalCostTracker } from './cost-tracker.js';
+export { CircuitBreaker, CircuitState, globalCircuitBreaker } from './circuit-breaker.js';
+
+/**
+ * Create a complete budget controller with all components
+ */
+export function createBudgetController(config = {}) {
+  return {
+    tokenCounter: new TokenCounter(),
+    costTracker: new CostTracker(config),
+    circuitBreaker: new CircuitBreaker(config),
+    
+    /**
+     * Check budget before operation
+     */
+    async checkBudget(budgetId, estimatedCost = 0, estimatedTokens = 0) {
+      return this.circuitBreaker.checkBudget(budgetId, estimatedCost, estimatedTokens);
+    },
+    
+    /**
+     * Record usage after operation
+     */
+    recordUsage(budgetId, usage) {
+      // usage: { inputTokens, outputTokens, totalTokens, model, provider, cost }
+      this.tokenCounter.recordUsage({ ...usage, budgetId });
+      if (usage.cost !== undefined) {
+        this.costTracker.recordCost({ ...usage, budgetId });
+      }
+    },
+    
+    /**
+     * Get status
+     */
+    getStatus(budgetId = null) {
+      return {
+        tokens: this.tokenCounter.getSummary(),
+        costs: this.costTracker.getStatus(budgetId),
+        circuit: this.circuitBreaker.getState(),
+      };
+    },
+    
+    /**
+     * Reset run budget
+     */
+    resetRunBudget(budgetId) {
+      this.costTracker.resetRunBudget(budgetId);
+    },
+  };
+}