@genesislcap/ai-assistant 15.4.1 → 15.6.0

package/dist/ai-assistant.api.json

@@ -3629,10 +3629,82 @@
           ],
           "name": "assembleDebugLog"
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/ai-assistant!AssistantAppSettingsHeading:interface",
+          "docComment": "/**\n * Optional heading above a provider's toggle group.\n *\n * 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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface AssistantAppSettingsHeading "
+            }
+          ],
+          "fileUrlPath": "src/provider/assistant-app-settings.ts",
+          "releaseTag": "Beta",
+          "name": "AssistantAppSettingsHeading",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AssistantAppSettingsHeading#icon:member",
+              "docComment": "/**\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly icon?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "icon",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AssistantAppSettingsHeading#title:member",
+              "docComment": "",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly title: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "title",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Interface",
           "canonicalReference": "@genesislcap/ai-assistant!AssistantAppSettingsProvider:interface",
-          "docComment": "/**\n * 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.\n *\n * @beta\n */\n",
+          "docComment": "/**\n * 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.\n *\n * 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.\n *\n * @beta\n */\n",
           "excerptTokens": [
             {
               "kind": "Content",
@@ -3689,33 +3761,6 @@
               ],
               "name": "getValue"
             },
-            {
-              "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!AssistantAppSettingsProvider#sectionTitle:member",
-              "docComment": "/**\n * Section heading. Default: `\"UI Builder Settings\"`.\n */\n",
-              "excerptTokens": [
-                {
-                  "kind": "Content",
-                  "text": "readonly sectionTitle?: "
-                },
-                {
-                  "kind": "Content",
-                  "text": "string"
-                },
-                {
-                  "kind": "Content",
-                  "text": ";"
-                }
-              ],
-              "isReadonly": true,
-              "isOptional": true,
-              "releaseTag": "Beta",
-              "name": "sectionTitle",
-              "propertyTypeTokenRange": {
-                "startIndex": 1,
-                "endIndex": 2
-              }
-            },
             {
               "kind": "MethodSignature",
               "canonicalReference": "@genesislcap/ai-assistant!AssistantAppSettingsProvider#setValue:member(1)",
@@ -3857,6 +3902,34 @@
                 "startIndex": 1,
                 "endIndex": 4
               }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!AssistantAppSettingsProvider#togglesHeading:member",
+              "docComment": "/**\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "readonly togglesHeading?: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AssistantAppSettingsHeading",
+                  "canonicalReference": "@genesislcap/ai-assistant!AssistantAppSettingsHeading:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "togglesHeading",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
             }
           ],
           "extendsTokenRanges": []
@@ -4109,6 +4182,30 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Variable",
+          "canonicalReference": "@genesislcap/ai-assistant!assistantSettingsSectionTitleStyles:var",
+          "docComment": "/**\n * Heading style for a settings-modal section, published so a host can title its own section.\n *\n * 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.\n *\n * Compose it into a component's styles and put `ai-settings-section-title` on the heading:\n * ```ts\n * import { assistantSettingsSectionTitleStyles } from '@genesislcap/ai-assistant';\n *\n * const styles = css`\n *   ${assistantSettingsSectionTitleStyles}\n *   :host { display: block; }\n * `;\n * ```\n *\n * 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.\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "assistantSettingsSectionTitleStyles: "
+            },
+            {
+              "kind": "Reference",
+              "text": "ElementStyles",
+              "canonicalReference": "@microsoft/fast-element!ElementStyles:class"
+            }
+          ],
+          "fileUrlPath": "src/styles/settings-section.ts",
+          "isReadonly": true,
+          "releaseTag": "Beta",
+          "name": "assistantSettingsSectionTitleStyles",
+          "variableTypeTokenRange": {
+            "startIndex": 1,
+            "endIndex": 2
+          }
+        },
         {
           "kind": "TypeAlias",
           "canonicalReference": "@genesislcap/ai-assistant!CachePolicyInput:type",
@@ -5565,6 +5662,33 @@
                 "endIndex": 2
               }
             },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!ChatDriverConfig#condenseBatchCalls:member",
+              "docComment": "/**\n * 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.\n *\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "condenseBatchCalls?: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": true,
+              "releaseTag": "Beta",
+              "name": "condenseBatchCalls",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
             {
               "kind": "PropertySignature",
               "canonicalReference": "@genesislcap/ai-assistant!ChatDriverConfig#maxFoldOperations:member",
@@ -5916,7 +6040,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 +6113,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 +6127,17 @@
           "members": [
             {
               "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#costUsd:member",
-              "docComment": "",
+              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#banked:member",
+              "docComment": "/**\n * Spend that predates the current transcript, and so cannot be re-derived from it.\n *\n * 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.\n *\n * 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.\n *\n * Optional: rows written before this existed have none, which reads as \"nothing banked\".\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "costUsd: "
+                  "text": "banked?: "
                 },
                 {
-                  "kind": "Content",
-                  "text": "number"
+                  "kind": "Reference",
+                  "text": "AggregateUsage",
+                  "canonicalReference": "@genesislcap/foundation-ai!AggregateUsage:interface"
                 },
                 {
                   "kind": "Content",
@@ -6020,9 +6145,9 @@
                 }
               ],
               "isReadonly": false,
-              "isOptional": false,
+              "isOptional": true,
               "releaseTag": "Public",
-              "name": "costUsd",
+              "name": "banked",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
                 "endIndex": 2
@@ -6030,12 +6155,12 @@
             },
             {
               "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#id:member",
+              "docComment": "",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "endedAt: "
+                  "text": "id: "
                 },
                 {
                   "kind": "Content",
@@ -6049,7 +6174,7 @@
               "isReadonly": false,
               "isOptional": false,
               "releaseTag": "Public",
-              "name": "endedAt",
+              "name": "id",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
                 "endIndex": 2
@@ -6057,16 +6182,21 @@
             },
             {
               "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#id:member",
+              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#models:member",
               "docComment": "",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "id: "
+                  "text": "models: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "CostSessionModelEntry",
+                  "canonicalReference": "@genesislcap/ai-assistant!CostSessionModelEntry:interface"
                 },
                 {
                   "kind": "Content",
-                  "text": "string"
+                  "text": "[]"
                 },
                 {
                   "kind": "Content",
@@ -6076,29 +6206,24 @@
               "isReadonly": false,
               "isOptional": false,
               "releaseTag": "Public",
-              "name": "id",
+              "name": "models",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 2
+                "endIndex": 3
               }
             },
             {
               "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#models: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": "models: "
-                },
-                {
-                  "kind": "Reference",
-                  "text": "CostSessionModelEntry",
-                  "canonicalReference": "@genesislcap/ai-assistant!CostSessionModelEntry:interface"
+                  "text": "projectKey: "
                 },
                 {
                   "kind": "Content",
-                  "text": "[]"
+                  "text": "string"
                 },
                 {
                   "kind": "Content",
@@ -6108,10 +6233,10 @@
               "isReadonly": false,
               "isOptional": false,
               "releaseTag": "Public",
-              "name": "models",
+              "name": "projectKey",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 3
+                "endIndex": 2
               }
             },
             {
@@ -6143,16 +6268,16 @@
             },
             {
               "kind": "PropertySignature",
-              "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord#tokensConsumed: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": "tokensConsumed: "
+                  "text": "updatedAt: "
                 },
                 {
                   "kind": "Content",
-                  "text": "number"
+                  "text": "string"
                 },
                 {
                   "kind": "Content",
@@ -6162,7 +6287,35 @@
               "isReadonly": false,
               "isOptional": false,
               "releaseTag": "Public",
-              "name": "tokensConsumed",
+              "name": "updatedAt",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "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 * This is the project's **lifetime** usage: `banked` plus whatever the live transcript currently proves.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "usage: "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AggregateUsage",
+                  "canonicalReference": "@genesislcap/foundation-ai!AggregateUsage:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Public",
+              "name": "usage",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
                 "endIndex": 2
@@ -6801,7 +6954,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 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.\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",
@@ -7221,16 +7374,21 @@
             },
             {
               "kind": "Property",
-              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#appSettingsSectionTitle:member",
-              "docComment": "/**\n * Section title for the app settings block.\n */\n",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#appSettingsTogglesHeading:member",
+              "docComment": "/**\n * 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.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
-                  "text": "get appSettingsSectionTitle(): "
+                  "text": "get appSettingsTogglesHeading(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AssistantAppSettingsHeading",
+                  "canonicalReference": "@genesislcap/ai-assistant!AssistantAppSettingsHeading:interface"
                 },
                 {
                   "kind": "Content",
-                  "text": "string"
+                  "text": " | undefined"
                 },
                 {
                   "kind": "Content",
@@ -7240,10 +7398,10 @@
               "isReadonly": true,
               "isOptional": false,
               "releaseTag": "Beta",
-              "name": "appSettingsSectionTitle",
+              "name": "appSettingsTogglesHeading",
               "propertyTypeTokenRange": {
                 "startIndex": 1,
-                "endIndex": 2
+                "endIndex": 3
               },
               "isStatic": false,
               "isProtected": false,
@@ -7936,7 +8094,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#costSessionHistory:member",
-              "docComment": "/**\n * Persisted finalized cost sessions shown on the Cost tab build history list.\n */\n",
+              "docComment": "/**\n * Persisted finalized cost sessions shown on the Usage tab build history list.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -7971,7 +8129,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#cumulativeCostUsd:member",
-              "docComment": "/**\n * Saved build history plus the in-flight session — shown on the Cost tab summary.\n */\n",
+              "docComment": "/**\n * Lifetime USD across every project in the history scope.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -7998,6 +8156,37 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#cumulativeUsage:member",
+              "docComment": "/**\n * Lifetime usage across every project in the history scope — cost and all four token buckets. What the Usage tab's lifetime section renders.\n *\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get cumulativeUsage(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "AggregateUsage",
+                  "canonicalReference": "@genesislcap/foundation-ai!AggregateUsage:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "cumulativeUsage",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#debugRedux:member",
@@ -8293,7 +8482,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 Usage tab counted both.\n *\n * 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.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -8909,7 +9098,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#liveCostSessionTitle:member",
-              "docComment": "/**\n * Label shown on the Cost tab for the in-flight session (app title or first user phrase).\n */\n",
+              "docComment": "/**\n * Label shown on the Usage tab for the in-flight session (app title or first user phrase).\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -9010,6 +9199,36 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#liveUsageIsProjectLifetime:member",
+              "docComment": "/**\n * 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.\n *\n * Note this is NOT what makes the *rows* lifetime — those bank their pre-transcript spend (see `CostSessionRecord.banked`) and are lifetime either way.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get liveUsageIsProjectLifetime(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "liveUsageIsProjectLifetime",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#messages:member",
@@ -10022,7 +10241,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 +10253,10 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n\nset sessionCostUsd(value: number);"
+                  "text": ";"
                 }
               ],
-              "isReadonly": false,
+              "isReadonly": true,
               "isOptional": false,
               "releaseTag": "Beta",
               "name": "sessionCostUsd",
@@ -10206,7 +10425,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 +10437,10 @@
                 },
                 {
                   "kind": "Content",
-                  "text": ";\n\nset sessionTokensConsumed(value: number);"
+                  "text": ";"
                 }
               ],
-              "isReadonly": false,
+              "isReadonly": true,
               "isOptional": false,
               "releaseTag": "Beta",
               "name": "sessionTokensConsumed",
@@ -10233,6 +10452,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)",
@@ -10766,10 +11025,40 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#settingsCostLifetimeVisible:member",
+              "docComment": "/**\n * Whether the lifetime-usage section has anything to say.\n *\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get settingsCostLifetimeVisible(): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "settingsCostLifetimeVisible",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#settingsCostSummaryVisible:member",
-              "docComment": "/**\n * Whether the built-in Cost tab summary block has anything to show.\n */\n",
+              "docComment": "/**\n * Whether the built-in Usage tab summary block has anything to show.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -10799,7 +11088,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#settingsCostTabVisible:member",
-              "docComment": "/**\n * Whether the Cost tab should appear in the settings modal.\n */\n",
+              "docComment": "/**\n * Whether the Usage tab should appear in the settings modal.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -10986,7 +11275,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#settingsSessionTokensVisible:member",
-              "docComment": "/**\n * Whether session token usage should render on the Cost tab.\n */\n",
+              "docComment": "/**\n * Whether session token usage should render on the Usage tab.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -11444,6 +11733,41 @@
               "isProtected": false,
               "isAbstract": false
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#sortedCostSessionHistory:member",
+              "docComment": "/**\n * Build history for display: most recently worked on first.\n *\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get sortedCostSessionHistory(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "CostSessionRecord",
+                  "canonicalReference": "@genesislcap/ai-assistant!CostSessionRecord:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "[]"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "sortedCostSessionHistory",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#state:member",
@@ -11907,6 +12231,41 @@
               "isAbstract": false,
               "name": "triggerFileInput"
             },
+            {
+              "kind": "Property",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#uniqueProviderModels:member",
+              "docComment": "/**\n * Distinct models the registry currently resolves to — the live session's model chips.\n *\n * `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.\n *\n * 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.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "get uniqueProviderModels(): "
+                },
+                {
+                  "kind": "Reference",
+                  "text": "CostSessionModelEntry",
+                  "canonicalReference": "@genesislcap/ai-assistant!CostSessionModelEntry:interface"
+                },
+                {
+                  "kind": "Content",
+                  "text": "[]"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": true,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "uniqueProviderModels",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 3
+              },
+              "isStatic": false,
+              "isProtected": false,
+              "isAbstract": false
+            },
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#userIcon:member",
@@ -15177,6 +15536,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 Usage 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 +15780,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",