packages/kosong/src/usage.ts

/**
 * Token usage breakdown for a single LLM generation.
 *
 * Providers map their native usage counters into this common shape so
 * callers can aggregate costs without caring about the backend.
 */
export interface TokenUsage {
  /** Input tokens that were neither cache-read nor cache-created. */
  inputOther: number;
  /** Output (completion) tokens generated by the model. */
  output: number;
  /** Input tokens served from the provider's prompt cache. */
  inputCacheRead: number;
  /** Input tokens written into the provider's prompt cache. */
  inputCacheCreation: number;
}

/**
 * Compute total input tokens (other + cache read + cache creation).
 */
export function inputTotal(usage: TokenUsage): number {
  return usage.inputOther + usage.inputCacheRead + usage.inputCacheCreation;
}

/**
 * Compute grand total tokens (input total + output).
 */
export function grandTotal(usage: TokenUsage): number {
  return inputTotal(usage) + usage.output;
}

/**
 * Create a zero-valued TokenUsage.
 */
export function emptyUsage(): TokenUsage {
  return {
    inputOther: 0,
    output: 0,
    inputCacheRead: 0,
    inputCacheCreation: 0,
  };
}

/**
 * Sum two TokenUsage values.
 */
export function addUsage(a: TokenUsage, b: TokenUsage): TokenUsage {
  return {
    inputOther: a.inputOther + b.inputOther,
    output: a.output + b.output,
    inputCacheRead: a.inputCacheRead + b.inputCacheRead,
    inputCacheCreation: a.inputCacheCreation + b.inputCacheCreation,
  };
}