Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

22.3 KB
Raw Blame
/**
 * UsageTracker — agent-agnostic 的 token / context / cost 状态机。
 *
 * 设计目标:
 *   - 把"对标 agentManager.ts 的 currentTurn / lastApi / contextWindow / cumulativeCost"
 *     这套 mutable session state 从 translator / vendor runtime 里抽出来,放到
 *     一个独立的可单测、可跨 agent 复用的 class 里。
 *   - translator 不再做累加,只在 SDK 事件触发点调 ingest* / setContextWindow / endTurn,
 *     emit status event 时数值一律走 tracker.snapshot() —— 单一可信源。
 *   - 各 agent (claude-code / codex) 自己决定怎么从 SDK 原始 usage 字段映射到
 *     本类的 ingestApiCallUsage(...) 入参,本类对 SDK 协议无知。
 *
 * 对标 (agentManager.ts):
 *   - currentTurn{Input,Output,CacheRead,CacheCreate}Tokens (每 turn 累计,result 后 reset)
 *   - lastApi{Input,CacheRead,CacheCreate}Tokens            (最后一次 API call,跨 turn 保留)
 *   - resultModelUsage[model].contextWindow                 (每次 result 时 set)
 *   - 累计 cost                                              (覆盖 result.total_cost_usd —— SDK 子进程内累计值)
 *
 * 不在本类范围:
 *   - status text (Generating.../Done/...)  — translator 自己设
 *   - isRunning 标志                         — translator 在 push status 时拼
 *     (它属于 session lifecycle 不属于 usage)
 */

import { randomUUID } from 'node:crypto';
import type { UsageSnapshot } from '../../types/events.js';

/**
 * One provider request (or the narrowest reliable upstream usage boundary).
 *
 * Pricing consumers must price each segment independently before summing a
 * turn. In particular, long-context bands are request-scoped: selecting a
 * band from the turn aggregate overcharges turns made of many smaller calls.
 */
export interface UsageSegment {
  /** Stable only within the owning turn; used to merge split provider frames. */
  id?: string;
  /** Actual model for this request when the provider exposes it. */
  model?: string;
  /** Request price variant. Fast maps to the gateway priority tariff. */
  priceVariant?: 'standard' | 'priority' | 'fast' | 'batch' | 'ultrafast';
  /** 输入 token (不含 cache) */
  inputTokens: number;
  outputTokens: number;
  /** 命中缓存读出的 token (Anthropic cache_read_input_tokens / Codex 类似) */
  cacheReadTokens?: number;
  /** 写入缓存的 token (Anthropic cache_creation_input_tokens) */
  cacheCreateTokens?: number;
  /** Provider diagnostic subset; never add this to outputTokens again. */
  reasoningTokens?: number;
  /** Provider-reported request cost, used only on routes where that value is authoritative. */
  costUsd?: number;
  /** Upstream emitted a terminal request usage frame covering every token bucket. */
  complete?: boolean;
}

export class RequestUsageTracker {
  private meteringEpoch = randomUUID();
  private meteringModels = new Map<string, UsageSegment>();

  /** Runtime-cumulative receipts. Independent of turn resets, context and display cost. */
  snapshot() {
    return { epoch: this.meteringEpoch, models: [...this.meteringModels.values()].map(row => ({ ...row })) };
  }

  ingest(usage: UsageSegment): void {
    const model = usage.model ?? 'unknown';
    const previous = this.meteringModels.get(model);
    this.meteringModels.set(model, {
      model,
      inputTokens: (previous?.inputTokens ?? 0) + usage.inputTokens,
      outputTokens: (previous?.outputTokens ?? 0) + usage.outputTokens,
      cacheReadTokens: (previous?.cacheReadTokens ?? 0) + (usage.cacheReadTokens ?? 0),
      cacheCreateTokens: (previous?.cacheCreateTokens ?? 0) + (usage.cacheCreateTokens ?? 0),
    });
  }

}

export class UsageTracker {
  private requestMeter = new RequestUsageTracker();
  getRequestMetering() { return this.requestMeter.snapshot(); }
  // ── turn 累计 ────────────────────────────────────────────────────────────
  // 每次 ingestApiCallUsage 累加, endTurn 后由 resetCurrentTurn 清零。
  // 老链路对标: agentManager.ts:2362-2365 currentTurn{Input,Output,CacheRead,CacheCreate}Tokens
  private currentTurn = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };

  // Request/segment boundaries for request-scoped pricing. This list follows
  // the same turn lifecycle as currentTurn and is copied before exposure.
  private currentTurnSegments: UsageSegment[] = [];
  private currentTurnSegmentIndex = new Map<string, number>();

  // ── 最后一次 API call 快照 ─────────────────────────────────────────────────
  // 用于 contextTokens (圆环): 反映"自动压缩后真实 context 占用",而非整 turn 累计。
  // 跨 turn 保留 —— 下一 turn 第一次 ingestApiCallUsage 时被覆盖。
  // 老链路对标: agentManager.ts:2358-2360 lastApi{Input,CacheRead,CacheCreate}Tokens
  private lastApi = { input: 0, cacheRead: 0, cacheCreate: 0 };

  // ── 模型上下文窗口 ─────────────────────────────────────────────────────────
  // result.modelUsage[model].contextWindow 写进来; 跨 turn 保留 (同模型不会变,
  // setModel 切换后下个 result 会覆盖)。
  // 老链路对标: agentManager.ts:2600-2616
  private contextWindow = 0;

  // ── 累计 cost ─────────────────────────────────────────────────────────────
  // claude-code: 入参 costUsd 是 SDK 子进程内累计 (从 spawn 起算, 每次 result 给一个新累计值),
  //              直接覆盖而非 +=, 否则会把同一笔钱算 N 次 (turn 越多越离谱)。
  // codex: 不传 costUsd, 字段保持 0 (SDK 不报告 codex cost, UI 也不显示)。
  // session 持久化的 sessions.total_cost_usd 走 register.ts 的 delta 算法, 与本字段独立。
  private cumulativeCostUsd = 0;

  // ── 按模型分桶累计 cost (额外字典, 不参与 snapshot, 仅供调试/未来扩展) ────
  // 同一 session 内切换模型时, SDK msg.modelUsage[model].costUSD 是每个模型
  // 在子进程内的累计值, 这里覆盖语义与 cumulativeCostUsd 一致 (避免重复累加)。
  private cumulativeCostUsdByModel = new Map<string, number>();

  // ── Cache 命中率统计 (诊断专用, 不参与 snapshot / 不影响 UI) ────────────
  // 用途: 排查"是不是第三方 proxy 把 cache_control 透传搞坏了"。
  // 指标:
  //   - turn 级: 每次 ingestApiCallUsage 累加, endTurn 后清零 (跟 currentTurn 同步)
  //   - session 级: 跨 turn 累计, 只在 reset() / 新 session 时清零
  // hitRate 公式: cacheRead / (cacheRead + cacheCreate + uncachedInput)
  //   - 分母用"本次 API call 真正进入模型的 input token 总量"
  //   - input_tokens (Anthropic) / inputTokens-cachedInputTokens (Codex 已减过) = uncached
  //   - 命中 = cacheRead 部分, 未命中 = cacheCreate + uncached
  // 都为 0 时 hitRate=null (避免 0/0)。
  private turnCache = { read: 0, create: 0, uncachedInput: 0, apiCalls: 0 };
  private sessionCache = { read: 0, create: 0, uncachedInput: 0, apiCalls: 0 };

  /**
   * SDK 报告一次 API call 的 usage 时调 (claude-code: message_delta;
   * codex: 在 turn.completed 或类似事件提取后映射)。
   * 同时累加 currentTurn + 覆盖 lastApi。
   */
  ingestApiCallUsage(usage: UsageSegment): void {
    this.appendUsageSegment(usage);
  }

  /**
   * Merge split frames for one provider request. Claude commonly reports the
   * input/cache side at message_start and output at message_delta; some
   * compatible endpoints repeat input/cache on both frames. Field-wise max
   * preserves the final request snapshot without double counting repeats.
   */
  upsertApiCallUsage(segmentId: string, usage: UsageSegment): void {
    if (!segmentId) {
      this.appendUsageSegment(usage);
      return;
    }
    const existingIndex = this.currentTurnSegmentIndex.get(segmentId);
    if (existingIndex === undefined) {
      this.appendUsageSegment({ ...usage, id: segmentId });
      return;
    }
    const existing = this.currentTurnSegments[existingIndex]!;
    const merged: UsageSegment = {
      ...existing,
      ...usage,
      id: segmentId,
      // Request identity is fixed by the first frame. Runtime settings may
      // change before a terminal frame arrives, but that must not re-price an
      // already-dispatched request.
      model: existing.model ?? usage.model,
      priceVariant: existing.priceVariant ?? usage.priceVariant,
      inputTokens: Math.max(existing.inputTokens, usage.inputTokens),
      outputTokens: Math.max(existing.outputTokens, usage.outputTokens),
      cacheReadTokens: Math.max(existing.cacheReadTokens ?? 0, usage.cacheReadTokens ?? 0),
      cacheCreateTokens: Math.max(existing.cacheCreateTokens ?? 0, usage.cacheCreateTokens ?? 0),
      reasoningTokens: Math.max(existing.reasoningTokens ?? 0, usage.reasoningTokens ?? 0),
      costUsd: Math.max(existing.costUsd ?? 0, usage.costUsd ?? 0),
      ...(existing.complete !== undefined || usage.complete !== undefined
        ? { complete: existing.complete === true || usage.complete === true }
        : {}),
    };
    this.currentTurnSegments[existingIndex] = merged;
    this.requestMeter.ingest({
      model: merged.model,
      inputTokens: merged.inputTokens - existing.inputTokens,
      outputTokens: merged.outputTokens - existing.outputTokens,
      cacheReadTokens: (merged.cacheReadTokens ?? 0) - (existing.cacheReadTokens ?? 0),
      cacheCreateTokens: (merged.cacheCreateTokens ?? 0) - (existing.cacheCreateTokens ?? 0),
    });
    this.applyUsageDelta(
      {
        inputTokens: merged.inputTokens - existing.inputTokens,
        outputTokens: merged.outputTokens - existing.outputTokens,
        cacheReadTokens: (merged.cacheReadTokens ?? 0) - (existing.cacheReadTokens ?? 0),
        cacheCreateTokens: (merged.cacheCreateTokens ?? 0) - (existing.cacheCreateTokens ?? 0),
      },
      false,
    );
    if (
      merged.inputTokens > 0 ||
      (merged.cacheReadTokens ?? 0) > 0 ||
      (merged.cacheCreateTokens ?? 0) > 0
    ) {
      this.lastApi = {
        input: merged.inputTokens,
        cacheRead: merged.cacheReadTokens ?? 0,
        cacheCreate: merged.cacheCreateTokens ?? 0,
      };
    }
  }

  private appendUsageSegment(usage: UsageSegment): void {
    const normalized: UsageSegment = {
      ...usage,
      inputTokens: Math.max(0, usage.inputTokens),
      outputTokens: Math.max(0, usage.outputTokens),
      cacheReadTokens: Math.max(0, usage.cacheReadTokens ?? 0),
      cacheCreateTokens: Math.max(0, usage.cacheCreateTokens ?? 0),
      ...(usage.reasoningTokens !== undefined
        ? { reasoningTokens: Math.max(0, usage.reasoningTokens) }
        : {}),
      ...(usage.costUsd !== undefined ? { costUsd: Math.max(0, usage.costUsd) } : {}),
    };
    if (normalized.id)
      this.currentTurnSegmentIndex.set(normalized.id, this.currentTurnSegments.length);
    this.currentTurnSegments.push(normalized);
    this.applyUsageDelta(normalized, true);
    this.requestMeter.ingest(normalized);
  }

  private applyUsageDelta(
    usage: Pick<
      UsageSegment,
      'inputTokens' | 'outputTokens' | 'cacheReadTokens' | 'cacheCreateTokens'
    >,
    isNewApiCall: boolean,
  ): void {
    const cr = usage.cacheReadTokens ?? 0;
    const cc = usage.cacheCreateTokens ?? 0;

    // lastApi: 覆盖, 反映"最后一次 API call" (如果入参全 0 则不覆盖,防止被没有 input_tokens 的 delta 冲掉)
    if (isNewApiCall && (usage.inputTokens > 0 || cr > 0 || cc > 0)) {
      this.lastApi.input = usage.inputTokens;
      this.lastApi.cacheRead = cr;
      this.lastApi.cacheCreate = cc;
    }

    // currentTurn: 累加, 反映"本 turn 已消耗"
    this.currentTurn.input += usage.inputTokens;
    this.currentTurn.output += usage.outputTokens;
    this.currentTurn.cacheRead += cr;
    this.currentTurn.cacheCreate += cc;

    // cache 命中率累加: 同时进 turn / session 两个桶
    // usage.inputTokens 已经是"未命中缓存的输入 token"(claude message_delta 直接是 input_tokens,
    // codex 已经在调用方做过 totalInput - cached 减法), 所以此处直接当 uncached 累加。
    this.turnCache.read += cr;
    this.turnCache.create += cc;
    this.turnCache.uncachedInput += usage.inputTokens;
    if (isNewApiCall) this.turnCache.apiCalls += 1;
    this.sessionCache.read += cr;
    this.sessionCache.create += cc;
    this.sessionCache.uncachedInput += usage.inputTokens;
    if (isNewApiCall) this.sessionCache.apiCalls += 1;
  }

  /**
   * result.usage 是 turn aggregate。部分 provider 只在 result 阶段补报 cache
   * tokens;这时 contextTokens 会在 endTurn() 里修正,但 cache hit-rate 诊断桶也
   * 必须同步补上 aggregate 与当前累计值之间的差额。
   */
  ingestTurnAggregateCacheStats(usage: {
    inputTokens: number;
    cacheReadTokens?: number;
    cacheCreateTokens?: number;
  }): void {
    const aggregateInput = usage.inputTokens;
    const aggregateCacheRead = usage.cacheReadTokens ?? this.currentTurn.cacheRead;
    const aggregateCacheCreate = usage.cacheCreateTokens ?? this.currentTurn.cacheCreate;
    const deltaRead = Math.max(0, aggregateCacheRead - this.currentTurn.cacheRead);
    const deltaCreate = Math.max(0, aggregateCacheCreate - this.currentTurn.cacheCreate);
    const deltaUncached = Math.max(0, aggregateInput - this.currentTurn.input);

    if (deltaRead === 0 && deltaCreate === 0 && deltaUncached === 0) return;

    this.turnCache.read += deltaRead;
    this.turnCache.create += deltaCreate;
    this.turnCache.uncachedInput += deltaUncached;
    this.sessionCache.read += deltaRead;
    this.sessionCache.create += deltaCreate;
    this.sessionCache.uncachedInput += deltaUncached;
    if (this.turnCache.apiCalls === 0) {
      this.turnCache.apiCalls = 1;
      this.sessionCache.apiCalls += 1;
    }
  }

  /**
   * Compact 后用 postTokens 覆盖 lastApi,使后续 snapshot().contextTokens
   * 反映压缩后的真实 context 占用,而非压缩前最后一次 API call 的值。
   */
  setContextTokensAfterCompact(postTokens: number): void {
    if (postTokens > 0) {
      this.lastApi = { input: postTokens, cacheRead: 0, cacheCreate: 0 };
    }
  }

  /**
   * SDK 在 result 阶段报告模型上下文窗口大小时调。
   * 0 视为"未知" —— renderer 端有 model prefix → 200K/1M 的 fallback 兜底。
   */
  setContextWindow(window: number): void {
    if (window > 0) this.contextWindow = window;
  }

  /**
   * 上下文超限错误(400 context_length_exceeded / prompt is too long 等)终态时调。
   *
   * 超限请求被上游整体拒绝, 不返回任何 usage —— lastApi 停在上一次成功值(会话重启后
   * 首轮就失败则是 0), snapshot().contextTokens 会把"已经溢出"显示成低占用甚至 0%,
   * 且 auto-compact 的 ratio 判定永远走不到阈值, 会话进入"超限 → 无 usage → 不压缩 →
   * 重试再超限"的自锁(#1429)。这里把 lastApi 锁到窗口满载, 让圆环如实显示 100%、
   * ratio 达到 1.0, turn end 的 auto-compact 判定得以触发。
   *
   * 窗口未知(0)时 no-op —— 与 setContextWindow / AutoCompactController.onUsageUpdate
   * 一致的"无估算"原则; 已 ≥ 窗口(上一轮真实值本就超了)时也不动, 保留真实读数。
   */
  markContextOverflow(): void {
    if (this.contextWindow <= 0) return;
    const current = this.lastApi.input + this.lastApi.cacheRead + this.lastApi.cacheCreate;
    if (current >= this.contextWindow) return;
    this.lastApi = { input: this.contextWindow, cacheRead: 0, cacheCreate: 0 };
  }

  /**
   * 当前 turn 已累计的真实用量 (copy, 只读)。
   *
   * 与 endTurn 的关系: endTurn(turnUsage) 会用调用方给的 aggregate **覆盖**
   * input/output 再 reset — Codex 链路的调用方只有 contextTokens 可给 (降级值),
   * 所以 done 事件要在 endTurn 之前用本方法取走真实 per-turn 累计
   * (来自每次 tokenUsage/updated 的 ingestApiCallUsage 累加)。
   * 语义: input = 未命中缓存输入, output = provider 的计费 output(reasoning 若为
   * 子集不重复相加), cacheRead = 命中缓存。
   */
  getTurnUsage(): {
    input: number;
    output: number;
    cacheRead: number;
    cacheCreate: number;
  } {
    return { ...this.currentTurn };
  }

  /** Current turn's provider request boundaries, returned as defensive copies. */
  getTurnUsageSegments(): UsageSegment[] {
    return this.currentTurnSegments.map((segment) => ({ ...segment }));
  }

  /**
   * Turn 结束: 用 result.usage (turn aggregate) 锁定 currentTurn,
   * 覆盖 cost,返回 turn-end snapshot,然后内部 reset currentTurn 为下一轮做准备。
   *
   * 锁定的原因: 老链路 turn end 的 tokenUsage 用 result.usage.input + output,
   * 不是 currentTurn 累加值 (理论上相等,但以 SDK aggregate 为准更稳)。
   *
   * costUsd 覆盖语义: SDK 子进程的 total_cost_usd 本身就是从 spawn 起累计,
   * 不是 per-turn 增量, 直接覆盖即可 (历史 += bug 会让 cost 越积越离谱)。
   *
   * lastApi 不动 —— 跨 turn 保留, 下一轮 message_delta 才覆盖。
   */
  endTurn(turnUsage?: {
    inputTokens: number;
    outputTokens: number;
    cacheReadTokens?: number;
    cacheCreateTokens?: number;
    costUsd?: number;
    replaceLastApi?: boolean;
  }): UsageSnapshot {
    if (turnUsage) {
      this.currentTurn.input = turnUsage.inputTokens;
      this.currentTurn.output = turnUsage.outputTokens;
      const cacheRead = turnUsage.cacheReadTokens ?? this.currentTurn.cacheRead;
      const cacheCreate = turnUsage.cacheCreateTokens ?? this.currentTurn.cacheCreate;
      this.currentTurn.cacheRead = cacheRead;
      this.currentTurn.cacheCreate = cacheCreate;
      if (typeof turnUsage.costUsd === 'number') {
        this.cumulativeCostUsd = turnUsage.costUsd;
      }
      // 兜底:如果整个 turn 都没拿到 input_tokens,用最终的 turn aggregate 填上 context 消耗。
      // 部分 provider 只在 result.usage 报 cache_read/cache_creation;这些也属于 context 占用。
      // 单 API turn 时调用方可显式要求用 result aggregate 覆盖 lastApi,修正
      // message_start 只有 input_tokens、result 才有 cache tokens 的低估。
      if (
        turnUsage.replaceLastApi ||
        (this.lastApi.input === 0 && this.lastApi.cacheRead === 0 && this.lastApi.cacheCreate === 0)
      ) {
        this.lastApi.input = turnUsage.inputTokens;
        this.lastApi.cacheRead = cacheRead;
        this.lastApi.cacheCreate = cacheCreate;
      }
    }
    const snap = this.snapshot();
    // reset currentTurn for next turn (lastApi / contextWindow / cost 跨 turn 保留)
    this.currentTurn = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
    this.currentTurnSegments = [];
    this.currentTurnSegmentIndex.clear();
    // turnCache 同步清零, sessionCache 跨 turn 累计保留
    this.turnCache = { read: 0, create: 0, uncachedInput: 0, apiCalls: 0 };
    return snap;
  }

  /**
   * Turn 开始 (用户 send 时调): 主动清 currentTurn,
   * 防止上一 turn 没正常 endTurn (异常 / abort) 时 currentTurn 残留。
   * 通常 endTurn 已经清过, 这里是兜底; 重复清零无害。
   */
  beginTurn(): void {
    this.currentTurn = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
    this.currentTurnSegments = [];
    this.currentTurnSegmentIndex.clear();
    // 兜底清 turnCache, 防止上一 turn 异常 / abort 没走到 endTurn 留下脏数据;
    // 与 currentTurn 同语义。
    this.turnCache = { read: 0, create: 0, uncachedInput: 0, apiCalls: 0 };
  }

  /**
   * 按模型上报 per-model 累计 cost (覆盖语义)。
   * SDK msg.modelUsage[model].costUSD 已经是每个模型在子进程内的累计值, 直接覆盖。
   * 入参里 cost 不是 number 或 ≤ 0 的条目跳过 (避免把空模型项写进字典)。
   */
  ingestModelCosts(modelCosts: Record<string, number | undefined>): void {
    for (const [model, cost] of Object.entries(modelCosts)) {
      if (typeof cost === 'number' && cost > 0) {
        this.cumulativeCostUsdByModel.set(model, cost);
      }
    }
  }

  /**
   * 取 per-model cost 字典快照 (普通对象, 调用方可安全保存)。
   * 当前未接入 UI / snapshot, 仅用于日志输出与未来按模型分桶展示。
   */
  getCostByModel(): Record<string, number> {
    return Object.fromEntries(this.cumulativeCostUsdByModel);
  }

  /**
   * Cache 命中率统计快照。turn / session 两个粒度都给。
   *
   * 主要用途: 排查第三方 proxy / SDK bug 导致的 prompt cache 失效 ——
   * 直连官方端点时 hitRate 一般 ≥ 0.8 (warm), 走未优化的 proxy 经常掉到 0.2 以下。
   *
   * hitRate 公式: read / (read + create + uncachedInput)
   *   - 分母 = 本桶内所有"真正进模型"的 input token
   *   - 分子 = 命中缓存的 input token
   *   - 全为 0 时返 null (避免 0/0; 调用方按"暂无数据"处理)
   *
   * apiCalls = 桶内 ingestApiCallUsage 调用次数, 配合 hitRate 判断"热身"程度
   *   (1-2 次的 hitRate 不能代表 session 长期表现)。
   */
  getCacheStats(): {
    turn: {
      read: number;
      create: number;
      uncachedInput: number;
      apiCalls: number;
      hitRate: number | null;
    };
    session: {
      read: number;
      create: number;
      uncachedInput: number;
      apiCalls: number;
      hitRate: number | null;
    };
  } {
    const calc = (b: { read: number; create: number; uncachedInput: number }): number | null => {
      const denom = b.read + b.create + b.uncachedInput;
      return denom > 0 ? b.read / denom : null;
    };
    return {
      turn: { ...this.turnCache, hitRate: calc(this.turnCache) },
      session: { ...this.sessionCache, hitRate: calc(this.sessionCache) },
    };
  }

  /**
   * 当前 snapshot —— 任何时刻调都返回最新数值。
   * translator 在 push status event 时调它取数。
   */
  snapshot(): UsageSnapshot {
    return {
      tokenUsage: this.currentTurn.input + this.currentTurn.output,
      contextTokens: this.lastApi.input + this.lastApi.cacheRead + this.lastApi.cacheCreate,
      contextWindow: this.contextWindow,
      costUsd: this.cumulativeCostUsd,
    };
  }
}