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

package/dist/esm/main/budget-meter.test.js

@@ -0,0 +1,317 @@
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import { clearAllSessionStores, getSessionStore } from '../state/session-store';
+import { logger } from '../utils/logger';
+import { budgetPercentOf, FoundationAiAssistant } from './main';
+// Hold a reference so the custom-element registration isn't tree-shaken.
+FoundationAiAssistant;
+// GENC-1464 — the settings-modal per-vendor budget meter.
+//
+// Like `blocked-state.test.ts`, this pins the GETTER LOGIC the template bindings
+// depend on rather than the rendered DOM, and for the same reason: mounting the
+// assistant runs `connectedCallback`, which subscribes to `agenticActivityBus`
+// and leaves the runner's event loop open. `document.createElement` only
+// upgrades the element — it does not connect — so nothing subscribes here.
+//
+// The bindings under test in `settings-modal.template.ts` are:
+//   ${when((x) => x.settingsBudgetUsageVisible, …)}          (the whole meter)
+//   ${repeat((x) => x.settingsBudgetRows, …)}                (one row per vendor)
+//   <…-progress value="${(row) => row.barValue}">            (the clamped bar)
+// plus `settingsModelSectionVisible`, which decides whether the "AI Model
+// Settings" section renders at all.
+const Suite = createLogicSuite('FoundationAiAssistant budget meter');
+let storeSeq = 0;
+/** A fresh (unconnected) element wired to its own real session store. */
+function element() {
+    const el = document.createElement('foundation-ai-assistant');
+    storeSeq += 1;
+    el._sessionRef = getSessionStore(`budget-meter-test-${storeSeq}`, false);
+    return el;
+}
+/** The raw stored figures, read the way the rows getter reads them. */
+const storedBudgets = (el) => el._sessionRef.store.aiAssistant
+    .vendorBudgets;
+/** The store half of "Clear" / "New chat" — see blocked-state.test.ts. */
+const resetSession = (el) => el._sessionRef.actions.aiAssistant.resetSession();
+/** Count `logger.warn` calls during `run` — the boundary warns ONCE per element. */
+const countWarns = (run) => {
+    const original = logger.warn;
+    let calls = 0;
+    logger.warn = ((...args) => {
+        calls += 1;
+        void args;
+    });
+    try {
+        run();
+    }
+    finally {
+        logger.warn = original;
+    }
+    return calls;
+};
+/**
+ * Count reads of `settingsBudgetRows` during `run`.
+ *
+ * Building the rows formats every vendor's money text — a `formatUsd` pair and
+ * a `budgetPercentOf` each — so a gate that answers THROUGH the rows pays for
+ * all of it. Counting reads of the getter is the direct probe of that; the spy
+ * goes on the prototype (where the accessor lives) and is put back after.
+ */
+const countRowBuilds = (run) => {
+    const proto = FoundationAiAssistant.prototype;
+    const original = Object.getOwnPropertyDescriptor(proto, 'settingsBudgetRows');
+    let calls = 0;
+    Object.defineProperty(proto, 'settingsBudgetRows', Object.assign(Object.assign({}, original), { get() {
+            calls += 1;
+            return original.get.call(this);
+        } }));
+    try {
+        run();
+    }
+    finally {
+        Object.defineProperty(proto, 'settingsBudgetRows', original);
+    }
+    return calls;
+};
+Suite.after(() => {
+    clearAllSessionStores();
+});
+// ── Feeding figures ─────────────────────────────────────────────────────────
+Suite('feeding two vendors renders two rows with the real money text', () => {
+    const el = element();
+    assert.is(el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 45 }), true);
+    assert.is(el.setVendorBudget('gemini', { budgetUsd: 200, spentUsd: 30.5 }), true);
+    const rows = el.settingsBudgetRows;
+    assert.is(rows.length, 2);
+    assert.is(rows[0].vendor, 'anthropic');
+    assert.is(rows[0].label, 'Anthropic', 'display name comes from VENDOR_LABELS');
+    assert.is(rows[0].figures, '$45.00 / $50.00 (90%)');
+    assert.is(rows[0].barValue, 90);
+    assert.is(rows[1].vendor, 'gemini');
+    assert.is(rows[1].figures, '$30.50 / $200.00 (15%)', 'two decimals always, percent rounded');
+});
+Suite('rows keep BUDGETED_VENDORS order however the host ordered its feed', () => {
+    // The feed loops over a server response whose order is the server's business;
+    // the meter must not reorder itself between turns because of it.
+    const el = element();
+    el.setVendorBudget('gemini', { budgetUsd: 10, spentUsd: 1 });
+    el.setVendorBudget('anthropic', { budgetUsd: 10, spentUsd: 2 });
+    assert.equal(el.settingsBudgetRows.map((r) => r.vendor), ['anthropic', 'gemini']);
+});
+Suite('a vendor with no figures gets no row — that is how "unlimited" renders', () => {
+    // Display rule: hosts simply do not feed a vendor the server marks
+    // `unlimited: true` / `limitUsd: null`, and the meter shows only what it was
+    // fed. No "∞" row, no empty bar.
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 15 });
+    const rows = el.settingsBudgetRows;
+    assert.is(rows.length, 1);
+    assert.is(rows[0].vendor, 'anthropic');
+});
+// ── Overshoot: the text tells the truth, the bar clamps ─────────────────────
+Suite('spend past the cap shows the real figures but clamps the bar at 100', () => {
+    // Real overshoot exists — the last allowed call can cross the cap (the demo
+    // "Exhaust" lands at $62.34 of $50 on purpose). A bar past its end renders
+    // nonsense, so only the bar clamps.
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 62.34 });
+    const [row] = el.settingsBudgetRows;
+    assert.is(row.figures, '$62.34 / $50.00 (125%)', 'the text is the truth, unclamped');
+    assert.is(row.barValue, 100, 'the bar is full, not broken');
+});
+Suite('a $0 cap reads as a full meter, not a division by zero', () => {
+    // The platform treats a $0 budget as "no spend allowed" (not "unlimited"), so
+    // it has no headroom by definition.
+    assert.is(budgetPercentOf({ budgetUsd: 0, spentUsd: 0 }), 100);
+    assert.is(budgetPercentOf({ budgetUsd: 0, spentUsd: 3 }), 100);
+    const el = element();
+    el.setVendorBudget('gemini', { budgetUsd: 0, spentUsd: 0 });
+    assert.is(el.settingsBudgetRows[0].figures, '$0.00 / $0.00 (100%)');
+    assert.is(el.settingsBudgetRows[0].barValue, 100);
+});
+// ── Clearing ────────────────────────────────────────────────────────────────
+Suite('setVendorBudget(vendor, null) clears that row and only that row', () => {
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 45 });
+    el.setVendorBudget('gemini', { budgetUsd: 50, spentUsd: 15 });
+    assert.is(el.setVendorBudget('anthropic', null), true);
+    assert.equal(el.settingsBudgetRows.map((r) => r.vendor), ['gemini']);
+});
+Suite('clearing a vendor that has no figures is a true no-op', () => {
+    const el = element();
+    assert.is(el.setVendorBudget('anthropic', null), true, 'clearing nothing is not an error');
+    assert.is(el.settingsBudgetRows.length, 0);
+});
+Suite("undefined clears too — an untyped host's missing lookup is not a crash", () => {
+    // The `| null` parameter type is for typed callers; the runtime is more
+    // forgiving on purpose. Untyped JS hosts feed this straight from
+    // GET /api/budget, where a per-vendor lookup that MISSES yields `undefined`,
+    // not `null` — and a boundary whose whole contract is "return false, never
+    // throw" must not TypeError on it. "No figures" means "no row", either way.
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 45 });
+    el.setVendorBudget('gemini', { budgetUsd: 50, spentUsd: 15 });
+    const warns = countWarns(() => {
+        assert.is(el.setVendorBudget('anthropic', undefined), true, 'accepted, not refused');
+    });
+    assert.is(warns, 0, 'a missing lookup is not garbage input — nothing to warn about');
+    assert.equal(el.settingsBudgetRows.map((r) => r.vendor), ['gemini'], 'it cleared that vendor and only that vendor, exactly as null does');
+});
+// ── Invalid input: false + warn once, never a throw, never a write ──────────
+Suite('an unbudgeted vendor is refused with false and no state change', () => {
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 15 });
+    // 'none' is the no-provider sentinel; 'chrome' is on-device (no pot to
+    // meter); 'openai' is refused by the proxy up front — none can carry figures.
+    for (const vendor of ['none', 'chrome', 'openai', 'acme-ai']) {
+        assert.is(el.setVendorBudget(vendor, { budgetUsd: 1, spentUsd: 0 }), false, vendor);
+    }
+    assert.equal(el.settingsBudgetRows.map((r) => r.vendor), ['anthropic'], 'nothing was stored for any of them');
+});
+Suite('non-finite or negative figures are refused with false and no state change', () => {
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 15 });
+    const bad = [
+        { budgetUsd: NaN, spentUsd: 1 },
+        { budgetUsd: 1, spentUsd: NaN },
+        { budgetUsd: Infinity, spentUsd: 1 },
+        { budgetUsd: 1, spentUsd: -0.01 },
+        { budgetUsd: -50, spentUsd: 1 },
+        // The endpoint's `limitUsd: null` (unlimited) must be dropped by the host,
+        // not forwarded; forwarded anyway, it is garbage, not a clear.
+        { budgetUsd: null, spentUsd: 1 },
+    ];
+    for (const figures of bad) {
+        assert.is(el.setVendorBudget('anthropic', figures), false, JSON.stringify(figures));
+    }
+    assert.is(el.settingsBudgetRows[0].figures, '$15.00 / $50.00 (30%)', 'the good figures survive');
+});
+Suite('garbage warns once per element, not once per call', () => {
+    // The documented feed re-runs after every turn, so a host bug would repeat
+    // the same warning on every send for the life of the page.
+    const el = element();
+    const warns = countWarns(() => {
+        assert.is(el.setVendorBudget('openai', { budgetUsd: 1, spentUsd: 0 }), false);
+        assert.is(el.setVendorBudget('openai', { budgetUsd: 1, spentUsd: 0 }), false);
+        assert.is(el.setVendorBudget('anthropic', { budgetUsd: NaN, spentUsd: 0 }), false);
+    });
+    assert.is(warns, 1, 'one warning covers the whole broken feed');
+});
+// ── Not ready yet: the other reason a feed is refused ───────────────────────
+Suite('a feed before the element has a session store is refused, not silently dropped', () => {
+    // The lifecycle window: a host feeding ahead of the first append, or during a
+    // pop-out remount, has no store to write to. The dispatch no-ops there, so
+    // returning true reported a write that never happened and the caller — which
+    // reads the boolean as "accepted" — would never retry.
+    const el = document.createElement('foundation-ai-assistant');
+    const warns = countWarns(() => {
+        assert.is(el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 45 }), false);
+    });
+    assert.is(warns, 0, 'a lifecycle window is not bad input — the warn-once channel is for garbage');
+    assert.is(el.settingsBudgetRows.length, 0, 'nothing was stored');
+    assert.is(el.settingsBudgetUsageVisible, false, 'and nothing is shown');
+    // The recovery is the documented per-turn re-feed, which lands as soon as the
+    // store exists — the connected path is unchanged.
+    const ready = element();
+    assert.is(ready.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 45 }), true);
+    assert.is(ready.settingsBudgetRows.length, 1);
+});
+// ── Idempotence ─────────────────────────────────────────────────────────────
+Suite('re-feeding identical figures leaves the stored object untouched', () => {
+    // The feed re-runs unconditionally after every turn; identical dollars must
+    // not publish a new store reference (and re-render an unchanged meter).
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 15 });
+    const before = storedBudgets(el).anthropic;
+    assert.is(el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 15 }), true);
+    assert.is(storedBudgets(el).anthropic, before, 'same dollars, same object');
+});
+Suite('the store keeps its own copy, not the host object', () => {
+    // The store must not adopt an object the host still owns: immer finalizes
+    // whatever the reducer assigns into the draft and FREEZES it — so adoption
+    // would freeze state the host believes is its own, turning the host's next
+    // `figures.spentUsd += x` into a strict-mode TypeError (or a silent no-op).
+    // The frozen-ness probe is the observable that catches adoption directly;
+    // the mutation-isolation assertion is the user-visible consequence.
+    const el = element();
+    const hostFigures = { budgetUsd: 50, spentUsd: 15 };
+    el.setVendorBudget('anthropic', hostFigures);
+    assert.is(Object.isFrozen(hostFigures), false, 'the host object was not adopted-and-frozen');
+    hostFigures.spentUsd = 999;
+    assert.is(el.settingsBudgetRows[0].figures, '$15.00 / $50.00 (30%)');
+});
+// ── Lifetime ────────────────────────────────────────────────────────────────
+Suite('the figures survive "Clear" / "New chat" — budget is not conversation state', () => {
+    // Same side of the resetSession preserve-list as the blocked latch: a new
+    // chat refills no budget, so wiping the meter would blank real dollars until
+    // the host's next re-feed. Opposite side from contextTokens, which IS
+    // conversation state (a fresh chat genuinely has an empty context window).
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 45 });
+    el.messages = [{ id: '1', role: 'user', content: 'hello' }];
+    resetSession(el);
+    assert.is(el.messages.length, 0, 'the transcript is gone');
+    assert.is(el.contextTokens, undefined, 'context usage reset with the conversation');
+    assert.is(el.settingsBudgetRows[0].figures, '$45.00 / $50.00 (90%)', 'the meter is not');
+});
+Suite('the figures are per session store — a different stateKey starts empty', () => {
+    const first = element();
+    const second = element();
+    first.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 45 });
+    assert.is(first.settingsBudgetRows.length, 1);
+    assert.is(second.settingsBudgetRows.length, 0, 'a different session store is unaffected');
+});
+// ── Visibility ──────────────────────────────────────────────────────────────
+Suite('showBudgetUsage: false hides the meter even with figures fed', () => {
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 45 });
+    assert.is(el.settingsBudgetUsageVisible, true, 'default ON — undefined shows');
+    el.chatConfig = { ui: { showBudgetUsage: false } };
+    assert.is(el.settingsBudgetUsageVisible, false);
+    assert.is(el.settingsBudgetRows.length, 1, 'the state itself is kept, only the render is off');
+    el.chatConfig = { ui: { showBudgetUsage: true } };
+    assert.is(el.settingsBudgetUsageVisible, true, 'explicit true shows too');
+});
+Suite('no figures → the meter behaves like the context indicator with no data', () => {
+    // The absent case mirrors settingsContextUsageVisible exactly: nothing to
+    // show means no meter AND no "AI Model Settings" section on its account.
+    const el = element();
+    assert.is(el.settingsContextUsageVisible, false, 'the sibling gate this one mirrors');
+    assert.is(el.settingsBudgetUsageVisible, false);
+    assert.is(el.settingsModelSectionVisible, false, 'no slot content, no data — no section');
+});
+Suite('clearing the last vendor takes the meter back out of view', () => {
+    // The gate reads the RAW slice state rather than counting formatted rows, so
+    // this is the case that keeps the two readings honest: a vendor that was fed
+    // and then cleared must leave NO trace the gate could mistake for data.
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 45 });
+    assert.is(el.settingsBudgetUsageVisible, true);
+    el.setVendorBudget('anthropic', null);
+    assert.is(el.settingsBudgetUsageVisible, false, 'cleared is invisible, not an empty meter');
+    assert.is(el.settingsBudgetRows.length, 0, 'the rows agree');
+    assert.is(el.settingsModelSectionVisible, false, 'and the section goes with it');
+});
+Suite('the visibility gate answers without building a single row', () => {
+    // The gate is read several times per render pass — this getter, the section
+    // gate, the template's `when` — and answering it through
+    // `settingsBudgetRows.length` formatted every vendor's money text each time
+    // just to ask whether any rows exist. It reads the raw slice state instead;
+    // the context sibling it mirrors gates on a bare `!= null` for the same
+    // reason. The rendering path still builds rows, of course — the control below.
+    const el = element();
+    el.setVendorBudget('anthropic', { budgetUsd: 50, spentUsd: 45 });
+    el.setVendorBudget('gemini', { budgetUsd: 200, spentUsd: 30.5 });
+    assert.is(countRowBuilds(() => void el.settingsBudgetUsageVisible), 0, 'the gate builds nothing');
+    assert.is(countRowBuilds(() => void el.settingsBudgetRows), 1, 'the rendering path does (the control that the probe can see a read at all)');
+});
+Suite('figures alone are enough to surface the AI Model Settings section', () => {
+    // The wiring into settingsModelSectionVisible, the same way
+    // settingsContextUsageVisible is wired in.
+    const el = element();
+    assert.is(el.settingsModelSectionVisible, false);
+    el.setVendorBudget('gemini', { budgetUsd: 50, spentUsd: 15 });
+    assert.is(el.settingsModelSectionVisible, true);
+    el.chatConfig = { ui: { showBudgetUsage: false } };
+    assert.is(el.settingsModelSectionVisible, false, 'and the config flag takes it back out');
+});
+Suite.run();

package/dist/esm/main/main.js

@@ -57,6 +57,7 @@ import { deleteBankedBaseline, getBankedBaseline, setBankedBaseline, } from '../
 import { collectSessionModels } from '../utils/collect-session-models';
 import { clearCostSessionHistory, isCostSessionRecord, loadCostSessionHistory, resolveBankedUsage, saveCostSessionHistory, sortRecordsByRecency, upsertRecord, } from '../utils/cost-session-history';
 import { deriveCostSessionTitleFromMessages, resolveCostSessionTitle, } from '../utils/derive-cost-session-title';
+import { formatUsd } from '../utils/format-usd';
 import { logger } from '../utils/logger';
 import { filterVisibleMessages, trailingInteractionRow } from '../utils/message-partition';
 import { resolveCostHistoryConfig, } from '../utils/resolve-cost-history-config';
@@ -143,7 +144,7 @@ const RAISE_LIMITS_ACTION = 'Contact your administrator to raise them.';
 export function formatBlockedReason(budget, vendor) {
     if (!budget || (budget.budgetUsd == null && budget.spentUsd == null))
         return undefined;
-    const money = (v) => (v == null ? 'an unknown amount' : `$${v.toFixed(2)}`);
+    const money = (v) => (v == null ? 'an unknown amount' : formatUsd(v));
     const figures = `(${money(budget.spentUsd)} of ${money(budget.budgetUsd)})`;
     // A per-vendor statement carries NO action clause, because the right action is
     // not knowable at latch time: whether "switch vendor" or "contact your
@@ -189,6 +190,24 @@ function formatVendorList(vendors) {
         return (_a = names[0]) !== null && _a !== void 0 ? _a : '';
     return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
 }
+/**
+ * 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 function budgetPercentOf(figures) {
+    if (figures.budgetUsd <= 0)
+        return 100;
+    return Math.round((figures.spentUsd / figures.budgetUsd) * 100);
+}
 // Register supporting components when the main component module is imported.
 avoidTreeShaking(AiChatMarkdown, AiChatInteractionWrapper, AiHaloOverlay, AiWavesIndicator, AiFlowingWavesIndicator, AiPlasmaOrbIndicator, AiChatBubble, AiActivityHalo, ChatSuggestions, AgentPicker);
 /**
@@ -239,6 +258,13 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         this.persistence = {};
         /** When set, enables Redux DevTools for this instance's session store. */
         this.debugRedux = false;
+        /**
+         * 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.
+         */
+        this.vendorBudgetWarningIssued = false;
         // ---- Transient UI state (stays as @observable on the component) ----
         this._suggestionsGeneration = 0;
         this.attachments = [];
@@ -862,6 +888,102 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         }
         (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setVendorBlocked({ vendor, blocked, reason });
     }
+    warnVendorBudgetOnce(message) {
+        if (this.vendorBudgetWarningIssued)
+            return;
+        this.vendorBudgetWarningIssued = true;
+        logger.warn(`FoundationAiAssistant.setVendorBudget: ${message}`);
+    }
+    /**
+     * 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, figures) {
+        if (!BUDGETED_VENDORS.includes(vendor)) {
+            this.warnVendorBudgetOnce(`'${vendor}' is not a budgeted vendor — ignoring. Only the proxy-metered vendors ` +
+                `(${BUDGETED_VENDORS.join(', ')}) can carry budget figures.`);
+            return false;
+        }
+        // Nullish, not `!== null`: an untyped host's missing lookup arrives as
+        // `undefined`, and dereferencing it here would throw at a boundary whose
+        // whole contract is to return false instead. `undefined` clears, like null.
+        if (figures != null) {
+            const validUsd = (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0;
+            if (!validUsd(figures.budgetUsd) || !validUsd(figures.spentUsd)) {
+                this.warnVendorBudgetOnce(`invalid figures for '${vendor}' — ignoring. budgetUsd and spentUsd must both be ` +
+                    `finite numbers >= 0 (got budgetUsd: ${figures.budgetUsd}, spentUsd: ${figures.spentUsd}).`);
+                return false;
+            }
+        }
+        const session = this._sessionRef;
+        // No store yet (fed before the first append, or mid pop-out remount): there
+        // is nowhere to write, so say so rather than returning an accepted the
+        // caller would never retry. Not warned — this is a lifecycle window, not
+        // bad input, and the documented per-turn re-feed lands the figures as soon
+        // as the store exists.
+        if (!session)
+            return false;
+        session.actions.aiAssistant.setVendorBudget({
+            vendor: vendor,
+            // A fresh literal, never the caller's object — see the reducer, which
+            // must not adopt (and potentially freeze) state the host still owns.
+            figures: figures == null ? null : { budgetUsd: figures.budgetUsd, spentUsd: figures.spentUsd },
+        });
+        return true;
+    }
     /** Whether this vendor's wall came from the sweep alone — see the slice's `sweptVendors`. */
     isVendorSwept(vendor) {
         var _a, _b;
@@ -3107,15 +3229,73 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             return false;
         return ((_c = this.agents) !== null && _c !== void 0 ? _c : []).some((a) => { var _a; return (_a = a.manualSelection) === null || _a === void 0 ? void 0 : _a.enabled; });
     }
-    /** 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() {
-        return this.settingsModelSlotted.length > 0 || this.settingsContextUsageVisible;
+        return (this.settingsModelSlotted.length > 0 ||
+            this.settingsContextUsageVisible ||
+            this.settingsBudgetUsageVisible);
     }
     /** Built-in context window indicator (generic platform concern). */
     get settingsContextUsageVisible() {
         const ui = this.chatConfig.ui;
         return ((ui === null || ui === void 0 ? void 0 : ui.showContextUsage) !== false && this.contextTokens != null && this.contextLimit != null);
     }
+    /**
+     * 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() {
+        var _a, _b;
+        const budgets = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.vendorBudgets;
+        return (((_b = this.chatConfig.ui) === null || _b === void 0 ? void 0 : _b.showBudgetUsage) !== false &&
+            budgets != null &&
+            // Keyed off BUDGETED_VENDORS, exactly as the rows are, so a key outside
+            // that list could never surface a meter with no row to show.
+            BUDGETED_VENDORS.some((vendor) => budgets[vendor] != null));
+    }
+    /**
+     * 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() {
+        var _a;
+        const budgets = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.vendorBudgets;
+        if (!budgets)
+            return [];
+        const rows = [];
+        for (const vendor of BUDGETED_VENDORS) {
+            const figures = budgets[vendor];
+            if (!figures)
+                continue;
+            const percent = budgetPercentOf(figures);
+            rows.push({
+                vendor,
+                label: vendorDisplayName(vendor),
+                figures: `${formatUsd(figures.spentUsd)} / ${formatUsd(figures.budgetUsd)} (${percent}%)`,
+                // The same clamp the context indicator applies to its bar. No lower
+                // clamp needed: the boundary refuses negative figures.
+                barValue: Math.min(100, percent),
+            });
+        }
+        return rows;
+    }
     /** Whether the settings modal UI Builder section should render. */
     get settingsAppSectionVisible() {
         return this.settingsAppSlotted.length > 0 || this.visibleAppSettingsToggles.length > 0;
@@ -4290,6 +4470,12 @@ __decorate([
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "settingsContextUsageVisible", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "settingsBudgetUsageVisible", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "settingsBudgetRows", null);
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "settingsAppSectionVisible", null);

package/dist/esm/state/ai-assistant-slice.js

@@ -34,6 +34,7 @@ export function createDefaultSessionState() {
         blockedVendors: [],
         sweptVendors: [],
         blockedVendorReasons: {},
+        vendorBudgets: {},
         inputValue: '',
         liveSubAgentTrace: [],
         liveSubAgentName: null,
@@ -203,6 +204,36 @@ export const aiAssistantSlice = createSlice({
                 delete state.blockedVendorReasons[vendor];
             }
         },
+        /**
+         * Store (or clear, with `null`) one vendor's budget figures for the meter.
+         *
+         * Validation lives at the element boundary (`setVendorBudget` on the
+         * element), not here — the reducer is the storage layer and trusts its one
+         * caller, exactly as `setVendorBlocked` above trusts its.
+         *
+         * Idempotent by VALUE, not just by effect: re-feeding the figures a vendor
+         * already holds leaves the stored object untouched. The documented feed
+         * re-runs after every turn, so without this every turn would publish a new
+         * store reference for the same dollars and re-render a meter that has not
+         * changed.
+         */
+        setVendorBudget(state, action) {
+            const { vendor, figures } = action.payload;
+            if (figures === null) {
+                delete state.vendorBudgets[vendor];
+                return;
+            }
+            const existing = state.vendorBudgets[vendor];
+            if (existing &&
+                existing.budgetUsd === figures.budgetUsd &&
+                existing.spentUsd === figures.spentUsd) {
+                return;
+            }
+            // A fresh object rather than the caller's: the store may freeze what it
+            // holds, and adopting the host's object would freeze state the host still
+            // owns (and let later host mutations bypass the store).
+            state.vendorBudgets[vendor] = { budgetUsd: figures.budgetUsd, spentUsd: figures.spentUsd };
+        },
         setInputValue(state, action) {
             state.inputValue = action.payload;
         },
@@ -298,6 +329,13 @@ export const aiAssistantSlice = createSlice({
                 blockedVendors: state.blockedVendors,
                 sweptVendors: state.sweptVendors,
                 blockedVendorReasons: state.blockedVendorReasons,
+                // Category 2, beside the blocked latch: the budget figures are a fact
+                // about the USER'S DEPLOYMENT (what the server meters), not about this
+                // conversation — "Clear" refills no budget, so wiping them would blank
+                // the meter until the host's next re-feed while the dollars are
+                // unchanged. Opposite side from `contextTokens`, which IS conversation
+                // state (a new chat genuinely has an empty context window).
+                vendorBudgets: state.vendorBudgets,
             };
             Object.assign(state, createDefaultSessionState(), preservedAcrossReset);
         },

package/dist/esm/utils/format-usd.js

@@ -0,0 +1,23 @@
+/**
+ * The ONE place this package renders a USD amount as text.
+ *
+ * Extracted (GENC-1464 budget meter) from the ad-hoc `.toFixed(2)` call sites
+ * that had grown in `formatBlockedReason` and the settings modal's cost blocks,
+ * so the blocked banner, the session-cost figures and the budget meter cannot
+ * drift to different precisions. Two decimals always — money columns jitter
+ * when "$5.1" sits above "$5.10".
+ *
+ * @internal
+ */
+/** Decimal places for every USD figure this package renders. */
+export const USD_DECIMALS = 2;
+/**
+ * The bare amount, no currency sign — `(12.3) => "12.30"`.
+ *
+ * Exists for the settings modal's cost blocks, where the `$` is a separately
+ * styled `<span class="prefix">` and folding it into the text would change the
+ * DOM those styles target.
+ */
+export const formatUsdAmount = (value) => value.toFixed(USD_DECIMALS);
+/** A signed USD figure — `(12.3) => "$12.30"`. */
+export const formatUsd = (value) => `$${formatUsdAmount(value)}`;