@genesislcap/ai-assistant 15.10.6 → 15.12.0

package/src/utils/sum-usage.ts

@@ -4,7 +4,7 @@ import type { AggregateUsage, ChatMessage } from '@genesislcap/foundation-ai';
  * Zeroed {@link AggregateUsage}. A factory, not a shared const, because callers
  * accumulate into the returned object.
  *
- * @internal
+ * @beta
  */
 export function emptyUsage(): AggregateUsage {
   return {
@@ -26,7 +26,7 @@ export function emptyUsage(): AggregateUsage {
  * NOT the count of distinct tokens in the conversation, so it grows
  * super-linearly with turn count and is expected to dwarf the context size.
  *
- * @internal
+ * @beta
  */
 export function totalTokens(usage: AggregateUsage): number {
   return (
@@ -41,7 +41,7 @@ export function totalTokens(usage: AggregateUsage): number {
  * proves. Pure rather than in-place because both operands are live state a caller
  * must not mutate.
  *
- * @internal
+ * @beta
  */
 export function addUsage(a: AggregateUsage, b: AggregateUsage): AggregateUsage {
   return {
@@ -77,7 +77,40 @@ export function addUsage(a: AggregateUsage, b: AggregateUsage): AggregateUsage {
  * Returns a zeroed total when no message carries usage — providers that report
  * none (e.g. Chrome built-in) are skipped silently rather than guessed at.
  *
- * @internal
+ * @remarks
+ * This sums the WHOLE array, which is the right answer only when the array is the
+ * whole of the work being billed. A driver whose conversation **continues across
+ * rounds** opens its history with turns an earlier round already paid for, so
+ * summing it again bills them twice — and the session total then grows
+ * quadratically in the number of rounds while every individual figure in it stays
+ * correct. Nothing about the result looks wrong, which is why it is called out
+ * here rather than left to the caller to notice.
+ *
+ * Do NOT solve this with a "sum from this message onwards" marker. Compaction
+ * *replaces* the messages it summarises — and compaction is one of this function's
+ * own call sites — so the marker message can be absent from history by the time
+ * the sum runs, leaving the caller to either fail or silently sum everything,
+ * which is the double-count the marker was meant to prevent.
+ *
+ * Instead hold a **banked baseline**: spend that predates the current transcript,
+ * carried as a value, with `usage = banked + live` composed via {@link addUsage}.
+ * `resolveBankedUsage` in `utils/cost-session-history.ts` is the worked form, and
+ * the shape of its signature is the load-bearing part. It separates three cases:
+ *
+ * 1. no prior record — a genuine first round, so nothing is banked;
+ * 2. prior record, and the live transcript already accounts for it (a restored
+ *    session) — carry the prior record's own banked figure forward;
+ * 3. prior record, and the transcript starts empty — bank the prior record's
+ *    whole total, because nothing in the transcript can re-derive it.
+ *
+ * Case 1 and case 3 take the same arithmetic and mean opposite things, so the
+ * prior record must be a **required** input with no zero-defaulting path: a
+ * caller who carries a transcript and forgets its baseline reports the entire
+ * prior conversation as this round's spend. Distinguishing 2 from 3 is a separate
+ * decision, and getting it wrong is destructive in the other direction — it
+ * rewrites a total down to the current page-load and drops earlier spend.
+ *
+ * @beta
  */
 export function sumUsage(messages: readonly ChatMessage[]): AggregateUsage {
   const total = emptyUsage();

package/src/utils/usage-rows.test.ts

@@ -0,0 +1,237 @@
+import type { AggregateUsage, ChatMessage } from '@genesislcap/foundation-ai';
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { sumUsage } from './sum-usage';
+import { usageRows } from './usage-rows';
+
+const msg = (over: Partial<ChatMessage>): ChatMessage =>
+  ({ role: 'assistant', content: '', ...over }) as ChatMessage;
+
+const rolled = (over: Partial<AggregateUsage>): AggregateUsage => ({
+  costUsd: 0,
+  uncachedInputTokens: 0,
+  cacheReadTokens: 0,
+  cacheWriteTokens: 0,
+  outputTokens: 0,
+  ...over,
+});
+
+/** Every place spend can hide, in one transcript: a delegation and a compaction. */
+const richHistory = (): ChatMessage[] => [
+  msg({
+    role: 'compacted-summary',
+    content: 'summary',
+    compaction: {
+      compactedCount: 4,
+      rolledUpUsage: rolled({ costUsd: 0.05, uncachedInputTokens: 400, outputTokens: 60 }),
+      // The summariser's model — NOT what the banked spend ran on.
+      model: 'claude-haiku-4-5-20251001',
+    },
+  } as Partial<ChatMessage>),
+  msg({ role: 'user', content: 'go' }),
+  msg({
+    model: 'claude-sonnet-5',
+    agentName: 'boss',
+    cost: 0.01,
+    inputTokens: 1_000,
+    cacheReadTokens: 900,
+    outputTokens: 50,
+    toolCalls: [
+      {
+        id: 'tc1',
+        name: 'delegate',
+        args: {},
+        subAgentTrace: [
+          msg({
+            model: 'gemini-2.5-flash',
+            agentName: 'worker',
+            cost: 0.12,
+            inputTokens: 500,
+            outputTokens: 200,
+          }),
+        ],
+      },
+    ],
+  }),
+];
+
+const suite = createLogicSuite('usageRows');
+
+suite('reconciles exactly with sumUsage over the same input', () => {
+  // THE guarantee. A per-call view that disagrees with the total is worse than none,
+  // because both look right in isolation — which is how the consumer's own copy
+  // under-reported for a month.
+  const history = richHistory();
+  const rows = usageRows(history);
+  const total = sumUsage(history);
+
+  const rowCost = rows.reduce((n, r) => n + (r.costUsd ?? 0) + (r.externalCostUsd ?? 0), 0);
+  assert.ok(Math.abs(rowCost - total.costUsd) < 1e-12, `${rowCost} vs ${total.costUsd}`);
+
+  const bucket = (
+    k: 'uncachedInputTokens' | 'cacheReadTokens' | 'cacheWriteTokens' | 'outputTokens',
+  ) => rows.reduce((n, r) => n + r[k], 0);
+  assert.is(bucket('uncachedInputTokens'), total.uncachedInputTokens, 'uncached input');
+  assert.is(bucket('cacheReadTokens'), total.cacheReadTokens, 'cache read');
+  assert.is(bucket('cacheWriteTokens'), total.cacheWriteTokens, 'cache write');
+  assert.is(bucket('outputTokens'), total.outputTokens, 'output');
+});
+
+suite('emits a compaction row so banked spend is not lost from a per-call view', () => {
+  // The shortfall this function exists to close: the summary message carries no
+  // `cost` and no token fields of its own, so a naive per-message walk drops the
+  // spend of every turn the compaction deleted.
+  const rows = usageRows(richHistory());
+  const compactionRows = rows.filter((r) => r.source === 'compaction');
+  assert.is(compactionRows.length, 1);
+  assert.is(compactionRows[0].costUsd, 0.05);
+  assert.is(compactionRows[0].uncachedInputTokens, 400);
+  assert.is(
+    compactionRows[0].model,
+    undefined,
+    'no model — the banked spend may span several, and compaction.model is the summariser',
+  );
+});
+
+suite('recurses into sub-agent traces, tagging depth and the spawning call', () => {
+  const rows = usageRows(richHistory());
+  const child = rows.find((r) => r.model === 'gemini-2.5-flash');
+  assert.ok(child, 'the sub-agent turn produced a row');
+  assert.is(child!.subAgentDepth, 1);
+  assert.is(child!.subAgentOf, 'tc1');
+  assert.is(child!.agentName, 'worker');
+  const parent = rows.find((r) => r.model === 'claude-sonnet-5');
+  assert.is(parent!.subAgentDepth, 0);
+  assert.is(parent!.subAgentOf, undefined);
+});
+
+suite('prefers the provider the driver stamped over re-deriving it from the model', () => {
+  // `ChatMessage.provider` comes from the resolved provider's own status, so it is
+  // authoritative and knows vendors the model allowlists do not. Re-deriving from the
+  // model id alone drops attribution for a server-proxied turn — exactly the rows a
+  // usage ledger cares most about getting right. PR review.
+  const rows = usageRows([
+    msg({ model: 'gpt-5', provider: 'openai', cost: 1, inputTokens: 1 } as Partial<ChatMessage>),
+    // Stamped provider disagrees with what the model id would derive: the stamp still wins.
+    msg({
+      model: 'claude-sonnet-5',
+      provider: 'chrome',
+      cost: 1,
+      inputTokens: 1,
+    } as Partial<ChatMessage>),
+  ]);
+  assert.equal(
+    rows.map((r) => r.provider),
+    ['openai', 'chrome'],
+  );
+});
+
+suite('resolves the provider from the model, and leaves it unset when unknown', () => {
+  const rows = usageRows([
+    msg({ model: 'claude-sonnet-5', cost: 1, inputTokens: 1 }),
+    msg({ model: 'gemini-2.5-flash', cost: 1, inputTokens: 1 }),
+    msg({ model: 'gpt-5', cost: 1, inputTokens: 1 }),
+    msg({ cost: 1, inputTokens: 1 }),
+  ]);
+  assert.equal(
+    rows.map((r) => r.provider),
+    ['anthropic', 'gemini', undefined, undefined],
+    'an unrecognised or absent model leaves provider unset rather than guessing',
+  );
+});
+
+suite('splits the prompt into buckets the same way sumUsage does', () => {
+  const [row] = usageRows([
+    msg({
+      model: 'claude-sonnet-5',
+      inputTokens: 1_000,
+      cacheReadTokens: 600,
+      cacheWriteTokens: 300,
+    }),
+  ]);
+  assert.is(row.uncachedInputTokens, 100, 'the remainder, not an addition');
+  assert.is(row.cacheReadTokens, 600);
+  assert.is(row.cacheWriteTokens, 300);
+});
+
+suite('clamps a prompt whose cache buckets exceed the total', () => {
+  const [row] = usageRows([msg({ inputTokens: 100, cacheReadTokens: 900 })]);
+  assert.is(row.uncachedInputTokens, 0, 'never negative');
+});
+
+suite('leaves costUsd undefined when nothing was reported, rather than zero', () => {
+  // What the "carried usage but no cost" audit keys off. A zero here would read as a
+  // free call and the alarm would never fire.
+  const [row] = usageRows([msg({ model: 'claude-sonnet-5', inputTokens: 500, outputTokens: 10 })]);
+  assert.is(row.costUsd, undefined);
+  assert.is(row.source, 'request');
+});
+
+suite('records external (non-LLM) cost and counts it in the reconciliation', () => {
+  const history = [msg({ externalCostUsd: 0.4 }), msg({ model: 'claude-sonnet-5', cost: 0.1 })];
+  const rows = usageRows(history);
+  assert.is(rows.find((r) => r.externalCostUsd != null)!.externalCostUsd, 0.4);
+  const rowCost = rows.reduce((n, r) => n + (r.costUsd ?? 0) + (r.externalCostUsd ?? 0), 0);
+  assert.ok(Math.abs(rowCost - sumUsage(history).costUsd) < 1e-12);
+});
+
+suite('produces no row for a message carrying no usage', () => {
+  assert.equal(
+    usageRows([
+      msg({ role: 'user', content: 'hello' }),
+      msg({ content: 'thinking out loud', category: 'reasoning' }),
+    ]),
+    [],
+  );
+});
+
+suite('is empty for an empty transcript', () => {
+  assert.equal(usageRows([]), []);
+});
+
+suite('reconciles on a nested delegation two levels deep', () => {
+  const history = [
+    msg({
+      model: 'claude-sonnet-5',
+      cost: 0.01,
+      inputTokens: 100,
+      toolCalls: [
+        {
+          id: 'a',
+          name: 'delegate',
+          args: {},
+          subAgentTrace: [
+            msg({
+              model: 'claude-sonnet-5',
+              cost: 0.02,
+              inputTokens: 200,
+              toolCalls: [
+                {
+                  id: 'b',
+                  name: 'delegate',
+                  args: {},
+                  subAgentTrace: [msg({ model: 'gemini-2.5-flash', cost: 0.04, inputTokens: 400 })],
+                },
+              ],
+            }),
+          ],
+        },
+      ],
+    }),
+  ];
+  const rows = usageRows(history);
+  assert.equal(
+    rows.map((r) => r.subAgentDepth),
+    [0, 1, 2],
+  );
+  const rowCost = rows.reduce((n, r) => n + (r.costUsd ?? 0), 0);
+  assert.ok(Math.abs(rowCost - sumUsage(history).costUsd) < 1e-12, 'still reconciles');
+});
+
+suite('does not mutate the transcript', () => {
+  const history = richHistory();
+  const before = JSON.stringify(history);
+  usageRows(history);
+  assert.is(JSON.stringify(history), before, 'a projection, not a transform');
+});
+
+suite.run();

package/src/utils/usage-rows.ts

@@ -0,0 +1,187 @@
+import type { AggregateUsage, AIProviderType, ChatMessage } from '@genesislcap/foundation-ai';
+import { vendorOfModel } from '@genesislcap/foundation-ai';
+
+/**
+ * One billable unit of spend, projected out of a transcript.
+ *
+ * @remarks
+ * Deliberately **not** a `ChatMessage`, and not an extension of one. A row is a
+ * derived record for a ledger, and keeping the types distinct makes the one
+ * dangerous mistake — feeding rows back into `sumUsage`, which does its own
+ * recursion and would count everything twice — a compile error rather than a
+ * plausible wrong number.
+ *
+ * @beta
+ */
+export interface UsageRow {
+  /**
+   * Where the spend came from.
+   *
+   * - `'request'` — one model call, with a message behind it.
+   * - `'compaction'` — spend **banked** by a compaction. The turns that incurred it
+   *   were summarised and deleted, so there is no single call to attribute it to;
+   *   the amount survives on the summary's `compaction.rolledUpUsage`. Emitted as
+   *   its own row because otherwise this money is simply missing from a per-call
+   *   view while remaining present in the total, and the two disagree silently.
+   */
+  source: 'request' | 'compaction';
+  /**
+   * Model that produced the call. `undefined` on a `'compaction'` row: the banked
+   * spend covers however many turns were summarised, which may have run on
+   * different models, so attributing it to one would invent a fact. (The summary's
+   * `compaction.model` is the model that did the *summarising* — a different thing,
+   * and not what this spend was.)
+   */
+  model?: string;
+  /**
+   * Vendor that served the call. Taken from the provider the driver stamped on the message,
+   * which is authoritative and covers vendors the model allowlists do not — a server-proxied
+   * `gpt-5` turn is `'openai'` here and unknown to `vendorOfModel`. Falls back to resolving
+   * {@link UsageRow.model} through `vendorOfModel` only for messages persisted before that
+   * field existed, and is left unset when neither knows rather than guessed at.
+   */
+  provider?: AIProviderType;
+  /**
+   * USD for this row, as reported by the provider and stamped by the transport.
+   *
+   * `undefined` means no cost was reported — **not** zero. Nothing here estimates
+   * one from the token counts: an estimate is plausible, unremarkable and quietly
+   * wrong, whereas a total that is visibly too low gets investigated. A row with
+   * tokens but no `costUsd` is worth alarming on; that is the shape that check needs.
+   */
+  costUsd?: number;
+  /** Non-LLM spend a host reported for this turn (an external service it called). */
+  externalCostUsd?: number;
+  /** Prompt tokens billed at the full uncached rate — the remainder after the cache buckets. */
+  uncachedInputTokens: number;
+  /** Prompt tokens served from the provider's cache. */
+  cacheReadTokens: number;
+  /** Prompt tokens written to the provider's cache. */
+  cacheWriteTokens: number;
+  /** Generated tokens, including reasoning tokens the provider bills as output. */
+  outputTokens: number;
+  /** Agent that produced the call, when known. */
+  agentName?: string;
+  /** Delegation depth: 0 for the top-level conversation, 1 for a sub-agent, 2 for its sub-agent, … */
+  subAgentDepth: number;
+  /** Id of the tool call that spawned this row's conversation — correlates a row back to its delegation. */
+  subAgentOf?: string;
+}
+
+/** Whether a message carries anything a ledger would record. */
+function hasUsage(m: ChatMessage): boolean {
+  return (
+    m.cost != null ||
+    m.externalCostUsd != null ||
+    m.inputTokens != null ||
+    m.outputTokens != null ||
+    m.cacheReadTokens != null ||
+    m.cacheWriteTokens != null
+  );
+}
+
+/**
+ * Project a transcript into one row per billable unit of spend.
+ *
+ * @remarks
+ * Reads the messages and returns a table; it stores nothing, mutates nothing, and
+ * adds nothing to history. Use it where an **aggregate is not enough** — writing
+ * usage rows for per-project attribution, a cost dashboard, or auditing which turns
+ * came back unpriced. For a single total, `sumUsage` is the answer and this is the
+ * wrong tool.
+ *
+ * Walks the same shape `sumUsage` does, and is guaranteed to agree with it: summing
+ * `costUsd` and `externalCostUsd` across these rows equals `sumUsage(...).costUsd`
+ * over the same input, and the four token buckets reconcile likewise. That property
+ * is the point of the function — a per-call view that quietly disagrees with the
+ * total is worse than no per-call view, because both look right in isolation.
+ *
+ * Covers the two places spend hides:
+ *
+ * - **Sub-agent conversations.** A delegating tool call carries the child's entire
+ *   conversation on `toolCall.subAgentTrace`, so a walk of top-level messages alone
+ *   misses everything a delegating agent spent. A consumer that reimplemented this
+ *   and omitted the branch reported $0.106 on a run that cost $0.234.
+ * - **Compactions.** A compaction deletes the messages it summarises, banking their
+ *   spend on the summary. Those turns produce a single `source: 'compaction'` row.
+ *
+ * Messages carrying no usage at all (a user turn, a narration) produce no row.
+ *
+ * **Do not pass the result to `sumUsage`** — the types prevent it, and the reason is
+ * that both recurse, so a pre-flattened list would be counted twice. Both functions
+ * take raw history.
+ *
+ * @beta
+ */
+export function usageRows(messages: readonly ChatMessage[]): UsageRow[] {
+  return collectRows(messages, 0, undefined);
+}
+
+/** Map an already-bucketed {@link AggregateUsage} onto a row's token fields. */
+function bucketsOf(
+  usage: AggregateUsage,
+): Pick<UsageRow, 'uncachedInputTokens' | 'cacheReadTokens' | 'cacheWriteTokens' | 'outputTokens'> {
+  return {
+    uncachedInputTokens: usage.uncachedInputTokens,
+    cacheReadTokens: usage.cacheReadTokens,
+    cacheWriteTokens: usage.cacheWriteTokens,
+    outputTokens: usage.outputTokens,
+  };
+}
+
+function collectRows(
+  messages: readonly ChatMessage[],
+  depth: number,
+  subAgentOf: string | undefined,
+): UsageRow[] {
+  const rows: UsageRow[] = [];
+  for (const m of messages) {
+    if (hasUsage(m)) {
+      const cacheReadTokens = m.cacheReadTokens ?? 0;
+      const cacheWriteTokens = m.cacheWriteTokens ?? 0;
+      rows.push({
+        source: 'request',
+        model: m.model,
+        // The driver stamps `ChatMessage.provider` from the resolved provider's own
+        // status, so it is AUTHORITATIVE and covers vendors the model allowlists do
+        // not — a server-proxied `gpt-5` turn is `provider: 'openai'` on the message
+        // and unknown to `vendorOfModel`. Prefer it; fall back to resolving the model
+        // id only for messages persisted before the field existed. Still left
+        // undefined when neither knows, rather than guessed at.
+        provider: m.provider ?? (m.model ? vendorOfModel(m.model) : undefined),
+        ...(m.cost != null && { costUsd: m.cost }),
+        ...(m.externalCostUsd != null && { externalCostUsd: m.externalCostUsd }),
+        // Uncached input is the REMAINDER, matching `sumUsage`: `inputTokens` is the
+        // whole prompt and the cache fields break it down. Clamped for the same
+        // reason — hand-edited history must not drive a total negative.
+        uncachedInputTokens: Math.max(0, (m.inputTokens ?? 0) - cacheReadTokens - cacheWriteTokens),
+        cacheReadTokens,
+        cacheWriteTokens,
+        outputTokens: m.outputTokens ?? 0,
+        ...(m.agentName != null && { agentName: m.agentName }),
+        subAgentDepth: depth,
+        ...(subAgentOf != null && { subAgentOf }),
+      });
+    }
+
+    // Spend the compaction banked on this summary's behalf. Its buckets are already
+    // disjoint (it is an `AggregateUsage`), so they map across without the
+    // subtraction a per-message record needs.
+    const rolled = m.compaction?.rolledUpUsage;
+    if (rolled) {
+      rows.push({
+        source: 'compaction',
+        ...(rolled.costUsd != null && { costUsd: rolled.costUsd }),
+        ...bucketsOf(rolled),
+        ...(m.agentName != null && { agentName: m.agentName }),
+        subAgentDepth: depth,
+        ...(subAgentOf != null && { subAgentOf }),
+      });
+    }
+
+    for (const tc of m.toolCalls ?? []) {
+      if (tc.subAgentTrace) rows.push(...collectRows(tc.subAgentTrace, depth + 1, tc.id));
+    }
+  }
+  return rows;
+}