@genesislcap/ai-assistant 15.19.0 → 15.19.1

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

@@ -1,237 +0,0 @@
-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

@@ -1,187 +0,0 @@
-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;
-}

package/src/utils/with-timeout.ts

@@ -1,24 +0,0 @@
-/**
- * Resolve `promise`, or **reject** if it doesn't settle within `ms`. Rejecting
- * (rather than resolving to a fallback) lets restore tell a genuine timeout apart
- * from a clean "nothing stored" result, so it can surface a notice for the former
- * and stay silent for the latter. Because the loser of the race is abandoned, a
- * late-resolving `load()` is discarded and can never clobber a now-live session;
- * a late *rejection* is swallowed so it doesn't surface as an unhandled rejection.
- *
- * @internal
- */
-export async function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-  promise.catch(() => {});
-  try {
-    return await Promise.race([
-      promise,
-      new Promise<T>((_resolve, reject) => {
-        timer = setTimeout(() => reject(new Error(`withTimeout: exceeded ${ms}ms`)), ms);
-      }),
-    ]);
-  } finally {
-    clearTimeout(timer);
-  }
-}

package/tsconfig.json

@@ -1,9 +0,0 @@
-{
-  "extends": "../../../../tsconfig.json",
-  "compilerOptions": {
-    "declarationDir": "./dist/dts",
-    "outDir": "./dist/esm",
-    "rootDir": "./src"
-  },
-  "include": ["src/**/*"]
-}