@genesislcap/ai-assistant 15.19.0 → 15.19.1

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

@@ -1,191 +0,0 @@
-import type { ChatMessage } from '@genesislcap/foundation-ai';
-import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
-import { addUsage, emptyUsage, messageUsage, sumUsage, totalTokens } from './sum-usage';
-
-const suite = createLogicSuite('sumUsage');
-
-const msg = (over: Partial<ChatMessage> = {}): ChatMessage =>
-  ({ role: 'assistant', content: '', ...over }) as ChatMessage;
-
-suite('returns zeroes when no message carries usage', () => {
-  const usage = sumUsage([msg({ role: 'user', content: 'hi' })]);
-  assert.equal(usage, emptyUsage());
-  assert.is(totalTokens(usage), 0);
-});
-
-suite('splits the prompt into three disjoint input buckets', () => {
-  // `inputTokens` is the WHOLE prompt; the cache fields break it down. So uncached is
-  // the remainder, and the three must re-add to the prompt exactly — that identity is
-  // what stops the buckets double-counting the prompt when summed.
-  const usage = sumUsage([
-    msg({ inputTokens: 1000, cacheReadTokens: 700, cacheWriteTokens: 200, outputTokens: 50 }),
-  ]);
-  assert.is(usage.uncachedInputTokens, 100);
-  assert.is(usage.cacheReadTokens, 700);
-  assert.is(usage.cacheWriteTokens, 200);
-  assert.is(usage.outputTokens, 50);
-  assert.is(
-    usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens,
-    1000,
-    'input buckets re-add to the prompt total',
-  );
-  assert.is(totalTokens(usage), 1050);
-});
-
-suite('treats the whole prompt as uncached when no cache split is reported', () => {
-  // Providers that report no cache breakdown (and messages persisted before the fields
-  // existed) must still contribute their full prompt, not drop it.
-  const usage = sumUsage([msg({ inputTokens: 400, outputTokens: 60 })]);
-  assert.is(usage.uncachedInputTokens, 400);
-  assert.is(usage.cacheReadTokens, 0);
-  assert.is(usage.cacheWriteTokens, 0);
-  assert.is(totalTokens(usage), 460);
-});
-
-suite('clamps uncached input at zero when buckets exceed the prompt total', () => {
-  // Malformed or hand-edited history must not be able to drive a cost display negative.
-  const usage = sumUsage([
-    msg({ inputTokens: 100, cacheReadTokens: 90, cacheWriteTokens: 90, outputTokens: 0 }),
-  ]);
-  assert.is(usage.uncachedInputTokens, 0);
-});
-
-suite('sums LLM cost and widget-reported external cost', () => {
-  const usage = sumUsage([msg({ cost: 0.25 }), msg({ externalCostUsd: 0.1, cost: 0.05 })]);
-  assert.is(Math.round(usage.costUsd * 100) / 100, 0.4);
-});
-
-suite('recurses into sub-agent traces', () => {
-  // A sub-agent's whole conversation is embedded in the parent's tool call, so this is
-  // the only place its spend is visible to a host total.
-  const usage = sumUsage([
-    msg({
-      toolCalls: [
-        {
-          id: 'tc-1',
-          name: 'delegate',
-          args: {},
-          subAgentTrace: [
-            msg({ cost: 0.2, inputTokens: 300, cacheReadTokens: 100, outputTokens: 40 }),
-          ],
-        },
-      ],
-    }),
-  ]);
-  assert.is(usage.costUsd, 0.2);
-  assert.is(usage.uncachedInputTokens, 200);
-  assert.is(usage.cacheReadTokens, 100);
-  assert.is(usage.outputTokens, 40);
-});
-
-suite('counts usage banked onto a compaction summary', () => {
-  // Compaction destroys the messages it summarises. Without the banked rollup, a total
-  // re-derived from the transcript would fall by whatever those turns had spent.
-  const before = sumUsage([
-    msg({ cost: 0.5, inputTokens: 1000, cacheReadTokens: 400, outputTokens: 100 }),
-    msg({ cost: 0.3, inputTokens: 500, outputTokens: 50 }),
-  ]);
-  const afterCompaction = sumUsage([
-    msg({
-      role: 'compacted-summary',
-      content: 'summary of the above',
-      compaction: {
-        compactedCount: 2,
-        createdAt: '2026-06-14T12:00:00.000Z',
-        rolledUpUsage: before,
-      },
-    }),
-  ]);
-  assert.equal(afterCompaction, before, 'compaction preserves the running total');
-});
-
-suite('ignores tokensBefore, which is a context reading rather than spend', () => {
-  // `tokensBefore` is one turn's context-window size. Counting it as cumulative spend
-  // would silently inflate the session total on every compaction.
-  const usage = sumUsage([
-    msg({
-      role: 'compacted-summary',
-      content: 'summary',
-      compaction: {
-        compactedCount: 3,
-        createdAt: '2026-06-14T12:00:00.000Z',
-        tokensBefore: 90_000,
-      },
-    }),
-  ]);
-  assert.is(totalTokens(usage), 0);
-});
-
-suite('addUsage adds every bucket and mutates neither operand', () => {
-  const a = { ...emptyUsage(), costUsd: 1.5, uncachedInputTokens: 100, outputTokens: 10 };
-  const b = { ...emptyUsage(), costUsd: 0.25, cacheReadTokens: 900, outputTokens: 5 };
-  const sum = addUsage(a, b);
-
-  assert.is(sum.costUsd, 1.75);
-  assert.is(sum.uncachedInputTokens, 100);
-  assert.is(sum.cacheReadTokens, 900);
-  assert.is(sum.outputTokens, 15);
-  // Both operands are live state (a row's banked figure and the session total), so a
-  // caller must be able to add without either being altered underneath it.
-  assert.is(a.costUsd, 1.5);
-  assert.is(b.cacheReadTokens, 900);
-});
-
-suite('addUsage with an empty operand is the identity', () => {
-  const a = { ...emptyUsage(), costUsd: 3, cacheWriteTokens: 42 };
-  assert.equal(addUsage(a, emptyUsage()), a);
-  assert.equal(addUsage(emptyUsage(), a), a);
-});
-
-suite('messageUsage is undefined for a message reporting nothing', () => {
-  // A user turn, or a display-only reasoning/narration split. Distinct from a zeroed
-  // usage: "this call reported nothing" is not "this call cost nothing".
-  assert.is(messageUsage(msg({ role: 'user', content: 'hi' })), undefined);
-  assert.is(messageUsage(msg({ content: 'thinking…', category: 'reasoning' })), undefined);
-});
-
-suite('messageUsage agrees with sumUsage over the same single message', () => {
-  // The two derivations are deliberately separate — `accumulate` mutates one
-  // accumulator rather than allocating per message — so pin them together. A drift
-  // here would put one figure on a turn entry and a different one in the session
-  // total, both looking plausible.
-  const cases: Partial<ChatMessage>[] = [
-    { inputTokens: 1000, cacheReadTokens: 700, cacheWriteTokens: 200, outputTokens: 50, cost: 0.4 },
-    { inputTokens: 400, outputTokens: 60 },
-    { inputTokens: 100, cacheReadTokens: 90, cacheWriteTokens: 90 },
-    { cost: 0.01, externalCostUsd: 0.02 },
-  ];
-  for (const over of cases) {
-    const m = msg(over);
-    assert.equal(
-      messageUsage(m),
-      sumUsage([m]),
-      `messageUsage must match sumUsage for ${JSON.stringify(over)}`,
-    );
-  }
-});
-
-suite('messageUsage is shallow — it prices the one request, not the tree', () => {
-  // Deliberately blind to sub-agent traces and banked compaction usage: it answers
-  // "what did this call cost", which is what a turn snapshot needs. `sumUsage` is the
-  // function that walks everything underneath.
-  const m = msg({
-    inputTokens: 100,
-    outputTokens: 10,
-    cost: 0.05,
-    toolCalls: [
-      {
-        id: 't1',
-        name: 'delegate',
-        args: {},
-        subAgentTrace: [msg({ inputTokens: 900, outputTokens: 90, cost: 0.5 })],
-      },
-    ],
-  });
-  const usage = messageUsage(m)!;
-  assert.is(usage.costUsd, 0.05, 'the child conversation is not folded in');
-  assert.is(usage.uncachedInputTokens, 100);
-  assert.ok(sumUsage([m]).costUsd > usage.costUsd, 'sumUsage does fold it in');
-});
-
-suite.run();

package/src/utils/sum-usage.ts

@@ -1,208 +0,0 @@
-import type { AggregateUsage, ChatMessage } from '@genesislcap/foundation-ai';
-
-/**
- * Zeroed {@link AggregateUsage}. A factory, not a shared const, because callers
- * accumulate into the returned object.
- *
- * @beta
- */
-export function emptyUsage(): AggregateUsage {
-  return {
-    costUsd: 0,
-    uncachedInputTokens: 0,
-    cacheReadTokens: 0,
-    cacheWriteTokens: 0,
-    outputTokens: 0,
-  };
-}
-
-/**
- * Total tokens processed — the four buckets added up. Safe to sum because the
- * buckets are disjoint (see {@link AggregateUsage}); the equivalent sum over
- * per-message fields would double-count the prompt.
- *
- * Bear in mind what this number is: because every turn resends the conversation,
- * a turn's prompt is counted again in the next turn's. It is billed throughput,
- * 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.
- *
- * @beta
- */
-export function totalTokens(usage: AggregateUsage): number {
-  return (
-    usage.uncachedInputTokens + usage.cacheReadTokens + usage.cacheWriteTokens + usage.outputTokens
-  );
-}
-
-/**
- * `a + b`, per bucket, as a new object.
- *
- * Used to lay a row's banked (pre-transcript) spend over what the live transcript
- * proves. Pure rather than in-place because both operands are live state a caller
- * must not mutate.
- *
- * @beta
- */
-export function addUsage(a: AggregateUsage, b: AggregateUsage): AggregateUsage {
-  return {
-    costUsd: a.costUsd + b.costUsd,
-    uncachedInputTokens: a.uncachedInputTokens + b.uncachedInputTokens,
-    cacheReadTokens: a.cacheReadTokens + b.cacheReadTokens,
-    cacheWriteTokens: a.cacheWriteTokens + b.cacheWriteTokens,
-    outputTokens: a.outputTokens + b.outputTokens,
-  };
-}
-
-/**
- * The four buckets plus USD for ONE message — the per-message fields projected into
- * the disjoint, addable shape, or `undefined` when the message reports no usage at
- * all (a user turn, a display-only reasoning/narration split, a provider that
- * reports none).
- *
- * Shallow by design: it does NOT recurse into `toolCalls[].subAgentTrace` and does
- * NOT count `compaction.rolledUpUsage`, so it answers "what did this one request
- * cost" rather than "what did this message and everything under it cost". Use
- * {@link sumUsage} for the latter — passing a whole transcript through this one
- * message at a time would silently drop both.
- *
- * `costUsd` folds in `externalCostUsd` (non-LLM spend a widget reported), matching
- * `sumUsage`. It is `0` when the provider priced nothing, which is NOT a claim that
- * the call was free — see {@link AggregateUsage}; `UsageRow.costUsd` is the
- * shape that keeps unpriced distinguishable, and is the right tool for a ledger.
- *
- * @beta
- */
-export function messageUsage(m: ChatMessage): AggregateUsage | undefined {
-  if (
-    m.cost == null &&
-    m.externalCostUsd == null &&
-    m.inputTokens == null &&
-    m.outputTokens == null &&
-    m.cacheReadTokens == null &&
-    m.cacheWriteTokens == null
-  ) {
-    return undefined;
-  }
-  const cacheReadTokens = m.cacheReadTokens ?? 0;
-  const cacheWriteTokens = m.cacheWriteTokens ?? 0;
-  return {
-    costUsd: (m.cost ?? 0) + (m.externalCostUsd ?? 0),
-    // The uncached REMAINDER, clamped — the same arithmetic `accumulate` below applies,
-    // for the same reasons. The two are deliberately separate implementations (that walk
-    // mutates one accumulator rather than allocating per message) and must agree;
-    // `sum-usage.test.ts` pins them together.
-    uncachedInputTokens: Math.max(0, (m.inputTokens ?? 0) - cacheReadTokens - cacheWriteTokens),
-    cacheReadTokens,
-    cacheWriteTokens,
-    outputTokens: m.outputTokens ?? 0,
-  };
-}
-
-/**
- * Sum cost and per-bucket token usage across a message list.
- *
- * One walk produces everything a usage display needs, replacing separate cost and
- * token passes over the same (potentially deep) transcript. Recurses into each
- * tool call's `subAgentTrace`, so LLM work a sub-agent did — possibly on another
- * provider at other rates — lands in the total; the driver embeds a whole
- * sub-agent conversation in the parent's tool result, so this is the only place
- * that spend is visible.
- *
- * Splitting the prompt into buckets is the point: `cost` already has the cache
- * discount applied, but a single token total cannot show that a session was cheap
- * because most of its prompt was a cache hit. The three input buckets are derived
- * from the per-message fields, where `inputTokens` is the whole prompt and the
- * cache fields break it down — so uncached input is the remainder, never an
- * addition.
- *
- * Also counts `compaction.rolledUpUsage`: compaction destroys the messages it
- * summarises, and without their banked usage every total re-derived from the
- * transcript would drop by whatever those turns had already spent.
- *
- * 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.
- *
- * @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();
-  accumulate(messages, total);
-  return total;
-}
-
-/** Add `from` into `into`, in place. */
-function addInto(into: AggregateUsage, from: AggregateUsage): void {
-  into.costUsd += from.costUsd;
-  into.uncachedInputTokens += from.uncachedInputTokens;
-  into.cacheReadTokens += from.cacheReadTokens;
-  into.cacheWriteTokens += from.cacheWriteTokens;
-  into.outputTokens += from.outputTokens;
-}
-
-/**
- * Walk `messages`, accumulating into `into`. Mutates a single accumulator rather
- * than merging returned objects — this runs on every transcript change, so the
- * per-message allocation is worth avoiding.
- */
-function accumulate(messages: readonly ChatMessage[], into: AggregateUsage): void {
-  for (const m of messages) {
-    // Provider/LLM cost plus any non-LLM cost a widget reported for its own
-    // external service calls. Both are real spend on this session.
-    if (m.cost != null) into.costUsd += m.cost;
-    if (m.externalCostUsd != null) into.costUsd += m.externalCostUsd;
-
-    const cacheRead = m.cacheReadTokens ?? 0;
-    const cacheWrite = m.cacheWriteTokens ?? 0;
-    into.cacheReadTokens += cacheRead;
-    into.cacheWriteTokens += cacheWrite;
-    // The uncached remainder of the prompt. Clamped at zero so malformed or
-    // hand-edited history whose buckets exceed the prompt total can't drive the
-    // session total negative — a wrong-but-plausible number is worse than a
-    // conservative one here, since this feeds a cost display.
-    into.uncachedInputTokens += Math.max(0, (m.inputTokens ?? 0) - cacheRead - cacheWrite);
-    into.outputTokens += m.outputTokens ?? 0;
-
-    // Spend banked by a compaction on this summary's behalf. NOTE: deliberately
-    // not `compaction.tokensBefore` — that is a one-turn context-window reading,
-    // not cumulative spend, and counting it here would inflate the total.
-    const rolled = m.compaction?.rolledUpUsage;
-    if (rolled) addInto(into, rolled);
-
-    for (const tc of m.toolCalls ?? []) {
-      if (tc.subAgentTrace) accumulate(tc.subAgentTrace, into);
-    }
-  }
-}

package/src/utils/tool-fold.ts

@@ -1,181 +0,0 @@
-import type { ChatToolDefinition, ChatToolHandlers } from '@genesislcap/foundation-ai';
-
-/**
- * Symbol used to attach ToolFold metadata to a facade handler function.
- * The ChatDriver inspects this to detect fold facades at runtime.
- *
- * @internal
- */
-export const TOOL_FOLD_SYMBOL = Symbol('toolFold');
-
-/**
- * Internal metadata for a tool fold. Attached to the facade handler via TOOL_FOLD_SYMBOL.
- *
- * @internal
- */
-export interface ToolFold {
-  /** Facade tool name. */
-  name: string;
-  /** Description shown to the model. */
-  description: string;
-  /** Optional guidance injected in the fold-open response. */
-  usageNotes?: string;
-  /** Tool definitions inside this fold. */
-  tools: ChatToolDefinition[];
-  /** Handlers for the inner tools (keyed by tool name). */
-  handlers: ChatToolHandlers;
-  /**
-   * When true (default), all other tools are removed when this fold opens —
-   * the model can only see this fold's tools until it closes.
-   * When false, sibling tools remain alongside the inner tools.
-   */
-  exclusive: boolean;
-}
-
-/**
- * The value returned by `createToolFold`.
- *
- * @beta
- */
-export interface ToolFoldResult {
-  /**
-   * The facade tool definition. Add this to your agent's `toolDefinitions`.
-   * It is a regular `ChatToolDefinition` with an empty parameter schema.
-   */
-  definition: ChatToolDefinition;
-  /**
-   * The facade handler — a single-entry map keyed by the fold name.
-   * Spread this into your agent's `toolHandlers`.
-   * Inner tool handlers are NOT included here — they are encapsulated inside
-   * the fold metadata and installed by the driver only when the fold opens.
-   */
-  handler: ChatToolHandlers;
-}
-
-/**
- * Creates a tool fold — a facade that hides a group of related tools behind a single
- * named entry, revealing them progressively when the model invokes the facade.
- *
- * The `tools` and `handlers` parameters accept the exact same types as `AgentConfig.toolDefinitions`
- * and `AgentConfig.toolHandlers`, so existing tool creation functions can be passed in unchanged.
- *
- * @example
- * ```typescript
- * const tradingTools = createToolFold({
- *   name: 'trading_tools',
- *   tools: createTradesToolDefinitions(),
- *   handlers: createTradesToolHandlers(connect),
- * });
- *
- * const agent: AgentConfig = {
- *   name: 'Trades',
- *   systemPrompt: '...',
- *   toolDefinitions: [getCurrentDateDef, tradingTools.definition],
- *   toolHandlers: { get_current_date: handler, ...tradingTools.handler },
- * };
- * ```
- *
- * @example Nesting folds
- * ```typescript
- * const insertFold = createToolFold({
- *   name: 'trade_insertion',
- *   tools: [validateDef, insertDef],
- *   handlers: { validate_trade: vHandler, insert_trade: iHandler },
- * });
- *
- * const tradingFold = createToolFold({
- *   name: 'trading_tools',
- *   tools: [searchDef, insertFold.definition],
- *   handlers: { search_trades: sHandler, ...insertFold.handler },
- * });
- * ```
- *
- * @beta
- */
-export function createToolFold(config: {
-  /** Facade tool name — used as the tool name the model calls to open this fold. */
-  name: string;
-  /**
-   * Description shown to the model for the facade tool.
-   * If omitted, auto-generated from the inner tool names:
-   * "Contains: tool_a, tool_b. Invoke to access these tools."
-   */
-  description?: string;
-  /**
-   * Optional usage guidance injected into the fold-open response message.
-   * Not included in the facade description — only visible once the fold is open.
-   */
-  usageNotes?: string;
-  /** Inner tool definitions. Same type as `AgentConfig.toolDefinitions`. */
-  tools: ChatToolDefinition[];
-  /** Inner tool handlers. Same type as `AgentConfig.toolHandlers`. */
-  handlers: ChatToolHandlers;
-  /**
-   * When true (default), all other tools are removed when this fold opens.
-   * When false, sibling tools remain available alongside the inner tools.
-   */
-  exclusive?: boolean;
-}): ToolFoldResult {
-  const description =
-    config.description ??
-    `Contains: ${config.tools.map((t) => t.name).join(', ')}. Invoke to access these tools.`;
-
-  const fold: ToolFold = {
-    name: config.name,
-    description,
-    usageNotes: config.usageNotes,
-    tools: config.tools,
-    handlers: config.handlers,
-    exclusive: config.exclusive ?? true,
-  };
-
-  const definition: ChatToolDefinition = {
-    name: config.name,
-    description,
-    parameters: { type: 'object', properties: {} },
-  };
-
-  // The facade handler body is never actually called — the driver intercepts it
-  // via TOOL_FOLD_SYMBOL before dispatch. The body is a no-op fallback.
-  const facadeHandler = async (): Promise<string> => `Fold: ${config.name}`;
-  (facadeHandler as any)[TOOL_FOLD_SYMBOL] = fold;
-
-  return {
-    definition,
-    handler: {
-      [config.name]: facadeHandler,
-    },
-  };
-}
-
-/**
- * A tool entry in the expanded debug tree.
- * Folds are represented as nodes with a `tools` array; regular tools have none.
- *
- * @beta
- */
-export interface ToolTreeNode extends ChatToolDefinition {
-  /** Present when this tool is a fold — contains its inner tools recursively expanded. */
-  tools?: ToolTreeNode[];
-}
-
-/**
- * Expands a flat list of tool definitions into a nested tree by resolving fold
- * metadata from the corresponding handlers. Use this for debug output so the
- * full tool hierarchy is visible rather than just the top-level facade names.
- *
- * @beta
- */
-export function expandToolTree(
-  definitions: ChatToolDefinition[],
-  handlers: ChatToolHandlers,
-): ToolTreeNode[] {
-  return definitions.map((def) => {
-    const handler = handlers[def.name];
-    const fold: ToolFold | undefined = handler ? (handler as any)[TOOL_FOLD_SYMBOL] : undefined;
-    if (fold) {
-      return { ...def, tools: expandToolTree(fold.tools, fold.handlers) };
-    }
-    return { ...def };
-  });
-}