@genesislcap/ai-assistant 15.4.1 → 15.5.0

package/src/main/main.ts

@@ -22,6 +22,7 @@
 // =============================================================================
 
 import type {
+  AggregateUsage,
   AIProviderRegistryStatusEntry,
   ChatAttachment,
   ChatConfig,
@@ -59,6 +60,7 @@ import { AiWavesIndicator } from '../components/waves-indicator';
 import type { AgentConfig } from '../config/config';
 import {
   AssistantAppSettingsProvider,
+  type AssistantAppSettingsHeading,
   type AssistantAppSettingsToggle,
 } from '../provider/assistant-app-settings';
 import {
@@ -113,10 +115,14 @@ import { AnimatedPanelToggle } from '../utils/animated-panel-toggle';
 import { resolveExclusiveLoadingStyle } from '../utils/animation-exclusivity';
 import { collectSessionModels } from '../utils/collect-session-models';
 import {
-  appendCostSessionRecord,
   clearCostSessionHistory,
+  isCostSessionRecord,
   loadCostSessionHistory,
-  removeCostSessionRecord,
+  resolveBankedUsage,
+  saveCostSessionHistory,
+  sortRecordsByRecency,
+  upsertRecord,
+  type CostSessionModelEntry,
   type CostSessionRecord,
 } from '../utils/cost-session-history';
 import {
@@ -131,8 +137,7 @@ import {
 } from '../utils/resolve-cost-history-config';
 import { resolvePreferenceBaseline } from '../utils/resolve-preference-baseline';
 import { stripAgentHandlers } from '../utils/strip-agent-handlers';
-import { sumCosts } from '../utils/sum-costs';
-import { sumTokens } from '../utils/sum-tokens';
+import { addUsage, emptyUsage, sumUsage, totalTokens } from '../utils/sum-usage';
 import { expandToolTree } from '../utils/tool-fold';
 import { styles } from './main.styles';
 import { FoundationAiAssistantTemplate } from './main.template';
@@ -189,6 +194,13 @@ function sanitizeIconMarkup(markup: string): string {
  */
 const AGENT_PICKER_CLOSE_MS = 200;
 const SESSION_MENU_CLOSE_MS = 200;
+/**
+ * How long cost-ledger writes coalesce. Comfortably longer than the gap between the turns of a
+ * tool loop, so a multi-step run writes once rather than per turn, and short enough that a flush
+ * has landed well before a user could close the tab. Nothing reads the stored ledger while the
+ * assistant is running — the Usage tab renders the in-memory list — so the delay is invisible.
+ */
+const LEDGER_FLUSH_DEBOUNCE_MS = 2000;
 
 /** Drag-to-resize bounds for the chat input (composer), in px. */
 const COMPOSER_MIN_HEIGHT_PX = 48;
@@ -223,10 +235,13 @@ avoidTreeShaking(
  *
  * 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 Usage 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`
@@ -688,24 +703,109 @@ export class FoundationAiAssistant extends GenesisElement {
     this._sessionRef?.actions.aiAssistant.setContextLimit(value);
   }
 
-  /** 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 {
+    return this._sessionRef?.store.aiAssistant.sessionUsage ?? emptyUsage();
+  }
+  set sessionUsage(value: AggregateUsage) {
+    this._sessionRef?.actions.aiAssistant.setSessionUsage(value);
+  }
+
+  /**
+   * 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 {
-    return this._sessionRef?.store.aiAssistant.sessionCostUsd ?? 0;
+    return this.sessionUsage.costUsd;
   }
-  set sessionCostUsd(value: number) {
-    this._sessionRef?.actions.aiAssistant.setSessionCostUsd(value);
+
+  /**
+   * Distinct models the registry currently resolves to — the live session's model chips.
+   *
+   * `providerStatuses` carries one entry per registry SLOT, so a vendor configured across several
+   * tiers that happen to resolve to the same model reports it once per tier, and the chips
+   * rendered it once per tier too. Which tier a model came from is not what these chips are for.
+   *
+   * Deduped on the label actually displayed, not on `status.model`: a slot whose provider reports
+   * no model falls back to the slot's own name, and those are distinct per slot, so keying on the
+   * label keeps them from collapsing into one another.
+   */
+  @volatile
+  get uniqueProviderModels(): CostSessionModelEntry[] {
+    const seen = new Map<string, CostSessionModelEntry>();
+    for (const entry of this.providerStatuses) {
+      const model = entry.status?.model ?? entry.name;
+      if (!model) continue;
+      const existing = seen.get(model);
+      if (!existing) {
+        seen.set(model, { model, provider: entry.status?.provider });
+        continue;
+      }
+      // Keep whichever tier knew the vendor, so the chip still gets its colour when one slot
+      // reports a provider and another does not.
+      if (existing.provider === undefined && entry.status?.provider !== undefined) {
+        existing.provider = entry.status.provider;
+      }
+    }
+    return [...seen.values()];
   }
 
-  /** Saved build history plus the in-flight session — shown on the Cost tab summary. */
+  /**
+   * Build history for display: most recently worked on first.
+   *
+   * The stored order is insertion order (see `upsertRecord`), which leaves a project returned to
+   * sitting wherever it was first seen — so ordering is applied here, on read, where it also
+   * covers rows a host provider supplied.
+   */
   @volatile
-  get cumulativeCostUsd(): number {
-    // TODO: Handle project switching/loading so this reflects the active project's total cost.
+  get sortedCostSessionHistory(): CostSessionRecord[] {
+    return sortRecordsByRecency(this.costSessionHistory);
+  }
+
+  /**
+   * Lifetime usage across every project in the history scope — cost and all four token
+   * buckets. What the Usage 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.
+   */
+  @volatile
+  get cumulativeUsage(): AggregateUsage {
     void this.costSessionHistory;
     void this.chatConfig;
-    const historyTotal = this.resolvedCostHistory.enabled
-      ? this.costSessionHistory.reduce((sum, record) => sum + record.costUsd, 0)
-      : 0;
-    return historyTotal + this.sessionCostUsd;
+    // With history off there are no rows to sum, so the live session IS all we know.
+    if (!this.resolvedCostHistory.enabled) return this.sessionUsage;
+    return this.costSessionHistory.reduce(
+      (total, record) => addUsage(total, record.usage),
+      emptyUsage(),
+    );
+  }
+
+  /** Lifetime USD across every project in the history scope. */
+  @volatile
+  get cumulativeCostUsd(): number {
+    return this.cumulativeUsage.costUsd;
+  }
+
+  /**
+   * 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 Usage 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.
+   */
+  @volatile
+  get liveUsageIsProjectLifetime(): boolean {
+    return this.persistenceActive;
   }
 
   /** Resolved cost tab and build-history settings from `chatConfig.costHistory`. */
@@ -715,15 +815,15 @@ export class FoundationAiAssistant extends GenesisElement {
     return resolveCostHistoryConfig(this.chatConfig);
   }
 
-  /** 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 {
-    return this._sessionRef?.store.aiAssistant.sessionTokensConsumed ?? 0;
-  }
-  set sessionTokensConsumed(value: number) {
-    this._sessionRef?.actions.aiAssistant.setSessionTokensConsumed(value);
+    return totalTokens(this.sessionUsage);
   }
 
-  /** Label shown on the Cost tab for the in-flight session (app title or first user phrase). */
+  /** Label shown on the Usage tab for the in-flight session (app title or first user phrase). */
   @volatile
   get liveCostSessionTitle(): string | undefined {
     void this.messages;
@@ -734,15 +834,34 @@ export class FoundationAiAssistant extends GenesisElement {
   }
 
   /**
-   * 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
+   * Usage 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 {
     if (!this.resolvedCostHistory.enabled) return;
-    if (this._costSessionFinalizedForInstance) return;
-    const costUsd = this.sessionCostUsd;
-    const tokensConsumed = this.sessionTokensConsumed;
-    if (costUsd <= 0 && tokensConsumed <= 0) return;
+    // Wait for the rows before writing: a provider read is async, and banking from a
+    // not-yet-loaded ledger would read as "nothing came before" and rewrite this project's
+    // row down to the current transcript. Skipping is free — this is called on every
+    // transcript change, so the next one writes.
+    if (!this._costHistoryLoaded) return;
+    const live = this.sessionUsage;
+    const tokensConsumed = totalTokens(live);
+    if (live.costUsd <= 0 && tokensConsumed <= 0) return;
+    // The session key identifies the work — a project id, for hosts that key sessions
+    // per project. Without one there is nothing stable to upsert against, so skip
+    // rather than write a row that can never be matched again.
+    const projectKey = this.getStateKey();
+    if (!projectKey) return;
 
     const title = resolveCostSessionTitle({
       explicit: options?.title,
@@ -750,18 +869,63 @@ export class FoundationAiAssistant extends GenesisElement {
       messages: this.messages,
       headerTitle: this.headerTitle,
     });
+    // Lifetime = what came before this transcript + what this transcript proves. Both
+    // terms are derived from state, never incremented, so the two element instances that
+    // share a session write the same row rather than each adding their own contribution.
+    const banked = this.bankedUsageFor(projectKey);
     const record: CostSessionRecord = {
-      id: crypto.randomUUID(),
+      // Stable per project so repeat upserts replace the row instead of stacking, and
+      // so the delete action keeps targeting the same row across reloads.
+      id: projectKey,
+      projectKey,
       title,
-      endedAt: new Date().toISOString(),
-      costUsd,
-      tokensConsumed,
+      updatedAt: new Date().toISOString(),
+      usage: addUsage(banked, live),
+      banked,
       models: collectSessionModels(this.messages, this.providerStatuses),
     };
-    this.costSessionHistory = appendCostSessionRecord(this.getCostHistoryScope(), record);
-    this._costSessionFinalizedForInstance = true;
-    this.sessionCostUsd = 0;
-    this.sessionTokensConsumed = 0;
+    this.persistCostHistory(upsertRecord(this.costSessionHistory, record));
+    // NOTE: the live counters are deliberately NOT reset here. Resetting was what
+    // double-counted spend — the row was banked while the persisted transcript still
+    // carried the same usage, so a reload restored it and the Usage tab added both.
+    // The row is a projection of the session totals, not a transfer out of them.
+  }
+
+  /**
+   * 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(projectKey: string): AggregateUsage {
+    if (this._bankedFor === projectKey) return this._bankedUsage;
+    const existing = this.costSessionHistory.find((r) => r.projectKey === projectKey);
+    // `persistenceActive` is what decides whether the transcript speaks for the project's
+    // history: it is on only when a provider is wired AND the user is remembering the chat.
+    this._bankedUsage = resolveBankedUsage(existing, this.persistenceActive);
+    this._bankedFor = projectKey;
+    return this._bankedUsage;
+  }
+
+  /**
+   * 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(): void {
+    this._bankedFor = undefined;
+    this._bankedUsage = emptyUsage();
   }
 
   showConfirmationDialog(
@@ -786,11 +950,30 @@ export class FoundationAiAssistant extends GenesisElement {
 
   /** Remove one entry from persisted build history. */
   removeCostSessionFromHistory(id: string): void {
-    this.costSessionHistory = removeCostSessionRecord(this.getCostHistoryScope(), id);
+    // Deleting the active project's row discards its banked spend by intent, so drop the
+    // memo too — otherwise the next turn would rewrite the row we just removed, restoring
+    // the total the user asked to be rid of.
+    //
+    // Resolve the row first: `id` is a row id while `_bankedFor` is a projectKey. They match
+    // only for rows this element wrote (`finalizeCostSession` sets `id: projectKey`); a row from
+    // a host provider can carry any id, and comparing across the two namespaces would silently
+    // skip the reset.
+    const removed = this.costSessionHistory.find((record) => record.id === id);
+    if (removed && this._bankedFor === removed.projectKey) this.resetBankedUsage();
+    this.persistCostHistory(this.costSessionHistory.filter((record) => record.id !== id));
   }
 
   /** Clear all persisted build history for this assistant scope. */
   clearCostSessionHistory(): void {
+    // Every row is gone, so nothing is banked any more — without this the active project's
+    // next turn would resurrect its pre-clear total.
+    this.resetBankedUsage();
+    // Provider-backed: write an empty ledger through. The `localStorage` path instead
+    // removes its key outright rather than leaving an empty array behind.
+    if (this.costHistoryProvider()) {
+      this.persistCostHistory([]);
+      return;
+    }
     clearCostSessionHistory(this.getCostHistoryScope());
     this.costSessionHistory = [];
   }
@@ -803,23 +986,134 @@ export class FoundationAiAssistant extends GenesisElement {
   }
 
   private reloadCostSessionHistory(): void {
+    // NOTE: deliberately does NOT invalidate the banked figure. This runs again whenever
+    // `chatConfig` rebinds — hosts commonly build it in a template expression, so a new
+    // object arrives mid-session — and by then the rows include our own upserts, whose
+    // `usage` already contains the live transcript. Re-deriving from those would add the
+    // current session to itself. `bankedUsageFor` keys its memo on the project instead,
+    // which handles a genuine session switch without trusting reload timing.
+    this._costHistoryLoaded = false;
+    this._ledgerUnreadable = false;
     if (!this.resolvedCostHistory.enabled) {
       this.costSessionHistory = [];
+      this._costHistoryLoaded = true;
+      return;
+    }
+    const scope = this.getCostHistoryScope();
+    const provider = this.costHistoryProvider();
+    if (!provider) {
+      this.costSessionHistory = loadCostSessionHistory(scope);
+      this._costHistoryLoaded = true;
       return;
     }
-    this.costSessionHistory = loadCostSessionHistory(this.getCostHistoryScope());
+    // Provider reads are async, so the Usage tab renders an empty list for a tick before
+    // this lands. Seeded empty rather than left stale so a scope change can't briefly show
+    // the previous scope's rows.
+    this.costSessionHistory = [];
+    void provider.loadCostHistory!(scope)
+      .then((records) => {
+        // Guard against a scope change while the load was in flight — a late result must
+        // not overwrite the rows of whatever scope is current now.
+        if (this.getCostHistoryScope() === scope) {
+          // Filtered exactly as the localStorage path is. A host's rows are as capable of
+          // being malformed as a hand-edited storage entry, and an unchecked one poisons
+          // every total with NaN or throws in the sort during render.
+          this.costSessionHistory = (records ?? []).filter(isCostSessionRecord);
+          this._costHistoryLoaded = true;
+        }
+      })
+      .catch((e) => {
+        logger.warn('Cost history unreadable — recording locally only this page-load', e);
+        // Writes stay blocked, and `persistCostHistory` will not save even if something else
+        // calls it. `saveCostHistory` REPLACES the stored list, so writing an upsert against
+        // the empty list we fell back to would delete every other project's row and reset
+        // this project's banked total — destroying data we simply failed to read. The row
+        // rebuilds from the transcript on the next successful load.
+        this._ledgerUnreadable = true;
+      });
+  }
+
+  /**
+   * 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() {
+    const provider = this.persistence.provider;
+    return provider?.loadCostHistory && provider.saveCostHistory ? provider : undefined;
   }
 
-  /** Finalize the previous session when the host-provided title changes. */
+  /**
+   * Adopt `records` as the live list, and schedule a write to whichever backend owns cost
+   * history — the provider when the host implements it, else `localStorage`.
+   *
+   * The list is adopted synchronously because that is what the Usage tab renders; only the
+   * *write* is deferred. This runs on every usage change (about once per LLM call, plus once
+   * per sub-agent turn) and each write serialises the whole ledger, so coalescing cuts a
+   * per-turn `localStorage.setItem` or network round-trip down to one per quiet period. Safe
+   * because the write is a full replace of idempotent state: the newest call wins and no
+   * intermediate state is meaningful. Flushed on `pagehide` and disconnect so nothing is lost.
+   */
+  private persistCostHistory(records: CostSessionRecord[]): void {
+    this.costSessionHistory = records;
+    // A ledger we could not read must never be written back — see reloadCostSessionHistory.
+    // Guarded here rather than only at the finalize gate so it also covers the row-removal and
+    // clear paths, which write directly.
+    if (this._ledgerUnreadable) return;
+    this._ledgerDirty = true;
+    if (this._ledgerFlushTimer !== undefined) clearTimeout(this._ledgerFlushTimer);
+    this._ledgerFlushTimer = setTimeout(() => this.flushCostHistory(), LEDGER_FLUSH_DEBOUNCE_MS);
+  }
+
+  /**
+   * Write the pending ledger now. Safe to call when nothing is pending.
+   *
+   * 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. On
+   * `pagehide` the `localStorage` path completes synchronously; a provider write is subject to
+   * the same unload race as every other network save the assistant makes.
+   */
+  private flushCostHistory(): void {
+    if (this._ledgerFlushTimer !== undefined) {
+      clearTimeout(this._ledgerFlushTimer);
+      this._ledgerFlushTimer = undefined;
+    }
+    if (!this._ledgerDirty || this._ledgerUnreadable) return;
+    this._ledgerDirty = false;
+    const records = this.costSessionHistory;
+    const scope = this.getCostHistoryScope();
+    const provider = this.costHistoryProvider();
+    if (!provider) {
+      saveCostSessionHistory(scope, records);
+      return;
+    }
+    void provider.saveCostHistory!(scope, records).catch((e) => {
+      logger.warn('Cost history save failed', e);
+    });
+  }
+
+  /**
+   * Finalize the previous session when the host-provided title changes — a rename should land on
+   * the row under its old name rather than silently relabelling accrued spend.
+   *
+   * Only when the session key still matches the one that title accrued under. Hosts change
+   * `costHistory.title` on project SWITCH too, and if the key has already flipped, this would
+   * upsert the outgoing project's live usage onto the incoming project's row as
+   * `banked + old live`, inflating it. Under the old append model a mis-keyed write left a stray
+   * row; with the upsert it overwrites a real one.
+   */
   private syncActiveCostSessionTitle(): void {
     const previous = this._activeCostSessionTitle;
     const next = this.resolvedCostHistory.title?.trim() ?? '';
-    if (previous && previous !== next) {
+    const key = this.getStateKey();
+    if (previous && previous !== next && this._activeCostSessionKey === key) {
       this.finalizeCostSession({ title: previous });
     }
     if (previous !== next) {
       this._activeCostSessionTitle = next;
-      this._costSessionFinalizedForInstance = false;
+      this._activeCostSessionKey = key;
     }
   }
 
@@ -884,7 +1178,7 @@ export class FoundationAiAssistant extends GenesisElement {
   @observable settingsAppSlotted: HTMLElement[] = [];
   @observable settingsCostCurrentSlotted: HTMLElement[] = [];
   @observable settingsCostHistorySlotted: HTMLElement[] = [];
-  /** Persisted finalized cost sessions shown on the Cost tab build history list. */
+  /** Persisted finalized cost sessions shown on the Usage tab build history list. */
   @observable costSessionHistory: CostSessionRecord[] = [];
   /** Whether the splash overlay is currently showing (no messages and showSplash is enabled). Reflected as a boolean attribute on the host. */
   @observable showingSplash = false;
@@ -899,13 +1193,39 @@ export class FoundationAiAssistant extends GenesisElement {
   private unsubAppSettingsProvider?: () => void;
   /** 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 = false;
+  /**
+   * Session key `_activeCostSessionTitle` was captured under, so a title change can tell a rename
+   * (same key) from a project switch (key already flipped) — see `syncActiveCostSessionTitle`.
+   */
+  private _activeCostSessionKey?: string;
+  /** Memoised pre-transcript spend for `_bankedFor` — see `bankedUsageFor`. */
+  private _bankedUsage: AggregateUsage = emptyUsage();
+  /** Project key `_bankedUsage` was resolved for; `undefined` means "not yet resolved". */
+  private _bankedFor: string | undefined;
+  /**
+   * 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 = false;
+  /**
+   * Set when a provider read failed. Latches writes off for this page-load: `saveCostHistory`
+   * replaces the whole stored list, so writing anything derived from the empty list we fell back
+   * to would destroy rows we never managed to read.
+   */
+  private _ledgerUnreadable = false;
+  /** Pending (adopted but unwritten) ledger changes — see `persistCostHistory`. */
+  private _ledgerDirty = false;
+  private _ledgerFlushTimer?: ReturnType<typeof setTimeout>;
+  // No once-guard for cost-session writes: the write is an upsert keyed by the session
+  // key, so repeat calls (pagehide, title change, per-turn) replace the same row and are
+  // idempotent. The old flag existed only because the write appended and reset.
   // Single-view model (GENC-1351 Option A): the one assistant element always finalizes
   // the cost session on tab close — there is no hidden twin to defer to, so this fires
   // unconditionally (the old bubble-vs-docked gating flag is gone with the two-view model).
   private _handlePageHide = (): void => {
     this.finalizeCostSession();
+    // Straight to storage: the debounce timer will never fire once the page is going away.
+    this.flushCostHistory();
   };
   private haloStartPublished = false;
   /** Fingerprint of the agents array used to build the current driver. Used by agentsChanged to skip spurious rebuilds. */
@@ -1712,6 +2032,9 @@ export class FoundationAiAssistant extends GenesisElement {
 
   disconnectedCallback() {
     window.removeEventListener('pagehide', this._handlePageHide);
+    // Write out anything the debounce is still holding — the timer would otherwise fire against
+    // a torn-down element, or not at all.
+    this.flushCostHistory();
     super.disconnectedCallback();
     this._sessionActive = false;
     this.stopLoadingTimer();
@@ -1867,18 +2190,26 @@ export class FoundationAiAssistant extends GenesisElement {
         break;
       }
     }
-    // Recompute aggregated session cost from per-message `cost` fields. Recomputing
-    // (rather than incrementing on append) keeps the total correct under any
-    // mutation of the message list — including future clear-chat / re-render flows.
-    // `sumCosts` recurses into `toolCall.subAgentTrace` so cost incurred by
-    // sub-agents (potentially on different providers) is included.
-    const runningCost = sumCosts(this.messages);
-    if (runningCost !== this.sessionCostUsd) {
-      this.sessionCostUsd = runningCost;
-    }
-    const runningTokens = sumTokens(this.messages);
-    if (runningTokens !== this.sessionTokensConsumed) {
-      this.sessionTokensConsumed = runningTokens;
+    // Recompute cost and all four token buckets from the transcript in one walk.
+    // Recomputing (rather than incrementing on append) keeps the totals correct under
+    // any mutation of the message list — clear-chat, re-render, restore. `sumUsage`
+    // recurses into `toolCall.subAgentTrace`, so work a sub-agent did (possibly on
+    // another provider at other rates) counts, and it reads the usage a compaction
+    // banked onto its summary, so shrinking history no longer shrinks the totals.
+    const running = sumUsage(this.messages);
+    const current = this.sessionUsage;
+    if (
+      running.costUsd !== current.costUsd ||
+      running.uncachedInputTokens !== current.uncachedInputTokens ||
+      running.cacheReadTokens !== current.cacheReadTokens ||
+      running.cacheWriteTokens !== current.cacheWriteTokens ||
+      running.outputTokens !== current.outputTokens
+    ) {
+      this.sessionUsage = running;
+      // Keep this project's history row current as spend accrues, which is what lets
+      // the Usage tab total be the sum of the rows alone. Idempotent (an upsert keyed
+      // by the session key), so calling it per change is safe.
+      this.finalizeCostSession();
     }
     // Record a context.updated meta event when the token count changes (≈once
     // per LLM call, as a new usage-bearing message arrives), plus a one-shot
@@ -2357,12 +2688,6 @@ export class FoundationAiAssistant extends GenesisElement {
     return this.settingsAppSlotted.length > 0 || this.visibleAppSettingsToggles.length > 0;
   }
 
-  /** Section title for the app settings block. */
-  @volatile
-  get appSettingsSectionTitle(): string {
-    return this.appSettingsProvider.sectionTitle ?? 'UI Builder Settings';
-  }
-
   /** App toggles currently visible per each entry's `visible()` predicate. */
   @volatile
   get visibleAppSettingsToggles(): AssistantAppSettingsToggle[] {
@@ -2370,6 +2695,18 @@ export class FoundationAiAssistant extends GenesisElement {
     return this.appSettingsProvider.toggles.filter((toggle) => toggle.visible?.() !== false);
   }
 
+  /**
+   * Host-supplied heading for the toggle group, or `undefined` for none — the assistant has no
+   * default. Suppressed when no toggle is currently visible, so a `visible()` predicate hiding
+   * the last one takes its heading with it rather than leaving a label over nothing.
+   */
+  @volatile
+  get appSettingsTogglesHeading(): AssistantAppSettingsHeading | undefined {
+    void this.appSettingsRevision;
+    if (this.visibleAppSettingsToggles.length === 0) return undefined;
+    return this.appSettingsProvider.togglesHeading;
+  }
+
   getAppSettingValue(id: string): boolean {
     void this.appSettingsRevision;
     return this.appSettingsProvider.getValue(id);
@@ -2403,7 +2740,7 @@ export class FoundationAiAssistant extends GenesisElement {
     return this.costSessionHistory.length > 0 || this.settingsCostHistorySlotted.length > 0;
   }
 
-  /** Whether the built-in Cost tab summary block has anything to show. */
+  /** Whether the built-in Usage tab summary block has anything to show. */
   @volatile
   get settingsCostSummaryVisible(): boolean {
     void this.chatConfig;
@@ -2416,7 +2753,31 @@ export class FoundationAiAssistant extends GenesisElement {
     return !!this.liveCostSessionTitle;
   }
 
-  /** Whether the Cost tab should appear in the settings modal. */
+  /**
+   * 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.
+   */
+  @volatile
+  get settingsCostLifetimeVisible(): boolean {
+    void this.chatConfig;
+    void this._sessionRef;
+    const cost = this.resolvedCostHistory;
+    if (!cost.enabled || !(cost.showCost || cost.showTokens)) return false;
+    // Also requires a state key, because `finalizeCostSession` skips the write without one and the
+    // lifetime figures sum rows only — so the section would show a permanent $0.00 directly above
+    // a live block reporting real spend.
+    //
+    // Narrow in practice: `getStateKey` falls back to `id::headerTitle`, and `headerTitle` has a
+    // non-empty default, so a key is almost always derivable even with no `session-key`. This
+    // catches the remaining case — a host that supplies no session key, no element id, AND blanks
+    // the header title. Cheap, and the alternative is a figure that is simply wrong.
+    return !!this.getStateKey();
+  }
+
+  /** Whether the Usage tab should appear in the settings modal. */
   @volatile
   get settingsCostTabVisible(): boolean {
     void this.chatConfig;
@@ -2429,7 +2790,7 @@ export class FoundationAiAssistant extends GenesisElement {
     );
   }
 
-  /** Whether session token usage should render on the Cost tab. */
+  /** Whether session token usage should render on the Usage tab. */
   @volatile
   get settingsSessionTokensVisible(): boolean {
     void this.chatConfig;
@@ -2752,6 +3113,10 @@ export class FoundationAiAssistant extends GenesisElement {
           contextUsagePercent,
           sessionCostUsd: this.sessionCostUsd,
           sessionTokensConsumed: this.sessionTokensConsumed,
+          // The per-bucket split alongside the total. Without it a log shows a large
+          // token count next to a small cost with no way to tell why — the answer is
+          // almost always that most of the prompt was a cache hit.
+          sessionUsage: this.sessionUsage,
         },
         // Snapshot captured fresh at log-export time — reflects state NOW, which
         // may have transitioned since the last LLM call.