@genesislcap/ai-assistant 15.4.1 → 15.6.0

package/src/components/settings-modal/settings-modal.template.ts

@@ -1,4 +1,4 @@
-import type { AIProviderRegistryStatusEntry } from '@genesislcap/foundation-ai';
+import type { AggregateUsage } from '@genesislcap/foundation-ai';
 import { html, ref, repeat, slotted, when, type ViewTemplate } from '@genesislcap/web-core';
 import type { FoundationAiAssistant } from '../../main/main';
 import { ANIMATION_DEFS, type AiAssistantAnimation } from '../../main/main.types';
@@ -8,7 +8,7 @@ import {
   type CostSessionModelEntry,
   type CostSessionRecord,
 } from '../../utils/cost-session-history';
-import { formatCompactTokenCountPlain, formatCompactTokenCountSafe } from '../../utils/sum-tokens';
+import { formatCompactTokenCountSafe } from '../../utils/sum-tokens';
 
 const SESSION_COST_DECIMALS = 2;
 
@@ -114,18 +114,41 @@ const animationsPickerTemplate = (
   </div>
 `;
 
-/** 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.
+ */
 export type SettingsModalTab = 'settings' | 'cost';
 
+/**
+ * How a settings row places its control.
+ *
+ * `row` top-aligns it, which is what a switch wants — it then sits level with the title rather
+ * than floating beside a two-line description. `row-centered` is for a taller control such as a
+ * button, which top-aligned reads as hanging above the text it belongs to. `column` stacks the
+ * control under the text, for controls that need the full width.
+ */
+type SettingsRowLayout = 'row' | 'row-centered' | 'column';
+
+const SETTINGS_ROW_LAYOUT_CLASS: Record<SettingsRowLayout, string> = {
+  row: '',
+  'row-centered': 'is-centered',
+  column: 'is-stacked',
+};
+
 /** Shared label + control row used for switches, buttons, and multiselects. */
 const settingsToggleRow = (
   title: string,
   description: string,
   part: string,
   control: ViewTemplate<FoundationAiAssistant>,
-  layout: 'row' | 'column' = 'row',
+  layout: SettingsRowLayout = 'row',
 ) => html<FoundationAiAssistant>`
-  <div class="settings-toggle-row ${layout === 'column' ? 'is-stacked' : ''}" part="${part}-row">
+  <div class="settings-toggle-row ${SETTINGS_ROW_LAYOUT_CLASS[layout]}" part="${part}-row">
     <div class="settings-toggle-text">
       <div class="settings-toggle-title">${title}</div>
       <div class="settings-toggle-desc">${description}</div>
@@ -265,7 +288,34 @@ const chatBotSettingsTemplate = (
 
 const appSettingsTemplate = (
   switchTag: string,
+  iconTag: string,
 ): ViewTemplate<FoundationAiAssistant> => html<FoundationAiAssistant>`
+  <!--
+    Slot FIRST, ahead of the provider toggles. The assistant renders no heading for this
+    section, so whatever the host slots in has to be able to title it — and a heading below the
+    rows it names would title nothing. Anything the host wants under the toggles it can render
+    below them within its own slotted block.
+  -->
+  <slot name="settings-app" ${slotted('settingsAppSlotted')}></slot>
+  <!--
+    Sub-heading for the toggle group, rendered only when the host asks for one — both the text
+    and the icon come from its provider. It exists so a host whose slotted content covers other
+    ground can still mark these rows off from it.
+  -->
+  ${when(
+    (x) => !!x.appSettingsTogglesHeading,
+    html<FoundationAiAssistant>`
+      <h4 class="ai-settings-section-title settings-app-toggles-title" part="app-toggles-title">
+        ${when(
+          (x) => !!x.appSettingsTogglesHeading?.icon,
+          html<FoundationAiAssistant>`
+            <${iconTag} name="${(x) => x.appSettingsTogglesHeading?.icon}"></${iconTag}>
+          `,
+        )}
+        ${(x) => x.appSettingsTogglesHeading?.title}
+      </h4>
+    `,
+  )}
   ${repeat(
     (x) => x.visibleAppSettingsToggles,
     html<AssistantAppSettingsToggle, FoundationAiAssistant>`
@@ -298,9 +348,142 @@ const appSettingsTemplate = (
       </div>
     `,
   )}
-  <slot name="settings-app" ${slotted('settingsAppSlotted')}></slot>
 `;
 
+/**
+ * One model chip. Shared by the live session and the history rows so the two can't drift — both
+ * already reduce to a distinct-model list, the live one via `uniqueProviderModels` and a row via
+ * `collectSessionModels`.
+ */
+const modelTagTemplate = html<CostSessionModelEntry>`
+  <span class="settings-model-tag vendor-${(entry) => entry.provider || 'generic'}">
+    ${(entry) => entry.model}
+  </span>
+`;
+
+/**
+ * The four billing buckets for one `AggregateUsage`, wherever it comes from — the lifetime
+ * total, the live session, or a history row.
+ *
+ * Why four numbers instead of one: each bucket bills at a different rate, so a single token
+ * total can't explain a session that processed millions of tokens for pennies. Uncached input,
+ * cache read and cache write partition the prompt (they sum to it, never add on top), and
+ * output is what the model generated.
+ *
+ * Ordered input, output, cache read, cache write to match how Claude Code reports usage, so the
+ * two can be read side by side — comparing against it is what this breakdown exists for. Note
+ * this puts output between the three buckets that partition the prompt, so their relationship is
+ * carried by the tooltips rather than by adjacency.
+ *
+ * `partPrefix` keeps the shadow-part names caller-specific (`session-tokens-input`,
+ * `lifetime-tokens-input`, …) so a host can style one context without hitting the others.
+ */
+const tokenBreakdownTemplate = <T>(
+  usageOf: (x: T) => AggregateUsage,
+  partPrefix: string,
+): ViewTemplate<T> => html<T>`
+  <div class="settings-token-breakdown" part="${partPrefix}-token-breakdown">
+    <!--
+      Titles the box. Nothing in it otherwise said "tokens": the four bucket names are the
+      token TYPES, not the unit, so the panel read as four unexplained numbers unless the
+      reader found the per-bucket tooltips.
+    -->
+    <div class="settings-token-breakdown-label">Tokens</div>
+    <div class="settings-token-buckets">
+      <div class="settings-token-bucket" part="${partPrefix}-tokens-input">
+        <span
+          class="settings-token-bucket-label"
+          title="Prompt tokens billed at the full uncached rate"
+        >
+          Input
+        </span>
+        <span
+          class="settings-token-bucket-value"
+          :innerHTML="${(x: T) => formatCompactTokenCountSafe(usageOf(x).uncachedInputTokens)}"
+        ></span>
+      </div>
+      <div class="settings-token-bucket" part="${partPrefix}-tokens-output">
+        <span
+          class="settings-token-bucket-label"
+          title="Tokens the model generated, including reasoning tokens billed as output"
+        >
+          Output
+        </span>
+        <span
+          class="settings-token-bucket-value"
+          :innerHTML="${(x: T) => formatCompactTokenCountSafe(usageOf(x).outputTokens)}"
+        ></span>
+      </div>
+      <div class="settings-token-bucket is-discounted" part="${partPrefix}-tokens-cache-read">
+        <span
+          class="settings-token-bucket-label"
+          title="Prompt tokens served from the provider cache — billed at a fraction of the uncached rate"
+        >
+          Cache read
+        </span>
+        <span
+          class="settings-token-bucket-value"
+          :innerHTML="${(x: T) => formatCompactTokenCountSafe(usageOf(x).cacheReadTokens)}"
+        ></span>
+      </div>
+      <div class="settings-token-bucket" part="${partPrefix}-tokens-cache-write">
+        <span
+          class="settings-token-bucket-label"
+          title="Prompt tokens written to the provider cache — billed at a premium over the uncached rate"
+        >
+          Cache write
+        </span>
+        <span
+          class="settings-token-bucket-value"
+          :innerHTML="${(x: T) => formatCompactTokenCountSafe(usageOf(x).cacheWriteTokens)}"
+        ></span>
+      </div>
+    </div>
+  </div>
+`;
+
+/**
+ * Lifetime usage across every project in the history scope.
+ *
+ * Sits above the live session block because it is the wider figure. It used to live inside
+ * that block as a lone "Total build cost", where the live badge and project name directly
+ * above it implied the total belonged to the open project.
+ */
+const lifetimeUsageTemplate =
+  (): ViewTemplate<FoundationAiAssistant> => html<FoundationAiAssistant>`
+    ${when(
+      (x) => x.settingsCostLifetimeVisible,
+      html<FoundationAiAssistant>`
+        <div class="settings-lifetime-usage" part="lifetime-usage">
+          <div class="settings-lifetime-usage-top">
+            <span class="settings-lifetime-label">Lifetime usage</span>
+          </div>
+          <div class="settings-usage-row">
+            <div
+              class="settings-build-stat"
+              part="lifetime-cost"
+              ?hidden=${(x) => !x.resolvedCostHistory.showCost}
+            >
+              <div class="settings-build-stat-label">Total build cost</div>
+              <div class="settings-build-stat-value">
+                <span class="prefix">$</span>
+                <span class="value">
+                  ${(x) => x.cumulativeCostUsd.toFixed(SESSION_COST_DECIMALS)}
+                </span>
+              </div>
+            </div>
+            <div
+              class="settings-usage-row-tokens"
+              ?hidden=${(x) => !x.resolvedCostHistory.showTokens}
+            >
+              ${tokenBreakdownTemplate<FoundationAiAssistant>((x) => x.cumulativeUsage, 'lifetime')}
+            </div>
+          </div>
+        </div>
+      `,
+    )}
+  `;
+
 const sessionCostSummaryTemplate =
   (): ViewTemplate<FoundationAiAssistant> => html<FoundationAiAssistant>`
     ${when(
@@ -319,58 +502,38 @@ const sessionCostSummaryTemplate =
               `,
             )}
           </div>
-          <div class="settings-current-build-stats">
+          <div class="settings-usage-row">
             <div
               class="settings-build-stat"
               part="session-cost"
               ?hidden=${(x) => !x.resolvedCostHistory.showCost}
             >
-              <div class="settings-build-stat-label">Current session cost</div>
+              <!--
+                Label states the scope rather than implying one. These figures are whatever
+                the open transcript proves, so they are the project's whole history exactly
+                when that transcript is restored on load, and only this page-load's when it
+                isn't. Same number, two meanings — so the caller can't be left guessing.
+              -->
+              <div class="settings-build-stat-label">
+                ${(x) => (x.liveUsageIsProjectLifetime ? 'Project cost' : 'Session cost')}
+              </div>
               <div class="settings-build-stat-value">
                 <span class="prefix">$</span>
                 <span class="value">${(x) => x.sessionCostUsd.toFixed(SESSION_COST_DECIMALS)}</span>
               </div>
             </div>
             <div
-              class="settings-build-stat"
-              part="session-tokens"
+              class="settings-usage-row-tokens"
               ?hidden=${(x) => !x.resolvedCostHistory.showTokens}
             >
-              <div class="settings-build-stat-label">Tokens consumed</div>
-              <div
-                class="settings-build-stat-value"
-                :innerHTML="${(x) => formatCompactTokenCountSafe(x.sessionTokensConsumed)}"
-              ></div>
-            </div>
-            <div
-              class="settings-build-stat"
-              part="session-cumulative-cost"
-              ?hidden=${(x) => !x.resolvedCostHistory.showCost}
-            >
-              <div class="settings-build-stat-label">Total build cost</div>
-              <div class="settings-build-stat-value">
-                <span class="prefix">$</span>
-                <span class="value">
-                  ${(x) => x.cumulativeCostUsd.toFixed(SESSION_COST_DECIMALS)}
-                </span>
-              </div>
+              ${tokenBreakdownTemplate<FoundationAiAssistant>((x) => x.sessionUsage, 'session')}
             </div>
           </div>
           ${when(
-            (x) => x.chatConfig.ui?.showActiveModel !== false && x.providerStatuses.length > 0,
+            (x) => x.chatConfig.ui?.showActiveModel !== false && x.uniqueProviderModels.length > 0,
             html<FoundationAiAssistant>`
               <div class="settings-model-tags" part="session-model-tags">
-                ${repeat(
-                  (x) => x.providerStatuses,
-                  html<AIProviderRegistryStatusEntry>`
-                    <span
-                      class="settings-model-tag vendor-${(entry) =>
-                        entry.status?.provider || 'generic'}"
-                    >
-                      ${(entry) => entry.status?.model ?? entry.name}
-                    </span>
-                  `,
-                )}
+                ${repeat((x) => x.uniqueProviderModels, modelTagTemplate)}
               </div>
             `,
           )}
@@ -384,7 +547,7 @@ const costSessionHistoryTemplate = (
   buttonTag: string,
 ): ViewTemplate<FoundationAiAssistant> => html<FoundationAiAssistant>`
   ${repeat(
-    (x) => x.costSessionHistory,
+    (x) => x.sortedCostSessionHistory,
     html<CostSessionRecord>`
       <div class="settings-cost-history-row" part="cost-history-row">
         <div class="settings-cost-history-row-content">
@@ -397,29 +560,46 @@ const costSessionHistoryTemplate = (
                 ${(record) => record.title}
               </div>
               <div class="settings-cost-history-row-date">
-                ${(record) => formatCostSessionDate(record.endedAt)}
+                ${(record) => formatCostSessionDate(record.updatedAt)}
               </div>
             </div>
+            <!--
+              Cost and the delete control live together so they centre against each other.
+              The button used to sit outside the row body, held in place by a negative margin
+              tuned for when this column had a second line (a merged token total); that line
+              is gone, and a nudge measured against a removed sibling is exactly the kind that
+              rots silently.
+            -->
             <div class="settings-cost-history-row-right">
               <div class="settings-cost-history-row-metrics">
                 <div class="settings-cost-history-row-cost">
-                  $${(record) => record.costUsd.toFixed(SESSION_COST_DECIMALS)}
-                </div>
-                <div class="settings-cost-history-row-tokens">
-                  ${(record) => formatCompactTokenCountPlain(record.tokensConsumed)} tokens
+                  $${(record) => record.usage.costUsd.toFixed(SESSION_COST_DECIMALS)}
                 </div>
               </div>
+              <${buttonTag}
+                class="settings-cost-history-delete"
+                part="cost-history-delete"
+                appearance="stealth"
+                aria-label="Remove from build history"
+                @click=${(record, c) => c.parent.showConfirmationDialog('Are you sure you want to remove this build from history?', c.parent.settingsModal, () => c.parent.removeCostSessionFromHistory(record.id))}
+              >
+                <${iconTag} name="trash"></${iconTag}>
+              </${buttonTag}>
             </div>
           </div>
-          <${buttonTag}
-            class="settings-cost-history-delete"
-            part="cost-history-delete"
-            appearance="stealth"
-            aria-label="Remove from build history"
-            @click=${(record, c) => c.parent.showConfirmationDialog('Are you sure you want to remove this build from history?', c.parent.settingsModal, () => c.parent.removeCostSessionFromHistory(record.id))}
-          >
-            <${iconTag} name="trash"></${iconTag}>
-          </${buttonTag}>
+        </div>
+        <!--
+          The same four buckets as the live block, on its own line below the row rather than
+          beside the cost — the row's own width is spoken for by title, cost and delete.
+          Replaces a merged total that could not explain a huge token count at a small cost
+          without hovering for a tooltip.
+        -->
+        <div
+          class="settings-cost-history-row-content settings-cost-history-row-breakdown"
+          ?hidden=${(record, c) =>
+            !(c.parent as FoundationAiAssistant).resolvedCostHistory.showTokens}
+        >
+          ${tokenBreakdownTemplate<CostSessionRecord>((record) => record.usage, 'cost-history-row')}
         </div>
         ${when(
           (record) => record.models.length > 0,
@@ -427,14 +607,7 @@ const costSessionHistoryTemplate = (
             <div
               class="settings-cost-history-row-content settings-model-tags settings-cost-history-model-tags"
             >
-              ${repeat(
-                (record) => record.models,
-                html<CostSessionModelEntry>`
-                  <span class="settings-model-tag vendor-${(model) => model.provider || 'generic'}">
-                    ${(model) => model.model}
-                  </span>
-                `,
-              )}
+              ${repeat((record) => record.models, modelTagTemplate)}
             </div>
           `,
         )}
@@ -444,7 +617,7 @@ const costSessionHistoryTemplate = (
 `;
 
 /**
- * Modal shell for assistant settings — Settings and Cost tabs, section slots for
+ * Modal shell for assistant settings — Configuration and Usage tabs, section slots for
  * app-specific UI, and built-in chat-bot toggles.
  */
 export const SettingsModalTemplate = (
@@ -471,7 +644,7 @@ export const SettingsModalTemplate = (
         part="settings-section-model"
         ?hidden=${(x) => !x.settingsModelSectionVisible}
       >
-        <h3 class="settings-modal-section-title">
+        <h3 class="ai-settings-section-title">
           <${iconTag} name="microchip"></${iconTag}> AI Model Settings
         </h3>
         <div class="settings-modal-section-body">
@@ -479,18 +652,11 @@ export const SettingsModalTemplate = (
           ${platformContextUsageTemplate(progressTag)}
         </div>
       </section>
-      <section
-        class="settings-modal-section"
-        part="settings-section-app"
-        ?hidden=${(x) => !x.settingsAppSectionVisible}
-      >
-        <h3 class="settings-modal-section-title">
-          <${iconTag} name="home"></${iconTag}> ${(x) => x.appSettingsSectionTitle}
-        </h3>
-        <div class="settings-modal-section-body">
-          ${appSettingsTemplate(switchTag)}
-        </div>
-      </section>
+      <!--
+        Above the host section, deliberately. This is the assistant's own control, so it belongs
+        with the assistant's other sections rather than trailing the host's — where, now that the
+        host section carries no heading of its own, it read as one more of the host's settings.
+      -->
       ${when(
         (x) => x.chatConfig.ui?.allowDebugDownload === true,
         html<FoundationAiAssistant>`
@@ -520,13 +686,29 @@ export const SettingsModalTemplate = (
                     ${(x) => (x.downloadingDebugLog ? 'Downloading…' : 'Download')}
                   </${buttonTag}>
                 `,
+                'row-centered',
               )}
             </div>
           </section>
         `,
       )}
+      <!--
+        No heading here, by design. This section belongs to the host: only it knows what its
+        settings are called, so the assistant supplies neither text nor icon and the host titles
+        the section from the slot. See assistantSettingsSectionTitleStyles for the heading style
+        it can apply to match the sections above and below.
+      -->
+      <section
+        class="settings-modal-section"
+        part="settings-section-app"
+        ?hidden=${(x) => !x.settingsAppSectionVisible}
+      >
+        <div class="settings-modal-section-body">
+          ${appSettingsTemplate(switchTag, iconTag)}
+        </div>
+      </section>
       <section class="settings-modal-section" part="settings-section-chat">
-        <h3 class="settings-modal-section-title">
+        <h3 class="ai-settings-section-title">
           <${iconTag} name="comment"></${iconTag}> AI Chat Bot Settings
         </h3>
         <p class="settings-modal-section-note">These options only control what you see in the chat window and do not control model behaviour.</p>
@@ -545,6 +727,7 @@ export const SettingsModalTemplate = (
       part="cost-tab-panel"
     >
       <div class="settings-modal-body" part="settings-modal-body">
+      ${lifetimeUsageTemplate()}
       ${sessionCostSummaryTemplate()}
       <div
         class="settings-cost-current"
@@ -595,7 +778,7 @@ export const SettingsModalTemplate = (
           appearance="secondary" 
           class="settings-modal-tab"
           part="settings-modal-tab-settings"
-        ><${iconTag} name="cog"></${iconTag}> AI Assistant</${tabTag}>${when(
+        ><${iconTag} name="sliders"></${iconTag}> Configuration</${tabTag}>${when(
           (x) => x.settingsCostTabVisible,
           html<FoundationAiAssistant>`<${tabTag} 
             slot="tab" 
@@ -603,7 +786,7 @@ export const SettingsModalTemplate = (
             appearance="secondary" 
             class="settings-modal-tab"
             part="settings-modal-tab-cost"
-          ><${iconTag} name="dollar-sign"></${iconTag}> Cost</${tabTag}>`,
+          ><${iconTag} name="chart-simple"></${iconTag}> Usage</${tabTag}>`,
         )}${settingsTabPanel}${when((x) => x.settingsCostTabVisible, costTabPanel)}</${tabsTag}>
       </div>
       <div slot="bottom" class="settings-modal-footer" part="settings-modal-footer">
@@ -612,7 +795,13 @@ export const SettingsModalTemplate = (
             (x) => x.settingsModalTab === 'cost',
             html<FoundationAiAssistant>`
               <span class="settings-disclaimer">
-                Costs are estimated from token usage at list price.
+                ${when(
+                  (x) => !!x.resolvedCostHistory.summaryHint,
+                  html<FoundationAiAssistant>`
+                    ${(x) => x.resolvedCostHistory.summaryHint}
+                  `,
+                )}Costs
+                are estimated from token usage at list price.
               </span>
             `,
           )}

package/src/index.ts

@@ -16,6 +16,7 @@ export * from './state/persistence';
 export * from './provider/ai-provider-switcher';
 export * from './provider/assistant-app-settings';
 export * from './utils/tool-fold';
+export { assistantSettingsSectionTitleStyles } from './styles/settings-section';
 export type { TurnFailureReason } from './state/debug-event-log';
 export type { TimelineMessage } from './utils/flatten-sub-agent-messages';
 export type { CostSessionModelEntry, CostSessionRecord } from './utils/cost-session-history';