@genesislcap/ai-assistant 15.7.3-alpha-e7d4aa5.0 → 15.8.0

package/dist/ai-assistant.api.json

@@ -11515,7 +11515,7 @@
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#settingsModelSectionVisible:member",
-              "docComment": "/**\n * Whether the settings modal AI Model section has slotted app content or context usage.\n */\n",
+              "docComment": "/**\n * Whether the settings modal AI Model section has slotted app content, context usage or budget figures.\n */\n",
               "excerptTokens": [
                 {
                   "kind": "Content",
@@ -11749,6 +11749,70 @@
               "isAbstract": false,
               "name": "setVendorBlocked"
             },
+            {
+              "kind": "Method",
+              "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#setVendorBudget:member(1)",
+              "docComment": "/**\n * Feed (or clear) one vendor's AI-spend figures for the settings-modal budget meter — the numeric companion to {@link FoundationAiAssistant.setVendorBlocked}, and like it a host-driven write: the element meters nothing itself.\n *\n * The meter renders a row for exactly the vendors that currently HAVE figures. An **unlimited** vendor (the budget endpoint reports `unlimited: true` / `limitUsd: null`) is expressed by never feeding it — there is deliberately no \"unlimited\" figure shape, because a bar with no cap has nothing truthful to fill to. `spentUsd` MAY exceed `budgetUsd` (the last allowed call can overshoot the cap): the row's text shows the real figures and only the bar clamps.\n *\n * Returns `false` — and warns once, not per call — instead of throwing when `vendor` is not a budgeted vendor (`BUDGETED_VENDORS`, the proxy's own metered list) or either figure is not a finite number `>= 0`. Invalid input changes no state. Idempotent: re-feeding a vendor's current figures is a no-op, so hosts can re-feed unconditionally after every turn.\n *\n * `false` ALSO means \"not stored, because the element is not ready yet\": a feed that lands before the element has its session store (a host calling ahead of the first append, or during a pop-out remount) stores nothing and says so, rather than reporting a write that never happened. That case is transient and needs no host handling — the documented per-turn re-feed is what recovers it — so it is deliberately NOT warned about; the warn-once channel is for garbage input only.\n *\n * `figures` is nullish-checked at run time, so `undefined` behaves exactly like `null` and CLEARS that vendor's row. Untyped JS hosts feed this straight from `GET /api/budget`, where a per-vendor lookup that misses yields `undefined`, not `null` — and \"no figures\" coherently means \"no row\". The `| null` parameter type is unchanged for typed callers; the runtime is deliberately the more forgiving of the two.\n *\n * The intended feed is the platform budget endpoint:\n * ```ts\n * // `vendors` is an OBJECT keyed by vendor id, not an array.\n * const { vendors } = await (await fetch('/api/budget')).json();\n * for (const v of Object.values(vendors)) {\n *   if (v.unlimited || v.limitUsd == null) {\n *     assistantEl.setVendorBudget(v.vendor, null); // clear stale figures after a cap is lifted\n *     continue;\n *   }\n *   assistantEl.setVendorBudget(v.vendor, { budgetUsd: v.limitUsd, spentUsd: v.spentUsd });\n * }\n * ```\n *\n * Re-run it on mount and after each turn. Scope and lifetime follow the rest of the session slice (per `stateKey`, survives pop-in/out and \"Clear\" / \"New chat\") — except that the figures are NOT persisted to the session snapshot: the server is authoritative and the host re-feeds at boot, so a persisted copy could only show stale dollars after a reload.\n *\n * @beta\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "setVendorBudget(vendor: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ", figures: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "{\n        budgetUsd: number;\n        spentUsd: number;\n    } | null"
+                },
+                {
+                  "kind": "Content",
+                  "text": "): "
+                },
+                {
+                  "kind": "Content",
+                  "text": "boolean"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isStatic": false,
+              "returnTypeTokenRange": {
+                "startIndex": 5,
+                "endIndex": 6
+              },
+              "releaseTag": "Beta",
+              "isProtected": false,
+              "overloadIndex": 1,
+              "parameters": [
+                {
+                  "parameterName": "vendor",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 1,
+                    "endIndex": 2
+                  },
+                  "isOptional": false
+                },
+                {
+                  "parameterName": "figures",
+                  "parameterTypeTokenRange": {
+                    "startIndex": 3,
+                    "endIndex": 4
+                  },
+                  "isOptional": false
+                }
+              ],
+              "isOptional": false,
+              "isAbstract": false,
+              "name": "setVendorBudget"
+            },
             {
               "kind": "Property",
               "canonicalReference": "@genesislcap/ai-assistant!FoundationAiAssistant#showAgentSwitchIndicator:member",
@@ -16544,6 +16608,132 @@
           ],
           "extendsTokenRanges": []
         },
+        {
+          "kind": "Interface",
+          "canonicalReference": "@genesislcap/ai-assistant!SettingsBudgetRow:interface",
+          "docComment": "/**\n * One rendered row of the settings-modal budget meter (GENC-1464) — a vendor that currently has budget figures, pre-formatted so the template stays a pure binding layer (and so tests can pin the exact text a user reads).\n *\n * @beta\n */\n",
+          "excerptTokens": [
+            {
+              "kind": "Content",
+              "text": "export interface SettingsBudgetRow "
+            }
+          ],
+          "fileUrlPath": "src/main/main.types.ts",
+          "releaseTag": "Beta",
+          "name": "SettingsBudgetRow",
+          "preserveMemberOrder": false,
+          "members": [
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!SettingsBudgetRow#barValue:member",
+              "docComment": "/**\n * The bar's value, clamped to `0..100` — a progress bar past its end renders nonsense, so only the bar clamps (mirroring the context-usage indicator's `Math.min(100, …)`).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "barValue: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "number"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "barValue",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!SettingsBudgetRow#figures:member",
+              "docComment": "/**\n * The real figures — `$45.00 / $50.00 (90%)`. The percentage is NOT clamped: spend can genuinely overshoot the cap (the last allowed call may cross it), and the text tells the truth about it.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "figures: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "figures",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!SettingsBudgetRow#label:member",
+              "docComment": "/**\n * Display name from `VENDOR_LABELS`, e.g. `Anthropic`.\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "label: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "label",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            },
+            {
+              "kind": "PropertySignature",
+              "canonicalReference": "@genesislcap/ai-assistant!SettingsBudgetRow#vendor:member",
+              "docComment": "/**\n * The vendor the row describes (an `AIProviderType` member).\n */\n",
+              "excerptTokens": [
+                {
+                  "kind": "Content",
+                  "text": "vendor: "
+                },
+                {
+                  "kind": "Content",
+                  "text": "string"
+                },
+                {
+                  "kind": "Content",
+                  "text": ";"
+                }
+              ],
+              "isReadonly": false,
+              "isOptional": false,
+              "releaseTag": "Beta",
+              "name": "vendor",
+              "propertyTypeTokenRange": {
+                "startIndex": 1,
+                "endIndex": 2
+              }
+            }
+          ],
+          "extendsTokenRanges": []
+        },
         {
           "kind": "Variable",
           "canonicalReference": "@genesislcap/ai-assistant!sparkleIconSvg:var",

package/dist/ai-assistant.d.ts

@@ -1143,6 +1143,21 @@ declare type BudgetDetail = NonNullable<Extract<ChatDriverResult, {
     reason: 'done';
 }>['budget']>;
 
+/**
+ * Whole-number percentage of a budget consumed, for the meter (GENC-1464).
+ *
+ * Deliberately unclamped — spend can genuinely overshoot the cap (the last
+ * allowed call may cross it), and the meter's TEXT shows the truth; only the
+ * bar clamps, at the render site. The one special case is a `$0` cap, which the
+ * platform treats as "no spend allowed" (not "unlimited"): it has no headroom
+ * by definition, so the meter reads full rather than dividing by zero.
+ *
+ * Exported for the unit test that pins the arithmetic; not element API.
+ *
+ * @internal
+ */
+export declare function budgetPercentOf(figures: VendorBudgetFigures): number;
+
 export { CachePolicy }
 
 /**
@@ -2555,6 +2570,75 @@ export declare class FoundationAiAssistant extends GenesisElement {
      * @beta
      */
     setVendorBlocked(vendor: AIProviderType, blocked: boolean, reason?: string | null): void;
+    /**
+     * One warning per element for garbage fed to
+     * {@link FoundationAiAssistant.setVendorBudget}. Once, not per call, because
+     * the documented feed re-runs after every turn — a host bug would otherwise
+     * repeat the same warning on every send for the life of the page.
+     */
+    private vendorBudgetWarningIssued;
+    private warnVendorBudgetOnce;
+    /**
+     * Feed (or clear) one vendor's AI-spend figures for the settings-modal budget
+     * meter — the numeric companion to
+     * {@link FoundationAiAssistant.setVendorBlocked}, and like it a host-driven
+     * write: the element meters nothing itself.
+     *
+     * The meter renders a row for exactly the vendors that currently HAVE
+     * figures. An **unlimited** vendor (the budget endpoint reports
+     * `unlimited: true` / `limitUsd: null`) is expressed by never feeding it —
+     * there is deliberately no "unlimited" figure shape, because a bar with no
+     * cap has nothing truthful to fill to. `spentUsd` MAY exceed `budgetUsd`
+     * (the last allowed call can overshoot the cap): the row's text shows the
+     * real figures and only the bar clamps.
+     *
+     * Returns `false` — and warns once, not per call — instead of throwing when
+     * `vendor` is not a budgeted vendor (`BUDGETED_VENDORS`, the proxy's own
+     * metered list) or either figure is not a finite number `>= 0`. Invalid input
+     * changes no state. Idempotent: re-feeding a vendor's current figures is a
+     * no-op, so hosts can re-feed unconditionally after every turn.
+     *
+     * `false` ALSO means "not stored, because the element is not ready yet": a
+     * feed that lands before the element has its session store (a host calling
+     * ahead of the first append, or during a pop-out remount) stores nothing and
+     * says so, rather than reporting a write that never happened. That case is
+     * transient and needs no host handling — the documented per-turn re-feed is
+     * what recovers it — so it is deliberately NOT warned about; the warn-once
+     * channel is for garbage input only.
+     *
+     * `figures` is nullish-checked at run time, so `undefined` behaves exactly
+     * like `null` and CLEARS that vendor's row. Untyped JS hosts feed this
+     * straight from `GET /api/budget`, where a per-vendor lookup that misses
+     * yields `undefined`, not `null` — and "no figures" coherently means "no
+     * row". The `| null` parameter type is unchanged for typed callers; the
+     * runtime is deliberately the more forgiving of the two.
+     *
+     * The intended feed is the platform budget endpoint:
+     *
+     * ```ts
+     * // `vendors` is an OBJECT keyed by vendor id, not an array.
+     * const { vendors } = await (await fetch('/api/budget')).json();
+     * for (const v of Object.values(vendors)) {
+     *   if (v.unlimited || v.limitUsd == null) {
+     *     assistantEl.setVendorBudget(v.vendor, null); // clear stale figures after a cap is lifted
+     *     continue;
+     *   }
+     *   assistantEl.setVendorBudget(v.vendor, { budgetUsd: v.limitUsd, spentUsd: v.spentUsd });
+     * }
+     * ```
+     *
+     * Re-run it on mount and after each turn. Scope and lifetime follow the rest
+     * of the session slice (per `stateKey`, survives pop-in/out and "Clear" /
+     * "New chat") — except that the figures are NOT persisted to the session
+     * snapshot: the server is authoritative and the host re-feeds at boot, so a
+     * persisted copy could only show stale dollars after a reload.
+     *
+     * @beta
+     */
+    setVendorBudget(vendor: string, figures: {
+        budgetUsd: number;
+        spentUsd: number;
+    } | null): boolean;
     /** Whether this vendor's wall came from the sweep alone — see the slice's `sweptVendors`. */
     private isVendorSwept;
     /**
@@ -3448,10 +3532,37 @@ export declare class FoundationAiAssistant extends GenesisElement {
     }): boolean;
     /** Whether the picker toggle button should appear. Mirrors the picker's own visibility rule. */
     get agentPickerEnabled(): boolean;
-    /** Whether the settings modal AI Model section has slotted app content or context usage. */
+    /** Whether the settings modal AI Model section has slotted app content, context usage or budget figures. */
     get settingsModelSectionVisible(): boolean;
     /** Built-in context window indicator (generic platform concern). */
     get settingsContextUsageVisible(): boolean;
+    /**
+     * Built-in per-vendor budget meter (GENC-1464) — the money sibling of
+     * {@link FoundationAiAssistant.settingsContextUsageVisible}, with the same
+     * shape of gate: not configured off, and there is data to show. "Data" here
+     * is "at least one vendor has figures", so a host that feeds nothing (or only
+     * unlimited vendors) gets no meter and no empty container — exactly the
+     * context indicator's absent case.
+     *
+     * Answered from the RAW slice state rather than from
+     * {@link FoundationAiAssistant.settingsBudgetRows}, whose `.length` would
+     * format every row (a `formatUsd` pair and a `budgetPercentOf` each) only to
+     * ask whether any exist. This is read several times per render pass — the
+     * getter, the section gate, the template's `when` — so it stays as cheap as
+     * the context sibling's `!= null`.
+     *
+     * @internal
+     */
+    get settingsBudgetUsageVisible(): boolean;
+    /**
+     * The meter's rows — one per vendor that currently has figures, in
+     * `BUDGETED_VENDORS` order (the proxy's own metered list) so the rendering is
+     * stable however the host ordered its feed calls. Pre-formatted; see
+     * {@link SettingsBudgetRow} for why the text is unclamped while the bar is.
+     *
+     * @internal
+     */
+    get settingsBudgetRows(): readonly SettingsBudgetRow[];
     /** Whether the settings modal UI Builder section should render. */
     get settingsAppSectionVisible(): boolean;
     /** App toggles currently visible per each entry's `visible()` predicate. */
@@ -4356,6 +4467,32 @@ export declare interface SessionPreferences {
     animations?: string[];
 }
 
+/**
+ * One rendered row of the settings-modal budget meter (GENC-1464) — a vendor
+ * that currently has budget figures, pre-formatted so the template stays a pure
+ * binding layer (and so tests can pin the exact text a user reads).
+ *
+ * @beta
+ */
+export declare interface SettingsBudgetRow {
+    /** The vendor the row describes (an `AIProviderType` member). */
+    vendor: string;
+    /** Display name from `VENDOR_LABELS`, e.g. `Anthropic`. */
+    label: string;
+    /**
+     * The real figures — `$45.00 / $50.00 (90%)`. The percentage is NOT clamped:
+     * spend can genuinely overshoot the cap (the last allowed call may cross it),
+     * and the text tells the truth about it.
+     */
+    figures: string;
+    /**
+     * The bar's value, clamped to `0..100` — a progress bar past its end renders
+     * nonsense, so only the bar clamps (mirroring the context-usage indicator's
+     * `Math.min(100, …)`).
+     */
+    barValue: number;
+}
+
 /**
  * Tab identifiers for the modal tab bar.
  *
@@ -4924,6 +5061,23 @@ export declare type UnresolvedToolInput = (ctx: UnresolvedToolContext) => string
 /** Person silhouette — default user avatar. */
 export declare const userIconSvg = "<svg viewBox=\"0 0 24 24\" fill=\"none\" xmlns=\"http://www.w3.org/2000/svg\"><path d=\"M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z\" fill=\"currentColor\"/></svg>";
 
+/**
+ * One vendor's AI-spend figures, as fed by the host from the budget endpoint
+ * (GENC-1464 — the settings-modal budget meter).
+ *
+ * Dollars, not a percentage: the meter's text shows the real figures (spend CAN
+ * exceed the cap — the last allowed call may overshoot it), and only the bar
+ * clamps. Storing a pre-computed percentage would destroy the overshoot.
+ *
+ * @beta
+ */
+declare interface VendorBudgetFigures {
+    /** The vendor's budget cap in USD. Finite and `>= 0`. */
+    budgetUsd: number;
+    /** Metered spend against that cap in USD. Finite and `>= 0`; may exceed the cap. */
+    spentUsd: number;
+}
+
 /**
  * A {@link SessionPersistenceProvider} backed by a Web Storage area. Both
  * `window.sessionStorage` and `window.localStorage` implement the `Storage`