@genesislcap/ai-assistant 15.3.3 → 15.3.4-GENC-1475.2

package/dist/ai-assistant.d.ts

@@ -1,4 +1,5 @@
 import { AgentPickerMode } from '@genesislcap/foundation-ai';
+import type { AggregateUsage } from '@genesislcap/foundation-ai';
 import { AIProviderRegistry } from '@genesislcap/foundation-ai';
 import type { AIProviderRegistryStatusEntry } from '@genesislcap/foundation-ai';
 import type { AIProviderType } from '@genesislcap/foundation-ai';
@@ -1698,21 +1699,58 @@ declare type ChatInteractionEventsMap = {
 
 export { ChatToolChoice }
 
-/** A model used during a finalized cost session. */
+/** A model used during a recorded cost session. */
 export declare interface CostSessionModelEntry {
     model: string;
     /** Vendor id from `getStatus()` (e.g. `'anthropic'`, `'gemini'`). */
     provider?: AIProviderType;
 }
 
-/** Persisted snapshot of a completed assistant cost session. */
+/** Persisted usage record for one project's assistant work. */
 export declare interface CostSessionRecord {
     id: string;
+    /**
+     * Stable identity of the work this row stands for — the assistant's session key
+     * (a project id, for hosts that key sessions per project). The upsert key: a row
+     * is one project's lifetime usage, so re-reporting the same key REPLACES the row
+     * rather than adding another.
+     */
+    projectKey: string;
     title: string;
-    /** ISO-8601 timestamp when the session was finalized. */
-    endedAt: string;
-    costUsd: number;
-    tokensConsumed: number;
+    /**
+     * ISO-8601 timestamp of the most recent usage recorded for this row.
+     *
+     * Named for what it is: the row is upserted as spend accrues, so this moves. It is
+     * NOT an end time — a row has no terminal state, because a project can always be
+     * worked on again.
+     */
+    updatedAt: string;
+    /**
+     * Cost plus the four token buckets — the same shape the live session tile renders, so
+     * a history row can show the identical breakdown instead of a lone merged total that
+     * cannot explain a large token count at a small cost.
+     *
+     * This is the project's **lifetime** usage: `banked` plus whatever the live transcript
+     * currently proves.
+     */
+    usage: AggregateUsage;
+    /**
+     * Spend that predates the current transcript, and so cannot be re-derived from it.
+     *
+     * Without this a row could only ever report what the open transcript proves. That is
+     * fine when the transcript is restored on load (it *is* the project's history), but
+     * where it starts empty every refresh the row would be rewritten downwards on the next
+     * turn and the project's earlier spend lost. Banking it keeps `usage` a lifetime figure
+     * in both cases.
+     *
+     * Deliberately part of the row rather than element state: two assistant instances (a
+     * docked bubble and a popped-out panel) share one session, and both write this row. A
+     * value derived from the row keeps every write idempotent, whereas an element-held
+     * accumulator would be applied once per instance.
+     *
+     * Optional: rows written before this existed have none, which reads as "nothing banked".
+     */
+    banked?: AggregateUsage;
     models: CostSessionModelEntry[];
 }
 
@@ -1905,10 +1943,13 @@ export declare interface FallbackAgentConfig extends BaseAgentConfig {
  *
  * Popout/collapse coordination uses `agenticActivityBus` topics `chat-popout` and `chat-popin` — not DOM `CustomEvent`s on this element.
  *
- * **Cost build history:** opt-in via `chatConfig.costHistory.enabled`. When enabled,
- * finalized sessions persist in `localStorage` (scoped by `costHistory.scope`, the
- * element `id`, or `'default'`). Snapshots run on tab close and when the session
- * title changes; hosts may call {@link FoundationAiAssistant.finalizeCostSession}.
+ * **Cost build history:** opt-in via `chatConfig.costHistory.enabled`. When enabled, each
+ * session's usage is kept as exactly ONE row per session key in `localStorage` (scoped by
+ * `costHistory.scope`, the element `id`, or `'default'`), upserted as spend accrues. So a
+ * row is a project's lifetime usage rather than a visit to it, and the Cost tab's total is
+ * the sum of the rows alone — the live session is never added on top, because the active
+ * project's own row already reflects it. Hosts may call
+ * {@link FoundationAiAssistant.finalizeCostSession} to flush early; it is idempotent.
  *
  * @fires chat-header-mousedown - Fired when the user presses the chat header in `popout-mode="expand"` (for drag-to-popout hosts). Bubbles and composed. detail: `ChatHeaderMouseDownDetail`
  * @fires session-cleared - Fired after the session is wiped (the lifecycle menu's Clear). The payload is captured before teardown so the host can clean up any external state the active agent was working on. Bubbles and composed. detail: `SessionClearedDetail`
@@ -2141,25 +2182,91 @@ export declare class FoundationAiAssistant extends GenesisElement {
     /** Context window size for the active model, if known. */
     get contextLimit(): number | undefined;
     set contextLimit(value: number | undefined);
-    /** Aggregated USD cost across every chat turn in this session. */
+    /**
+     * Cost plus the four token buckets for this session — derived from the transcript
+     * on every change, so it includes sub-agent turns and spend banked by a compaction.
+     */
+    get sessionUsage(): AggregateUsage;
+    set sessionUsage(value: AggregateUsage);
+    /**
+     * Aggregated USD cost across every chat turn in this session.
+     *
+     * Read-only (unlike previously): it is a projection of `sessionUsage`, and a
+     * host assigning it would have set a figure the next transcript change overwrites.
+     */
     get sessionCostUsd(): number;
-    set sessionCostUsd(value: number);
-    /** Saved build history plus the in-flight session — shown on the Cost tab summary. */
+    /**
+     * Lifetime usage across every project in the history scope — cost and all four token
+     * buckets. What the Cost tab's lifetime section renders.
+     *
+     * Rows ONLY — deliberately not rows + live session. Each row holds a project's lifetime
+     * usage and the active project's row is kept current on every transcript change, so
+     * adding the live total would count this project's spend twice. That double-count is what
+     * made the figure grow on every refresh: a page-hide banked a row while the restored
+     * session still carried the same spend.
+     */
+    get cumulativeUsage(): AggregateUsage;
+    /** Lifetime USD across every project in the history scope. */
     get cumulativeCostUsd(): number;
+    /**
+     * Whether the live session figures amount to this project's whole history, which is true
+     * exactly when the transcript is restored on load. Drives the Cost tab's live labels
+     * ("Project cost" vs "Session cost") so they state the scope rather than imply one.
+     *
+     * Note this is NOT what makes the *rows* lifetime — those bank their pre-transcript spend
+     * (see `CostSessionRecord.banked`) and are lifetime either way.
+     */
+    get liveUsageIsProjectLifetime(): boolean;
     /** Resolved cost tab and build-history settings from `chatConfig.costHistory`. */
     get resolvedCostHistory(): ResolvedCostHistoryConfig;
-    /** Cumulative input + output tokens across every chat turn in this session. */
+    /**
+     * Total tokens across every chat turn in this session — all four buckets added up.
+     * Read-only; the per-bucket split is on `sessionUsage`.
+     */
     get sessionTokensConsumed(): number;
-    set sessionTokensConsumed(value: number);
     /** Label shown on the Cost tab for the in-flight session (app title or first user phrase). */
     get liveCostSessionTitle(): string | undefined;
     /**
-     * Snapshot the running session into persisted build history (`localStorage`).
-     * No-op unless `chatConfig.costHistory.enabled` is `true`.
+     * Write this session's usage into persisted build history (`localStorage`) as a single
+     * row keyed by the session key, replacing any existing row for that key.
+     *
+     * **Idempotent** — safe to call per turn, on tab close, and on a title change alike.
+     * The name is historical: it does NOT end the session or reset the running totals.
+     * Resetting them is what used to double-count spend, since the row was banked while the
+     * persisted transcript still carried the same usage, so a reload restored it and the
+     * Cost tab counted both.
+     *
+     * No-op unless `chatConfig.costHistory.enabled` is `true`, when the live session has no
+     * usage yet, or when the session has no key to upsert against. Gating on the *live*
+     * figures (not the banked total) means a reload that restores nothing rewrites nothing.
      */
     finalizeCostSession(options?: {
         title?: string;
     }): void;
+    /**
+     * Spend for `projectKey` that predates the current transcript, resolved once per project
+     * and memoised (`_bankedFor`) so it cannot drift mid-session as the row it came from is
+     * rewritten by our own upserts.
+     *
+     * The two cases turn on whether the transcript is authoritative for this project:
+     *
+     * - **Transcript restored** (`persistenceActive`): it already accounts for everything after
+     *   the previous row's own banked figure, so carry that figure forward unchanged. Re-banking
+     *   `usage` here would add the restored history to itself on every reload.
+     * - **Transcript starts empty**: nothing on screen accounts for the previous total, so the
+     *   whole of it becomes banked. Without this the next turn would rewrite the row downwards
+     *   to just that turn, losing the project's earlier spend.
+     */
+    private bankedUsageFor;
+    /**
+     * Discard the banked figure — for when the spend it stands for has been deliberately
+     * thrown away (the user clearing history, or deleting this project's row).
+     *
+     * NOT for reloads. A reload re-reads rows that already include our own upserts, so
+     * re-deriving from them would fold the live session into its own baseline; only a genuine
+     * project change should re-derive, which `bankedUsageFor`'s per-project memo handles.
+     */
+    private resetBankedUsage;
     showConfirmationDialog(confirmationMessage: string, modalParent: HTMLElement, onConfirm: () => void, onCancel?: () => void): void;
     /** Remove one entry from persisted build history. */
     removeCostSessionFromHistory(id: string): void;
@@ -2167,6 +2274,22 @@ export declare class FoundationAiAssistant extends GenesisElement {
     clearCostSessionHistory(): void;
     private getCostHistoryScope;
     private reloadCostSessionHistory;
+    /**
+     * The persistence provider, but only when it implements BOTH cost-history methods.
+     *
+     * Both or neither: a provider that can save but not load would silently accumulate a
+     * ledger nobody ever reads back, so a partial implementation is treated as absent and
+     * falls back to `localStorage`.
+     */
+    private costHistoryProvider;
+    /**
+     * Adopt `records` as the live list and write them through to whichever backend owns
+     * cost history — the provider when the host implements it, else `localStorage`.
+     *
+     * Provider writes are fire-and-forget and best-effort: the ledger is accounting, not
+     * conversation content, so a failed write is logged and never surfaced into the chat.
+     */
+    private persistCostHistory;
     /** Finalize the previous session when the host-provided title changes. */
     private syncActiveCostSessionTitle;
     /** Active model id resolved from the AIProvider, if exposed. */
@@ -2222,8 +2345,15 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private unsubAppSettingsProvider?;
     /** Title tracked for the in-flight cost session (used when `header-title` changes). */
     private _activeCostSessionTitle;
-    /** Prevents double-finalize for the same session instance (pagehide + title change). */
-    private _costSessionFinalizedForInstance;
+    /** Memoised pre-transcript spend for `_bankedFor` — see `bankedUsageFor`. */
+    private _bankedUsage;
+    /** Project key `_bankedUsage` was resolved for; `undefined` means "not yet resolved". */
+    private _bankedFor;
+    /**
+     * Whether the row list reflects storage yet. Gates cost writes so a project's banked
+     * spend is never derived from a ledger that simply hasn't arrived.
+     */
+    private _costHistoryLoaded;
     private _handlePageHide;
     private haloStartPublished;
     /** Fingerprint of the agents array used to build the current driver. Used by agentsChanged to skip spurious rebuilds. */
@@ -2612,6 +2742,14 @@ export declare class FoundationAiAssistant extends GenesisElement {
     get settingsCostHistorySectionVisible(): boolean;
     /** Whether the built-in Cost tab summary block has anything to show. */
     get settingsCostSummaryVisible(): boolean;
+    /**
+     * Whether the lifetime-usage section has anything to say.
+     *
+     * Requires build history: with it off there are no rows, so `cumulativeUsage` falls back to
+     * the live session and the section would restate the block directly below it under a
+     * "lifetime" heading it hasn't earned.
+     */
+    get settingsCostLifetimeVisible(): boolean;
     /** Whether the Cost tab should appear in the settings modal. */
     get settingsCostTabVisible(): boolean;
     /** Whether session token usage should render on the Cost tab. */
@@ -3268,6 +3406,12 @@ declare interface ResolvedCostHistoryConfig {
     showTokens: boolean;
     /** Live-session badge label on the Cost tab summary. */
     badgeLabel: string;
+    /**
+     * Host-supplied disclosure line for the Cost tab. Stays optional — unlike
+     * `badgeLabel` there is no default, because only the host knows what its `scope`
+     * spans, and the library must not assert it.
+     */
+    summaryHint?: string;
 }
 
 /**
@@ -3385,6 +3529,28 @@ export declare interface SessionPersistenceProvider {
     loadPreferences?(sessionKey: string): Promise<SessionPreferences | undefined>;
     /** Persist the user's UI preferences for `sessionKey` (kept across `clear`). */
     savePreferences?(sessionKey: string, preferences: SessionPreferences): Promise<void>;
+    /**
+     * Scoped cost/build history — the per-project usage rows behind the Cost tab.
+     *
+     * ‼️ **Keyed by SCOPE, not `sessionKey`**, unlike every other method on this interface.
+     * A row holds one project's lifetime usage and the list spans projects, so keying it
+     * per session would defeat the model. The scope comes from
+     * `chatConfig.costHistory.scope`, falling back to the element `id`, then `'default'`.
+     *
+     * Optional: when a provider omits these, the assistant falls back to `localStorage`, so
+     * hosts that don't implement them are unaffected. Implementing them moves the ledger to
+     * the host's own backend, which is what stops it being stranded in one browser.
+     *
+     * Read/written **independently of the `enabled` toggle** (as with preferences and
+     * diagnostics): usage accounting is not conversation content, so a user turning off
+     * chat retention should not lose their cost ledger. Best-effort — a failed write must
+     * never affect the chat.
+     *
+     * `undefined` from `loadCostHistory` means "nothing stored", the same as `[]`.
+     */
+    loadCostHistory?(scope: string): Promise<CostSessionRecord[] | undefined>;
+    /** Replace the stored row list for `scope`. See {@link SessionPersistenceProvider.loadCostHistory}. */
+    saveCostHistory?(scope: string, records: CostSessionRecord[]): Promise<void>;
     /**
      * Server-saved diagnostics (GENC-1351 §5.8) — a **forward-only append** stream
      * that lets the downloadable debug log span the whole session lifetime, not just

package/dist/chat-driver.cjs

@@ -1565,6 +1565,8 @@ ${att.content}` });
     var _a, _b, _c, _d, _e, _f, _g, _h;
     let inputTokens;
     let outputTokens;
+    let cacheReadTokens;
+    let cacheWriteTokens;
     let cost;
     if (response.usage) {
       const uncachedInput = (_a = response.usage.input_tokens) !== null && _a !== void 0 ? _a : 0;
@@ -1574,6 +1576,8 @@ ${att.content}` });
       const cacheCreation = (_d = response.usage.cache_creation_input_tokens) !== null && _d !== void 0 ? _d : breakdown ? ((_e = breakdown.ephemeral_5m_input_tokens) !== null && _e !== void 0 ? _e : 0) + cacheCreation1h : 0;
       cost = this.logTokenUsage(uncachedInput, (_f = response.usage.output_tokens) !== null && _f !== void 0 ? _f : 0, cacheRead, cacheCreation, cacheCreation1h);
       inputTokens = uncachedInput + cacheRead + cacheCreation;
+      cacheReadTokens = cacheRead;
+      cacheWriteTokens = cacheCreation;
       if (response.usage.output_tokens != null) {
         outputTokens = response.usage.output_tokens;
       }
@@ -1604,6 +1608,10 @@ ${att.content}` });
       base.inputTokens = inputTokens;
     if (outputTokens != null)
       base.outputTokens = outputTokens;
+    if (cacheReadTokens != null)
+      base.cacheReadTokens = cacheReadTokens;
+    if (cacheWriteTokens != null)
+      base.cacheWriteTokens = cacheWriteTokens;
     if (cost != null)
       base.cost = cost;
     if (response.stop_reason === "max_tokens") {
@@ -2130,28 +2138,45 @@ ${att.content}`
     }
     return contents;
   }
+  /**
+   * Map Gemini's `usageMetadata` onto the provider-agnostic usage fields, pricing
+   * the call as a side effect (`logTokenUsage`). Returns an empty object when the
+   * response carries no usage — every field is optional, so an absent count stays
+   * `undefined` rather than being reported as a measured 0.
+   *
+   * Split out of `fromGeminiResponse` because it is self-contained bookkeeping
+   * that reads better alone — and because folding it inline pushed that method
+   * past the complexity ceiling.
+   */
+  usageFromGemini(usageMetadata) {
+    var _a, _b, _c, _d, _e, _f;
+    if (!usageMetadata)
+      return {};
+    const usage = usageMetadata;
+    const cost = this.logTokenUsage((_a = usage.promptTokenCount) !== null && _a !== void 0 ? _a : 0, (_b = usage.candidatesTokenCount) !== null && _b !== void 0 ? _b : 0, (_c = usage.thoughtsTokenCount) !== null && _c !== void 0 ? _c : 0, (_d = usage.cachedContentTokenCount) !== null && _d !== void 0 ? _d : 0);
+    return {
+      inputTokens: usage.promptTokenCount,
+      // Thinking tokens are generated output, billed at the candidate rate, but
+      // reported in a field disjoint from `candidatesTokenCount`. Fold them into the
+      // provider-agnostic `outputTokens` so it reflects the true generated total —
+      // matching Anthropic, whose `output_tokens` already includes them. Left
+      // `undefined` only when the provider reported neither count.
+      outputTokens: usage.candidatesTokenCount != null || usage.thoughtsTokenCount != null ? ((_e = usage.candidatesTokenCount) !== null && _e !== void 0 ? _e : 0) + ((_f = usage.thoughtsTokenCount) !== null && _f !== void 0 ? _f : 0) : void 0,
+      thoughtsTokens: usage.thoughtsTokenCount,
+      // Gemini reports cache HITS only — implicit caching bills no separate write, so
+      // `cacheWriteTokens` is left unset rather than 0 (there is no write bucket to
+      // measure, which is not the same as measuring 0). Already counted inside
+      // `promptTokenCount`, so this breaks that total down rather than adding to it.
+      cacheReadTokens: usage.cachedContentTokenCount,
+      cost
+    };
+  }
   fromGeminiResponse(response, offeredToolNames = /* @__PURE__ */ new Set()) {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
-    let inputTokens;
-    let outputTokens;
-    let thoughtsTokens;
-    let cost;
-    if (response.usageMetadata) {
-      const usage = response.usageMetadata;
-      cost = this.logTokenUsage((_a = usage.promptTokenCount) !== null && _a !== void 0 ? _a : 0, (_b = usage.candidatesTokenCount) !== null && _b !== void 0 ? _b : 0, (_c = usage.thoughtsTokenCount) !== null && _c !== void 0 ? _c : 0, (_d = usage.cachedContentTokenCount) !== null && _d !== void 0 ? _d : 0);
-      if (usage.promptTokenCount != null) {
-        inputTokens = usage.promptTokenCount;
-      }
-      if (usage.thoughtsTokenCount != null) {
-        thoughtsTokens = usage.thoughtsTokenCount;
-      }
-      if (usage.candidatesTokenCount != null || usage.thoughtsTokenCount != null) {
-        outputTokens = ((_e = usage.candidatesTokenCount) !== null && _e !== void 0 ? _e : 0) + ((_f = usage.thoughtsTokenCount) !== null && _f !== void 0 ? _f : 0);
-      }
-    }
+    var _a, _b, _c, _d;
+    const { inputTokens, outputTokens, thoughtsTokens, cacheReadTokens, cost } = this.usageFromGemini(response.usageMetadata);
     const candidates = response === null || response === void 0 ? void 0 : response.candidates;
     const firstCandidate = candidates === null || candidates === void 0 ? void 0 : candidates[0];
-    const parts = (_h = (_g = firstCandidate === null || firstCandidate === void 0 ? void 0 : firstCandidate.content) === null || _g === void 0 ? void 0 : _g.parts) !== null && _h !== void 0 ? _h : [];
+    const parts = (_b = (_a = firstCandidate === null || firstCandidate === void 0 ? void 0 : firstCandidate.content) === null || _a === void 0 ? void 0 : _a.parts) !== null && _b !== void 0 ? _b : [];
     const toolCalls = [];
     const thoughtParts = [];
     const textParts = [];
@@ -2164,7 +2189,7 @@ ${att.content}`
         toolCalls.push({
           id: crypto.randomUUID(),
           name: part.functionCall.name,
-          args: (_j = part.functionCall.args) !== null && _j !== void 0 ? _j : {},
+          args: (_c = part.functionCall.args) !== null && _c !== void 0 ? _c : {},
           providerMetadata: { [GEMINI_PROVIDER_KEY]: state }
         });
       } else if (part.thought && part.text) {
@@ -2198,9 +2223,11 @@ ${att.content}`
       base.inputTokens = inputTokens;
     if (outputTokens != null)
       base.outputTokens = outputTokens;
+    if (cacheReadTokens != null)
+      base.cacheReadTokens = cacheReadTokens;
     if (cost != null)
       base.cost = cost;
-    const blockReason = (_k = response.promptFeedback) === null || _k === void 0 ? void 0 : _k.blockReason;
+    const blockReason = (_d = response.promptFeedback) === null || _d === void 0 ? void 0 : _d.blockReason;
     if (finishReason != null || thoughtsTokens != null || blockReason != null) {
       base.responseMeta = {
         finishReason,
@@ -2997,6 +3024,46 @@ The above summarizes earlier parts of this conversation that were compacted. Con
   });
 }
 
+// src/utils/sum-usage.ts
+function emptyUsage() {
+  return {
+    costUsd: 0,
+    uncachedInputTokens: 0,
+    cacheReadTokens: 0,
+    cacheWriteTokens: 0,
+    outputTokens: 0
+  };
+}
+function sumUsage(messages) {
+  const total = emptyUsage();
+  accumulate(messages, total);
+  return total;
+}
+function addInto(into, from) {
+  into.costUsd += from.costUsd;
+  into.uncachedInputTokens += from.uncachedInputTokens;
+  into.cacheReadTokens += from.cacheReadTokens;
+  into.cacheWriteTokens += from.cacheWriteTokens;
+  into.outputTokens += from.outputTokens;
+}
+function accumulate(messages, into) {
+  for (const m of messages) {
+    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;
+    into.uncachedInputTokens += Math.max(0, (m.inputTokens ?? 0) - cacheRead - cacheWrite);
+    into.outputTokens += m.outputTokens ?? 0;
+    const rolled = m.compaction?.rolledUpUsage;
+    if (rolled) addInto(into, rolled);
+    for (const tc of m.toolCalls ?? []) {
+      if (tc.subAgentTrace) accumulate(tc.subAgentTrace, into);
+    }
+  }
+}
+
 // src/utils/tool-fold.ts
 var TOOL_FOLD_SYMBOL = Symbol("toolFold");
 
@@ -3744,7 +3811,12 @@ Output format (strict):
         coveredThroughTimestamp: toCompact[toCompact.length - 1]?.timestamp,
         tokensBefore,
         model: status?.model,
-        createdAt
+        createdAt,
+        // Bank what the replaced turns spent. `toCompact` is dropped from history
+        // below, taking its per-message cost/token fields with it — so a host total
+        // re-derived from the transcript would otherwise fall by exactly this much
+        // on every compaction. Summarising a turn does not refund what it cost.
+        rolledUpUsage: sumUsage(toCompact)
       }
     };
     this.loadHistory([summaryMessage, ...tail]);