@genesislcap/ai-assistant 15.4.1 → 15.6.0

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';
@@ -12,6 +13,7 @@ import type { ChatMessage } from '@genesislcap/foundation-ai';
 import type { ChatToolChoice } from '@genesislcap/foundation-ai';
 import type { ChatToolDefinition } from '@genesislcap/foundation-ai';
 import type { ChatToolHandlers } from '@genesislcap/foundation-ai';
+import { ElementStyles } from '@genesislcap/web-core';
 import { GenesisElement } from '@genesislcap/web-core';
 import type { InteractionRequestOptions } from '@genesislcap/foundation-ai';
 import type { InteractionResult } from '@genesislcap/foundation-ai';
@@ -726,16 +728,42 @@ export declare const ANIMATION_DEFS: {
 export declare function assembleDebugLog(entries: DiagnosticEntry[], readme: readonly string[]): DebugLog;
 
 /**
- * App-supplied settings for the platform settings modal UI Builder section.
- * Register a concrete implementation on the DI token at app bootstrap; the
- * assistant renders toggles with the same row layout as AI Chat Bot settings.
+ * Optional heading above a provider's toggle group.
+ *
+ * Entirely host-supplied — the assistant has no default title and no default icon, because the
+ * section belongs to the host. Omit it and the toggles render bare, which is right when the
+ * host's slotted content already titles them.
+ *
+ * @beta
+ */
+export declare interface AssistantAppSettingsHeading {
+    readonly title: string;
+    /**
+     * Icon name for the design system's icon element (a Font Awesome free name, e.g.
+     * `'object-group'`). Omitted renders text only; an unknown name renders nothing at all, so
+     * check it against the installed Font Awesome set.
+     */
+    readonly icon?: string;
+}
+
+/**
+ * App-supplied settings for the host's own section of the settings modal. Register a concrete
+ * implementation on the DI token at app bootstrap; the assistant renders the toggles with the
+ * same row layout as AI Chat Bot settings.
+ *
+ * The section itself is untitled by the assistant — no heading text and no icon — because only
+ * the host knows what it is. Title it from the `settings-app` slot, which renders above these
+ * toggles, and apply `assistantSettingsSectionTitleStyles` to match the built-in headings.
  *
  * @beta
  */
 export declare interface AssistantAppSettingsProvider {
-    /** Section heading. Default: `"UI Builder Settings"`. */
-    readonly sectionTitle?: string;
     readonly toggles: readonly AssistantAppSettingsToggle[];
+    /**
+     * Heading for the toggle group, for hosts that put other controls in the `settings-app` slot
+     * and need these distinguished from them. No default: absent means no heading.
+     */
+    readonly togglesHeading?: AssistantAppSettingsHeading;
     getValue(id: string): boolean;
     setValue(id: string, value: boolean): void;
     /** Notify the assistant to re-read toggle values / visibility. */
@@ -770,6 +798,34 @@ export declare interface AssistantAppSettingsToggle {
     hint?: () => string | undefined;
 }
 
+/**
+ * Heading style for a settings-modal section, published so a host can title its own section.
+ *
+ * The assistant renders no heading for the `settings-app` slot — no text and no icon — because
+ * only the host knows what that section is. The consequence is that a host supplying one has to
+ * reproduce the styling of the built-in headings beside it, and a copied rule drifts the moment
+ * either side changes. So the declarations live here, are applied by the assistant's own
+ * headings, and are exported for the host to apply to its.
+ *
+ * Compose it into a component's styles and put `ai-settings-section-title` on the heading:
+ *
+ * ```ts
+ * import { assistantSettingsSectionTitleStyles } from '@genesislcap/ai-assistant';
+ *
+ * const styles = css`
+ *   ${assistantSettingsSectionTitleStyles}
+ *   :host { display: block; }
+ * `;
+ * ```
+ *
+ * Carries no margin on purpose: spacing belongs to the surrounding layout, which differs
+ * between the assistant's own sections and a slotted one, and is the single declaration hosts
+ * had to diverge on when they copied this rule.
+ *
+ * @beta
+ */
+export declare const assistantSettingsSectionTitleStyles: ElementStyles;
+
 declare interface BaseAgentConfig {
     /**
      * Stable identity for this agent. Used for classifier routing, manual
@@ -1321,6 +1377,8 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private unsubscribeRegistry?;
     /** Hard cap on tool-loop iterations. */
     private readonly maxToolIterations;
+    /** Model-calls per condensation batch; `1` collapses as soon as a trigger fires. */
+    private readonly condenseBatchCalls;
     /** Session identity used to file meta events onto the shared debug-log timeline. */
     private readonly sessionKey;
     /** Injected activity bus; defaults to a no-op off-browser (Node/tests/headless). */
@@ -1657,6 +1715,16 @@ export declare interface ChatDriverConfig {
     maxToolIterations?: number;
     /** Hard cap on fold operations. Default `5`. */
     maxFoldOperations?: number;
+    /**
+     * Collapse `condenseWhen` payloads in batches of this many model-calls rather than as
+     * soon as each trigger fires. A positive integer; decimals are floored and anything
+     * below `1` becomes `1`. Default `1` — collapse immediately, the historical behaviour.
+     *
+     * Condensation rewrites history in place, so collapsing continuously breaks the
+     * provider's prompt cache on nearly every call of a re-read loop. Raising this trades
+     * up to that many calls' worth of extra context for one cache break per batch.
+     */
+    condenseBatchCalls?: number;
     /** Ring-buffer size for per-turn snapshots. Default `400`. */
     maxTurnSnapshots?: number;
     /** Session identity used to file meta events onto the shared debug-log timeline. */
@@ -1698,21 +1766,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 +2010,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 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`
@@ -2141,25 +2249,111 @@ 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. */
+    /**
+     * 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.
+     */
+    get uniqueProviderModels(): CostSessionModelEntry[];
+    /**
+     * 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.
+     */
+    get sortedCostSessionHistory(): CostSessionRecord[];
+    /**
+     * 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.
+     */
+    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 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.
+     */
+    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). */
+    /** Label shown on the Usage 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
+     * 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;
+    /**
+     * 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,7 +2361,45 @@ export declare class FoundationAiAssistant extends GenesisElement {
     clearCostSessionHistory(): void;
     private getCostHistoryScope;
     private reloadCostSessionHistory;
-    /** Finalize the previous session when the host-provided title changes. */
+    /**
+     * 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 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;
+    /**
+     * 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;
+    /**
+     * 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;
     /** Active model id resolved from the AIProvider, if exposed. */
     get activeModel(): string | undefined;
@@ -2208,7 +2440,7 @@ export declare class FoundationAiAssistant extends GenesisElement {
     settingsAppSlotted: HTMLElement[];
     settingsCostCurrentSlotted: HTMLElement[];
     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. */
     costSessionHistory: CostSessionRecord[];
     /** Whether the splash overlay is currently showing (no messages and showSplash is enabled). Reflected as a boolean attribute on the host. */
     showingSplash: boolean;
@@ -2222,8 +2454,29 @@ 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;
+    /**
+     * 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?;
+    /** 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;
+    /**
+     * 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;
+    /** Pending (adopted but unwritten) ledger changes — see `persistCostHistory`. */
+    private _ledgerDirty;
+    private _ledgerFlushTimer?;
     private _handlePageHide;
     private haloStartPublished;
     /** Fingerprint of the agents array used to build the current driver. Used by agentsChanged to skip spurious rebuilds. */
@@ -2600,21 +2853,33 @@ export declare class FoundationAiAssistant extends GenesisElement {
     get settingsContextUsageVisible(): boolean;
     /** Whether the settings modal UI Builder section should render. */
     get settingsAppSectionVisible(): boolean;
-    /** Section title for the app settings block. */
-    get appSettingsSectionTitle(): string;
     /** App toggles currently visible per each entry's `visible()` predicate. */
     get visibleAppSettingsToggles(): AssistantAppSettingsToggle[];
+    /**
+     * 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.
+     */
+    get appSettingsTogglesHeading(): AssistantAppSettingsHeading | undefined;
     getAppSettingValue(id: string): boolean;
     setAppSettingValue(id: string, value: boolean): void;
     private wireAppSettingsProvider;
     private unwireAppSettingsProvider;
     get settingsCostCurrentSectionVisible(): boolean;
     get settingsCostHistorySectionVisible(): boolean;
-    /** Whether the built-in Cost tab summary block has anything to show. */
+    /** Whether the built-in Usage tab summary block has anything to show. */
     get settingsCostSummaryVisible(): boolean;
-    /** 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.
+     */
+    get settingsCostLifetimeVisible(): boolean;
+    /** Whether the Usage tab should appear in the settings modal. */
     get settingsCostTabVisible(): boolean;
-    /** Whether session token usage should render on the Cost tab. */
+    /** Whether session token usage should render on the Usage tab. */
     get settingsSessionTokensVisible(): boolean;
     /** Whether the chat header (and settings cog) should render. */
     get settingsCogVisible(): boolean;
@@ -3262,12 +3527,18 @@ declare interface ResolvedCostHistoryConfig {
     title?: string;
     /** `localStorage` scope key; falls back to element `id` then `'default'`. */
     scope?: string;
-    /** Show running session USD on the Cost tab. Default: `true`. */
+    /** Show running session USD on the Usage tab. Default: `true`. */
     showCost: boolean;
-    /** Show cumulative session tokens on the Cost tab. Default: `true`. */
+    /** Show cumulative session tokens on the Usage tab. Default: `true`. */
     showTokens: boolean;
-    /** Live-session badge label on the Cost tab summary. */
+    /** Live-session badge label on the Usage tab summary. */
     badgeLabel: string;
+    /**
+     * Host-supplied disclosure line for the Usage 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 +3656,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 Usage 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
@@ -3428,7 +3721,14 @@ export declare interface SessionPreferences {
     animations?: string[];
 }
 
-/** Settings vs Cost tab identifiers for the modal tab bar. */
+/**
+ * Tab identifiers for the modal tab bar.
+ *
+ * The values are deliberately NOT renamed to match the visible labels ("Configuration" and
+ * "Usage"): they are the public API that hosts read and write via `settingsModalTab`, and are
+ * matched by the `settings-modal-tab-*` shadow parts. Renaming a label is cosmetic; renaming
+ * these would break consumers.
+ */
 declare type SettingsModalTab = 'settings' | 'cost';
 
 /** Design-system tabs element bound to the settings modal tab bar. */