Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
10.9 KB
Raw Blame
/**
 * chat-usage.ts — durable per-call chat usage accounting (#4218, reviving the
 * #3392 shape).
 *
 * gateway.chat() calls `recordChatUsage` at its SUCCESS boundary (both the
 * production provider path and the test-transport path) with the answering
 * model + token usage. This module:
 *
 *   - attributes a best-effort PHASE via AsyncLocalStorage (`withChatPhase`):
 *     the minion worker wraps handler execution in `job:<name>`; `think`
 *     records as `think` when nothing outside set a phase
 *     (`withDefaultChatPhase`); query expansion always records as
 *     `expansion` (#7176); other direct CLI / op callers record with phase
 *     NULL unless they opt in. Attribution is advisory — a missing phase never
 *     blocks the record.
 *   - prices the call from CANONICAL_PRICING (`estimateChatCostUsd`),
 *     including cache_read/cache_write tokens at the provider's cache rates
 *     when the table carries them (Anthropic), falling back to the input
 *     rate otherwise. Unknown models record cost_usd = NULL (never a fake 0).
 *   - forwards the record to the registered sink FIRE-AND-FORGET. Accounting
 *     is strictly fail-open: a sink error (missing table pre-migration,
 *     closed engine, disk pressure) must never break a chat call.
 *
 * Coverage contract (surfaced verbatim by the `get_usage` op): only
 * gateway.chat() and gateway.expand() calls are logged. The subagent raw-SDK path, embeddings
 * (embedding-pricing.ts owns those), and calls made before the sink was
 * registered or before migration v140 are NOT covered. Failed chat calls are
 * not logged either — the budget tracker (budget-tracker.ts) remains the
 * pessimistic in-flight spend gate; this table is the after-the-fact ledger.
 *
 * No engine import here (the sink is injected) — this module stays a leaf so
 * the gateway can import it statically without deepening any cycle.
 */

import { AsyncLocalStorage } from 'node:async_hooks';
import { canonicalLookup, priceAtPromptSize } from '../model-pricing.ts';
import { priceFor, type PricingOverrides } from '../budget/reservation-cost.ts';
import { embeddedEngineInScope } from '../engine-scope.ts';
import { engineKey } from '../engine-key.ts';

export interface ChatUsageRecord {
  /** "provider:modelId" of the model that actually answered. */
  model: string;
  /** Recipe/provider id when known (e.g. 'anthropic'). */
  provider: string | null;
  /** Best-effort attribution, e.g. 'job:embed-backfill'. NULL = direct/unattributed. */
  phase: string | null;
  input_tokens: number;
  output_tokens: number;
  cache_read_tokens: number;
  cache_write_tokens: number;
  /** USD, priced from CANONICAL_PRICING. NULL when the model has no pricing. */
  cost_usd: number | null;
}

export type ChatUsageSink = (record: ChatUsageRecord) => void | Promise<void>;

const __chatPhaseStore = new AsyncLocalStorage<string>();

/** Run `fn` with every gateway.chat() inside it attributed to `phase`. */
export function withChatPhase<T>(phase: string, fn: () => T): T {
  return __chatPhaseStore.run(phase, fn);
}

/** Like `withChatPhase`, but an enclosing phase (`job:<name>`, `phase:synthesize`) wins. */
export function withDefaultChatPhase<T>(phase: string, fn: () => T): T {
  return currentChatPhase() === null ? withChatPhase(phase, fn) : fn();
}

export function currentChatPhase(): string | null {
  return __chatPhaseStore.getStore() ?? null;
}

/**
 * Successful chat calls counted for one cycle phase (phase containment,
 * dream_paid_loop) or one nightly probe run. A meter that declares
 * `cost_usd` also prices each call with the budget tracker's resolver
 * (`priceFor`: `pricing_overrides`, then the shipped tables, the claude-cli
 * sibling rate and free local providers; table rows keep their cache-token
 * rates): priced calls add to `cost_usd`, unpriced ones add to
 * `unpriced_calls` instead of counting as 0.
 */
export interface ChatCallMeter {
  calls: number;
  cost_usd?: number;
  unpriced_calls?: number;
  pricing_overrides?: PricingOverrides;
}
const __chatMeterStore = new AsyncLocalStorage<ChatCallMeter>();

/** Run `fn` counting every successful gateway.chat() inside it on `meter`. */
export function withChatCallMeter<T>(meter: ChatCallMeter, fn: () => T): T {
  return __chatMeterStore.run(meter, fn);
}

/**
 * #4480: sink REGISTRY (stack), not a last-wins scalar. A multi-engine
 * process (migrate-engine source+target, doctor probes, tests) used to lose
 * its ledger permanently: the most recently created engine overwrote the
 * sink, and once that engine disconnected every later record was swallowed
 * by a closed engine. Registration now returns a deregister handle; the
 * engine factory calls it on engine.disconnect, restoring the previous live
 * sink. Records route to the TOP live entry (still single-writer —
 * simultaneous multi-brain attribution stays documented best-effort).
 */
interface SinkEntry { sink: ChatUsageSink; engine?: object }
let _sinks: SinkEntry[] = [];
/** An embedded engine's own sink, keyed by engineKey; never on the stack, and kept across reconnect() until it closes. */
const _engineSinks = new WeakMap<object, ChatUsageSink>();

/**
 * The sink a record goes to: in an embedded engine's scope, that engine's own (engine-scope.ts) or none once it
 * closed; otherwise the top of the stack, which never holds an embedded engine, so one brain's usage never lands in
 * another's database.
 */
function sinkInScope(): ChatUsageSink | null {
  const scoped = embeddedEngineInScope();
  if (scoped) return _engineSinks.get(engineKey(scoped)) ?? null;
  return _sinks.at(-1)?.sink ?? null;
}

/** Gives an engine opened from settings its own sink, off the process stack. Returns the handle its close calls. */
export function registerEngineChatUsageSink(engine: object, sink: ChatUsageSink): () => void {
  _engineSinks.set(engineKey(engine), sink);
  return () => { _engineSinks.delete(engineKey(engine)); };
}

/** Register a usage sink, for `engine` when given. Returns an idempotent deregister handle. */
export function registerChatUsageSink(sink: ChatUsageSink, engine?: object): () => void {
  const entry: SinkEntry = { sink, engine };
  _sinks.push(entry);
  return () => {
    _sinks = _sinks.filter((e) => e !== entry);
  };
}

/** @internal exported for tests: how many sinks the process stack holds. */
export function __chatUsageSinkCountForTests(): number {
  return _sinks.length;
}

/**
 * Legacy scalar API (tests + one-shot callers): clears the registry and
 * installs `sink` as the only entry (null = clear).
 */
export function setChatUsageSink(sink: ChatUsageSink | null): void {
  _sinks = sink ? [{ sink }] : [];
}

/**
 * Price a chat call in USD from the canonical table. Cache tokens use the
 * table's cache_read/cache_write rates when present, else the input rate
 * (documented best-effort — see module doc). Unknown model → null.
 */
export function estimateChatCostUsd(
  model: string,
  usage: {
    input_tokens: number;
    output_tokens: number;
    cache_read_tokens?: number;
    cache_write_tokens?: number;
  },
): number | null {
  const row = canonicalLookup(model);
  if (!row) return null;
  const cacheRead = usage.cache_read_tokens ?? 0;
  const cacheWrite = usage.cache_write_tokens ?? 0;
  // #6448 item 1: the prompt size that selects a long-prompt tier is the
  // whole prompt — uncached input plus both cache buckets.
  const p = priceAtPromptSize(row, usage.input_tokens + cacheRead + cacheWrite);
  return (
    (usage.input_tokens * p.input +
      usage.output_tokens * p.output +
      cacheRead * (p.cache_read ?? p.input) +
      cacheWrite * (p.cache_write ?? p.input)) /
    1_000_000
  );
}

/**
 * Called by gateway.chat() at its success boundary. Never throws; the sink
 * runs fire-and-forget with errors swallowed. `usage` is the gateway's
 * `ChatResult.usage` (AI SDK convention): `input_tokens` is the TOTAL input,
 * and the cache read/write counts are subsets of it, so the call is priced as
 * (input - cache) at the input rate plus each cache bucket at its own rate,
 * never the cache tokens a second time on top of the total.
 */
export function recordChatUsage(input: {
  model: string;
  provider?: string | null;
  /** An operation's own phase (`expansion`), over the ambient one. */
  phase?: string;
  usage: {
    input_tokens: number;
    output_tokens: number;
    cache_read_tokens?: number;
    cache_write_tokens?: number;
  };
}): void {
  const meter = __chatMeterStore.getStore();
  if (meter) meter.calls++;
  const sink = sinkInScope();
  const pricedMeter = meter && meter.cost_usd !== undefined ? meter : null;
  if (!sink && !pricedMeter) return;
  try {
    const { input_tokens, output_tokens, cache_read_tokens = 0, cache_write_tokens = 0 } = input.usage;
    const uncached = Math.max(0, input_tokens - cache_read_tokens - cache_write_tokens);
    const cost_usd = estimateChatCostUsd(input.model, { ...input.usage, input_tokens: uncached });
    if (pricedMeter) {
      const price = priceFor(input.model, 'chat', pricedMeter.pricing_overrides);
      const meterCost = price === null ? null
        : price.source === 'table' && cost_usd !== null ? cost_usd
        : (input_tokens * price.pricing.input + output_tokens * price.pricing.output) / 1_000_000;
      if (meterCost === null) pricedMeter.unpriced_calls = (pricedMeter.unpriced_calls ?? 0) + 1;
      else pricedMeter.cost_usd = (pricedMeter.cost_usd ?? 0) + meterCost;
    }
    if (!sink) return;
    const record: ChatUsageRecord = {
      model: input.model,
      provider: input.provider ?? null,
      phase: input.phase ?? currentChatPhase(),
      input_tokens: Math.max(0, Math.round(input.usage.input_tokens || 0)),
      output_tokens: Math.max(0, Math.round(input.usage.output_tokens || 0)),
      cache_read_tokens: Math.max(0, Math.round(input.usage.cache_read_tokens || 0)),
      cache_write_tokens: Math.max(0, Math.round(input.usage.cache_write_tokens || 0)),
      cost_usd,
    };
    void Promise.resolve(sink(record)).catch(() => {
      /* fail-open: accounting must never break a chat call */
    });
  } catch {
    /* fail-open */
  }
}

/**
 * Standard sink: INSERT into chat_usage_log via the engine's executeRaw.
 * Positional parameters only — no JSONB, no string-built SQL. Registered by
 * the engine factory (last engine created wins; multi-brain processes log
 * against the most recently created engine — documented best-effort).
 */
export function makeEngineChatUsageSink(engine: {
  executeRaw: (sql: string, params?: unknown[]) => Promise<unknown>;
}): ChatUsageSink {
  return async (r: ChatUsageRecord): Promise<void> => {
    await engine.executeRaw(
      `INSERT INTO chat_usage_log
         (model, provider, phase, input_tokens, output_tokens,
          cache_read_tokens, cache_write_tokens, cost_usd)
       VALUES ($1, $2, $3, $4, $5, $6, $7, $8)`,
      [
        r.model,
        r.provider,
        r.phase,
        r.input_tokens,
        r.output_tokens,
        r.cache_read_tokens,
        r.cache_write_tokens,
        r.cost_usd,
      ],
    );
  };
}