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

package/dist/ai-assistant.api.json

@@ -5916,7 +5916,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/ai-assistant!CostSessionModelEntry:interface",
-          "docComment": "/**\n * A model used during a finalized cost session.\n */\n",
+          "docComment": "/**\n * A model used during a recorded cost session.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -5989,7 +5989,7 @@
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord:interface",
-          "docComment": "/**\n * Persisted snapshot of a completed assistant cost session.\n */\n",
+          "docComment": "/**\n * Persisted usage record for one project's assistant work.\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -6003,16 +6003,16 @@
           "members": [
             {
               "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#costUsd:member",
+              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#id:member",
               "docComment": "",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "costUsd: "
+                  "text": "id: "
                 },
                 {
                   "kind": "Content",
-                  "text": "number"
+                  "text": "string"
                 },
                 {
                   "kind": "Content",
@@ -6022,7 +6022,7 @@
               "isReadonly": false,
               "isOptional": false,
               "releaseTag": "Public",
-              "name": "costUsd",
+              "name": "id",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
                 "endIndex": 2
@@ -6030,16 +6030,21 @@
             },
             {
               "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#endedAt:member",
-              "docComment": "/**\n * ISO-8601 timestamp when the session was finalized.\n */\n",
+              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#models:member",
+              "docComment": "",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "endedAt: "
+                  "text": "models: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "CostSessionModelEntry",
+                  "canonicalReference": "@genesislcap/ai-assistant!CostSessionModelEntry:interface"
                 },
                 {
                   "kind": "Content",
-                  "text": "string"
+                  "text": "[]"
                 },
                 {
                   "kind": "Content",
@@ -6049,20 +6054,20 @@
               "isReadonly": false,
               "isOptional": false,
               "releaseTag": "Public",
-              "name": "endedAt",
+              "name": "models",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 2
+                "endIndex": 3
               }
             },
             {
               "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#id:member",
-              "docComment": "",
+              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#projectKey:member",
+              "docComment": "/**\n * 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.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "id: "
+                  "text": "projectKey: "
                 },
                 {
                   "kind": "Content",
@@ -6076,7 +6081,7 @@
               "isReadonly": false,
               "isOptional": false,
               "releaseTag": "Public",
-              "name": "id",
+              "name": "projectKey",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
                 "endIndex": 2
@@ -6084,21 +6089,16 @@
             },
             {
               "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#models:member",
+              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#title:member",
               "docComment": "",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "models: "
-                },
-                {
-                  "kind": "Reference",
-                  "text": "CostSessionModelEntry",
-                  "canonicalReference": "@genesislcap/ai-assistant!CostSessionModelEntry:interface"
+                  "text": "title: "
                 },
                 {
                   "kind": "Content",
-                  "text": "[]"
+                  "text": "string"
                 },
                 {
                   "kind": "Content",
@@ -6108,20 +6108,20 @@
               "isReadonly": false,
               "isOptional": false,
               "releaseTag": "Public",
-              "name": "models",
+              "name": "title",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 3
+                "endIndex": 2
               }
             },
             {
               "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#title:member",
-              "docComment": "",
+              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#updatedAt:member",
+              "docComment": "/**\n * ISO-8601 timestamp of the most recent usage recorded for this row.\n *\n * 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.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "title: "
+                  "text": "updatedAt: "
                 },
                 {
                   "kind": "Content",
@@ -6135,7 +6135,7 @@
               "isReadonly": false,
               "isOptional": false,
               "releaseTag": "Public",
-              "name": "title",
+              "name": "updatedAt",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
                 "endIndex": 2
@@ -6143,16 +6143,17 @@
             },
             {
               "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#tokensConsumed:member",
-              "docComment": "",
+              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#usage:member",
+              "docComment": "/**\n * 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.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "tokensConsumed: "
+                  "text": "usage: "
                 },
                 {
-                  "kind": "Content",
-                  "text": "number"
+                  "kind": "Reference",
+                  "text": "AggregateUsage",
+                  "canonicalReference": "@genesislcap/foundation-ai!AggregateUsage:interface"
                 },
                 {
                   "kind": "Content",
@@ -6162,7 +6163,7 @@
               "isReadonly": false,
               "isOptional": false,
               "releaseTag": "Public",
-              "name": "tokensConsumed",
+              "name": "usage",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
                 "endIndex": 2
@@ -6801,7 +6802,7 @@
         {
           "kind": "Class",
           "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant:class",
-          "docComment": "/**\n * Foundation AI Assistant component.\n *\n * @remarks\n *\n * Register one or more AI providers via `registerAIProviders` from `@genesislcap/foundation-ai`; this element resolves the `AIProviderRegistry` through the DI container. Pass agent configuration via the `agents` property — each agent can override which registered provider it uses via `provider:`. The component creates a `ChatDriver` (single agent) or `OrchestratingDriver` (multiple agents) to manage the conversation loop.\n *\n * Popout/collapse coordination uses `agenticActivityBus` topics `chat-popout` and `chat-popin` — not DOM `CustomEvent`s on this element.\n *\n * **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}.\n *\n * @fires\n *\n * 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`\n *\n * @fires\n *\n * 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`\n *\n * @beta\n */\n",
+          "docComment": "/**\n * Foundation AI Assistant component.\n *\n * @remarks\n *\n * Register one or more AI providers via `registerAIProviders` from `@genesislcap/foundation-ai`; this element resolves the `AIProviderRegistry` through the DI container. Pass agent configuration via the `agents` property — each agent can override which registered provider it uses via `provider:`. The component creates a `ChatDriver` (single agent) or `OrchestratingDriver` (multiple agents) to manage the conversation loop.\n *\n * Popout/collapse coordination uses `agenticActivityBus` topics `chat-popout` and `chat-popin` — not DOM `CustomEvent`s on this element.\n *\n * **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.\n *\n * @fires\n *\n * 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`\n *\n * @fires\n *\n * 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`\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -8293,7 +8294,7 @@
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#finalizeCostSession:member(1)",
-              "docComment": "/**\n * Snapshot the running session into persisted build history (`localStorage`). No-op unless `chatConfig.costHistory.enabled` is `true`.\n */\n",
+              "docComment": "/**\n * 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.\n *\n * **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.\n *\n * No-op unless `chatConfig.costHistory.enabled` is `true`, when there is no usage yet, or when the session has no key to upsert against.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -10022,7 +10023,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#sessionCostUsd:member",
-              "docComment": "/**\n * Aggregated USD cost across every chat turn in this session.\n */\n",
+              "docComment": "/**\n * Aggregated USD cost across every chat turn in this session.\n *\n * 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.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -10034,10 +10035,10 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n\nset sessionCostUsd(value: number);"
+                  "text": ";"
                 }
               ],
-              "isReadonly": false,
+              "isReadonly": true,
               "isOptional": false,
               "releaseTag": "Beta",
               "name": "sessionCostUsd",
@@ -10206,7 +10207,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#sessionTokensConsumed:member",
-              "docComment": "/**\n * Cumulative input + output tokens across every chat turn in this session.\n */\n",
+              "docComment": "/**\n * Total tokens across every chat turn in this session — all four buckets added up. Read-only; the per-bucket split is on `sessionUsage`.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -10218,10 +10219,10 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n\nset sessionTokensConsumed(value: number);"
+                  "text": ";"
                 }
               ],
-              "isReadonly": false,
+              "isReadonly": true,
               "isOptional": false,
               "releaseTag": "Beta",
               "name": "sessionTokensConsumed",
@@ -10233,6 +10234,46 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#sessionUsage:member",
+              "docComment": "/**\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get sessionUsage(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AggregateUsage",
+                  "canonicalReference": "@genesislcap/foundation-ai!AggregateUsage:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";\n\nset sessionUsage(value: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AggregateUsage",
+                  "canonicalReference": "@genesislcap/foundation-ai!AggregateUsage:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ");"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "sessionUsage",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Method",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#setAgent:member(1)",
@@ -15177,6 +15218,65 @@
               ],
               "name": "load"
             },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/ai-assistant!SessionPersistenceProvider#loadCostHistory:member(1)",
+              "docComment": "/**\n * Scoped cost/build history — the per-project usage rows behind the Cost tab.\n *\n * ‼️ **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'`.\n *\n * 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.\n *\n * 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.\n *\n * `undefined` from `loadCostHistory` means \"nothing stored\", the same as `[]`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "loadCostHistory?(scope: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<"
+                },
+                {
+                  "kind": "Reference",
+                  "text": "CostSessionRecord",
+                  "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "[] | undefined>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": true,
+              "returnTypeTokenRange": {
+                "startIndex": 3,
+                "endIndex": 7
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "scope",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "loadCostHistory"
+            },
             {
               "kind": "MethodSignature",
               "canonicalReference": "@genesislcap/ai-assistant!SessionPersistenceProvider#loadDiagnostics:member(1)",
@@ -15362,6 +15462,77 @@
               ],
               "name": "save"
             },
+            {
+              "kind": "MethodSignature",
+              "canonicalReference": "@genesislcap/ai-assistant!SessionPersistenceProvider#saveCostHistory:member(1)",
+              "docComment": "/**\n * Replace the stored row list for `scope`. See {@link SessionPersistenceProvider.loadCostHistory}.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "saveCostHistory?(scope: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", records: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "CostSessionRecord",
+                  "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "[]"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "Promise",
+                  "canonicalReference": "!Promise:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "<void>"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isOptional": true,
+              "returnTypeTokenRange": {
+                "startIndex": 6,
+                "endIndex": 8
+              },
+              "releaseTag": "Public",
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "scope",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "records",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 5
+                  },
+                  "isOptional": false
+                }
+              ],
+              "name": "saveCostHistory"
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!SessionPersistenceProvider#saveDebounceMs:member",

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,38 @@ 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.
+     */
+    usage: AggregateUsage;
     models: CostSessionModelEntry[];
 }
 
@@ -1905,10 +1923,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,21 +2162,42 @@ 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. */
     get cumulativeCostUsd(): number;
     /** 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 there is no usage yet,
+     * or when the session has no key to upsert against.
      */
     finalizeCostSession(options?: {
         title?: string;
@@ -2167,6 +2209,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 +2280,6 @@ 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;
     private _handlePageHide;
     private haloStartPublished;
     /** Fingerprint of the agents array used to build the current driver. Used by agentsChanged to skip spurious rebuilds. */
@@ -3268,6 +3324,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 +3447,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