Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

15.8 KB
Raw Blame
import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';
import type { MercuryConfig } from './config.js';
import { getMercuryHome, saveConfig } from './config.js';
import { logger } from './logger.js';
import { formatNumber } from './format.js';
import { recordDay, seedToday } from './token-history.js';

export interface TokenTracker {
  dailyUsed: number;
  dailyBudget: number;
  lastResetDate: string;
  requestLog: TokenLogEntry[];
  /** Today's cache split, for /budget. Absent in files written before it existed. */
  dailySplit?: DailySplit;
}

/** Today's input/output split across every recorded request. */
export interface DailySplit {
  inputTokens: number;
  /** Input tokens served from the provider's prompt cache. */
  cachedInputTokens: number;
  /** Input tokens billed at the full rate. */
  noCacheInputTokens: number;
  outputTokens: number;
}

export interface TokenLogEntry {
  timestamp: number;
  provider: string;
  model: string;
  inputTokens: number;
  outputTokens: number;
  totalTokens: number;
  channelType: string;
  agentId?: string;
  /** Cache-hit input tokens, when the caller knows the split. */
  cachedInputTokens?: number;
  /** Full-rate input tokens, when the caller knows the split. */
  noCacheInputTokens?: number;
  /**
   * What this request added to `dailyUsed`: `totalTokens`, or with a cache
   * split, uncached input + output + cache hits × `tokens.cachedWeight`.
   */
  countedTokens?: number;
}

const TOKEN_FILE = 'token-usage.json';

function safeNumber(value: any): number {
  if (value === null || value === undefined) return 0;
  const n = Number(value);
  return isNaN(n) ? 0 : n;
}

const emptySplit = (): DailySplit => ({ inputTokens: 0, cachedInputTokens: 0, noCacheInputTokens: 0, outputTokens: 0 });

/** `tokens.cachedWeight`, clamped to 0–1; anything non-numeric is 1 (count everything). */
export function cachedWeightOf(config: MercuryConfig): number {
  const raw = (config.tokens as { cachedWeight?: unknown } | undefined)?.cachedWeight;
  if (typeof raw !== 'number' || !Number.isFinite(raw)) return 1;
  return Math.min(1, Math.max(0, raw));
}

/**
 * Tokens one request adds to the daily budget. Without a cache split this is
 * the plain total; with one, cache hits count at `weight`.
 */
export function countedTokensFor(
  entry: { inputTokens: number; outputTokens: number; totalTokens: number; cachedInputTokens?: number },
  weight: number,
): number {
  if (entry.cachedInputTokens === undefined) return entry.totalTokens;
  const cached = Math.min(entry.inputTokens, Math.max(0, entry.cachedInputTokens));
  const uncached = Math.max(0, entry.inputTokens - cached);
  return Math.round(uncached + entry.outputTokens + cached * weight);
}

const pct = (part: number, whole: number) => (whole > 0 ? Math.round((part / whole) * 100) : 0);

export class TokenBudget {
  private dailyUsed = 0;
  /** Today's cache split (resets daily). */
  private dailySplit: DailySplit = emptySplit();
  private dailyBudget: number;
  private lastResetDate: string;
  private requestLog: TokenLogEntry[] = [];
  private forceNext = false;
  private perAgentUsage: Map<string, number> = new Map();
  /** Estimated tokens saved today by saver mode (resets daily). */
  private dailySaved = 0;
  /** Cumulative lifetime estimated tokens saved (persisted). */
  private lifetimeSaved = 0;

  constructor(private config: MercuryConfig) {
    this.dailyBudget = config.tokens.dailyBudget;
    this.lastResetDate = new Date().toISOString().split('T')[0];
    const lifetime = (config.tokens as any).saverTokensSavedLifetime;
    if (typeof lifetime === 'number' && Number.isFinite(lifetime) && lifetime > 0) {
      this.lifetimeSaved = lifetime;
    }
    this.restore();
    // The ledger starts with today's counter on its first run, so today isn't blank.
    if (this.dailyUsed > 0) {
      const input = this.requestLog.reduce((a, e) => a + safeNumber(e.inputTokens), 0);
      const output = this.requestLog.reduce((a, e) => a + safeNumber(e.outputTokens), 0);
      seedToday(this.dailyUsed, input, output, this.requestLog.length);
    }
  }

  /**
   * A budget of zero (or less) is not a ceiling, it is the absence of one.
   *
   * The console has always read `dailyBudget: 0` as "unlimited", and an owner who clears the
   * field in the app means the same thing. Comparing `used >= 0` instead turned that request
   * into "every turn is refused from the first token" — a config that reads as *no limit* and
   * behaves as *no answers*, with nothing in the UI able to tell the two apart.
   */
  private hasCeiling(): boolean {
    return safeNumber(this.dailyBudget) > 0;
  }

  canAfford(estimatedTokens: number): boolean {
    this.resetIfNewDay();
    if (!this.hasCeiling()) return true;
    return safeNumber(this.dailyUsed) + estimatedTokens <= safeNumber(this.dailyBudget);
  }

  isOverBudget(): boolean {
    this.resetIfNewDay();
    if (this.forceNext) {
      this.forceNext = false;
      return false;
    }
    if (!this.hasCeiling()) return false;
    return safeNumber(this.dailyUsed) >= safeNumber(this.dailyBudget);
  }

  forceAllowNext(): void {
    this.forceNext = true;
    logger.info('Budget override: next request will proceed regardless of budget');
  }

  resetUsage(): void {
    this.dailyUsed = 0;
    this.dailySplit = emptySplit();
    this.requestLog = [];
    this.perAgentUsage.clear();
    this.persist();
    logger.info('Token usage reset to zero');
  }

  setBudget(newBudget: number): void {
    this.dailyBudget = newBudget;
    this.config.tokens.dailyBudget = newBudget;
    saveConfig(this.config);
    this.persist();
    logger.info({ newBudget }, 'Daily token budget updated');
  }

  getBudget(): number {
    return this.dailyBudget;
  }

  getDailyUsed(): number {
    this.resetIfNewDay();
    return this.dailyUsed;
  }

  recordUsage(entry: Omit<TokenLogEntry, 'timestamp'>): void {
    this.resetIfNewDay();
    const inputTokens = safeNumber(entry.inputTokens);
    const outputTokens = safeNumber(entry.outputTokens);
    const totalTokens = safeNumber(entry.totalTokens) || inputTokens + outputTokens;
    const hasSplit = entry.cachedInputTokens !== undefined;
    const cachedInputTokens = hasSplit ? Math.min(inputTokens, this.sanitizeCount(entry.cachedInputTokens)) : undefined;
    const noCacheInputTokens = hasSplit
      ? (entry.noCacheInputTokens !== undefined ? this.sanitizeCount(entry.noCacheInputTokens) : Math.max(0, inputTokens - (cachedInputTokens ?? 0)))
      : undefined;
    const countedTokens = countedTokensFor({ inputTokens, outputTokens, totalTokens, cachedInputTokens }, cachedWeightOf(this.config));
    const safeEntry = {
      ...entry,
      inputTokens,
      outputTokens,
      totalTokens,
      ...(hasSplit ? { cachedInputTokens, noCacheInputTokens } : {}),
      countedTokens,
    };
    const logEntry: TokenLogEntry = { ...safeEntry, timestamp: Date.now() };
    this.dailyUsed += countedTokens;
    this.dailySplit.inputTokens += inputTokens;
    this.dailySplit.outputTokens += outputTokens;
    if (hasSplit) {
      this.dailySplit.cachedInputTokens += cachedInputTokens ?? 0;
      this.dailySplit.noCacheInputTokens += noCacheInputTokens ?? 0;
    }
    this.requestLog.push(logEntry);
    // History keeps raw token counts; the weight only shapes the budget.
    recordDay(inputTokens, outputTokens, totalTokens, logEntry.timestamp);

    if (entry.agentId) {
      const agentUsed = this.perAgentUsage.get(entry.agentId) ?? 0;
      this.perAgentUsage.set(entry.agentId, agentUsed + countedTokens);
    }

    this.persist();
    this.syncToCloud(logEntry).catch((err) => {
      logger.warn({ err }, 'Failed to sync token usage to Mercury Cloud');
    });
  }

  private async syncToCloud(entry: TokenLogEntry): Promise<void> {
    if (!this.config.cloud.enabled || !this.config.cloud.jwt || !this.config.cloud.agentId || !this.config.cloud.apiUrl) return;
    if (entry.provider === 'mercuryCloud' || entry.provider === 'Mercury Cloud') return;
    if (entry.totalTokens <= 0) return;

    const res = await fetch(`${this.config.cloud.apiUrl}/v1/agents/${this.config.cloud.agentId}/usage/sync`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${this.config.cloud.jwt}`,
      },
      body: JSON.stringify({
        model: `${entry.provider}:${entry.model}`,
        tokensIn: entry.inputTokens,
        tokensOut: entry.outputTokens,
        costCredits: 0,
        timestamp: new Date(entry.timestamp).toISOString(),
      }),
    });

    if (!res.ok) {
      throw new Error(`usage sync failed: ${res.status}`);
    }
  }

  getUsageByAgent(agentId: string): { used: number; percentage: number } {
    this.resetIfNewDay();
    const used = this.perAgentUsage.get(agentId) ?? 0;
    const budget = safeNumber(this.dailyBudget);
    return { used, percentage: budget > 0 ? (used / budget) * 100 : 0 };
  }

  getRemaining(): number {
    this.resetIfNewDay();
    return Math.max(0, safeNumber(this.dailyBudget) - safeNumber(this.dailyUsed));
  }

  getUsagePercentage(): number {
    this.resetIfNewDay();
    const budget = safeNumber(this.dailyBudget);
    const used = safeNumber(this.dailyUsed);
    return budget > 0 ? (used / budget) * 100 : 0;
  }

  getStatusText(): string {
    const used = this.sanitizeCount(this.dailyUsed);
    if (!this.hasCeiling()) {
      return `Token budget: ${formatNumber(used)} used today, no daily ceiling`;
    }
    const pct = Math.round(this.getUsagePercentage());
    const remaining = this.getRemaining();
    return `Token budget: ${formatNumber(used)} / ${formatNumber(this.dailyBudget)} used (${pct}%), ${formatNumber(remaining)} remaining`;
  }

  /** Today's cache split, for display. */
  getDailySplit(): DailySplit {
    this.resetIfNewDay();
    return { ...this.dailySplit };
  }

  /**
   * One line for /budget showing what the bar counts: input with its cache
   * hits and hit rate, uncached input, output, and the cache weight when it
   * is not 1. Empty when nothing was recorded today.
   */
  getCacheSplitText(): string {
    const s = this.getDailySplit();
    if (s.inputTokens <= 0 && s.outputTokens <= 0) return '';
    const weight = cachedWeightOf(this.config);
    const weightNote = weight !== 1 ? `, counted at ${weight}` : '';
    return `Today: ${formatNumber(s.inputTokens)} in (${formatNumber(s.cachedInputTokens)} cached · ${pct(s.cachedInputTokens, s.inputTokens)}%${weightNote}) · ${formatNumber(s.noCacheInputTokens)} uncached · ${formatNumber(s.outputTokens)} out`;
  }

  /**
   * Record an estimated savings from Token Saver Mode. Updates both the
   * per-day counter (resets at day rollover) and the lifetime counter
   * (persisted to mercury.yaml). Negative or zero values are ignored.
   */
  recordSavings(estimatedTokens: number): void {
    const n = safeNumber(estimatedTokens);
    if (n <= 0) return;
    this.resetIfNewDay();
    this.dailySaved += n;
    this.lifetimeSaved += n;
    try {
      (this.config.tokens as any).saverTokensSavedLifetime = this.lifetimeSaved;
      saveConfig(this.config);
    } catch (err) {
      logger.warn({ err }, 'Failed to persist saver lifetime counter');
    }
  }

  getSavedToday(): number {
    this.resetIfNewDay();
    return this.dailySaved;
  }

  getSavedLifetime(): number {
    return this.lifetimeSaved;
  }

  private resetIfNewDay(): void {
    const today = new Date().toISOString().split('T')[0];
    if (today !== this.lastResetDate) {
      this.dailyUsed = 0;
      this.dailySplit = emptySplit();
      this.lastResetDate = today;
      this.requestLog = [];
      this.perAgentUsage.clear();
      this.dailySaved = 0;
      this.persist();
      logger.info('Token budget reset for new day');
    }
  }

  private persist(): void {
    const path = join(getMercuryHome(), TOKEN_FILE);
    try {
      const data = {
        dailyUsed: this.sanitizeCount(this.dailyUsed),
        dailyBudget: this.dailyBudget,
        lastResetDate: this.lastResetDate,
        requestLog: this.requestLog.slice(-200),
        dailySplit: this.dailySplit,
      };
      writeFileSync(path, JSON.stringify(data, null, 2), 'utf-8');
    } catch (err) {
      logger.warn({ err }, 'Failed to persist token usage');
    }
  }

  private restore(): void {
    const path = join(getMercuryHome(), TOKEN_FILE);
    if (!existsSync(path)) return;
    try {
      const raw = readFileSync(path, 'utf-8');
      const data = JSON.parse(raw) as Partial<TokenTracker>;
      const today = new Date().toISOString().split('T')[0];
      let repaired = false;
      const rawLogLength = Array.isArray(data.requestLog) ? data.requestLog.length : 0;
      const restoredLogs = Array.isArray(data.requestLog)
        ? data.requestLog
          .map((entry) => this.sanitizeLogEntry(entry as Omit<TokenLogEntry, 'timestamp'> & { timestamp?: unknown }, this.sanitizeTimestamp((entry as any)?.timestamp)))
          .filter((entry) => entry.totalTokens > 0)
        : [];
      if (restoredLogs.length !== rawLogLength) {
        repaired = true;
      }
      if (data.lastResetDate === today) {
        const restored = safeNumber(data.dailyUsed);
        if (data.dailyUsed != null && !isNaN(restored) && restored > 0) {
          this.dailyUsed = restored;
        } else {
          // Recompute from valid log entries when dailyUsed is corrupted/null
          this.dailyUsed = restoredLogs.reduce((sum, entry) => sum + (entry.countedTokens ?? entry.totalTokens), 0);
          repaired = true;
        }
        this.requestLog = (data.requestLog ?? []).map((entry: any) => ({
          ...entry,
          inputTokens: safeNumber(entry.inputTokens),
          outputTokens: safeNumber(entry.outputTokens),
          totalTokens: safeNumber(entry.totalTokens),
        }));
        const split = data.dailySplit;
        if (split && typeof split === 'object') {
          this.dailySplit = {
            inputTokens: this.sanitizeCount(split.inputTokens),
            cachedInputTokens: this.sanitizeCount(split.cachedInputTokens),
            noCacheInputTokens: this.sanitizeCount(split.noCacheInputTokens),
            outputTokens: this.sanitizeCount(split.outputTokens),
          };
        }
      }
      this.lastResetDate = data.lastResetDate ?? today;
      if (repaired) {
        this.persist();
      }
    } catch (err) {
      logger.warn({ err }, 'Failed to restore token usage');
    }
  }

  private sanitizeCount(value: unknown): number {
    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
  }

  private sanitizeTimestamp(value: unknown): number {
    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : Date.now();
  }

  private sanitizeLogEntry(entry: Omit<TokenLogEntry, 'timestamp'> & { timestamp?: unknown }, timestamp: number): TokenLogEntry {
    const inputTokens = this.sanitizeCount(entry.inputTokens);
    const outputTokens = this.sanitizeCount(entry.outputTokens);
    const rawTotal = this.sanitizeCount(entry.totalTokens);
    const totalTokens = rawTotal > 0 ? rawTotal : inputTokens + outputTokens;

    const optional = (v: unknown) => (typeof v === 'number' && Number.isFinite(v) && v >= 0 ? v : undefined);
    const cachedInputTokens = optional(entry.cachedInputTokens);
    const noCacheInputTokens = optional(entry.noCacheInputTokens);
    const countedTokens = optional(entry.countedTokens);

    return {
      timestamp: this.sanitizeTimestamp(timestamp),
      provider: typeof entry.provider === 'string' && entry.provider ? entry.provider : 'unknown',
      model: typeof entry.model === 'string' && entry.model ? entry.model : 'unknown',
      inputTokens,
      outputTokens,
      totalTokens,
      channelType: typeof entry.channelType === 'string' && entry.channelType ? entry.channelType : 'unknown',
      ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
      ...(noCacheInputTokens !== undefined ? { noCacheInputTokens } : {}),
      ...(countedTokens !== undefined ? { countedTokens } : {}),
    };
  }
}