@genesislcap/ai-assistant 15.3.2 → 15.3.3-alpha-4899ddd.0

package/dist/esm/main/main.js

@@ -22,7 +22,7 @@
 // =============================================================================
 var FoundationAiAssistant_1;
 import { __awaiter, __decorate, __rest } from "tslib";
-import { AIProviderRegistry, isObservableAIProviderRegistry } from '@genesislcap/foundation-ai';
+import { AIProviderRegistry, BUDGETED_VENDORS, DEFAULT_BUDGET_EXHAUSTED_MESSAGE, isObservableAIProviderRegistry, VENDOR_LABELS, vendorTypeOfLabel, } from '@genesislcap/foundation-ai';
 import { showNotificationDialog } from '@genesislcap/foundation-notifications';
 import { avoidTreeShaking } from '@genesislcap/foundation-utils';
 import { customElement, DOM, html, GenesisElement, observable, volatile, attr, } from '@genesislcap/web-core';
@@ -104,6 +104,84 @@ const COMPOSER_MIN_HEIGHT_PX = 48;
 const COMPOSER_MAX_HEIGHT_PX = 400;
 /** Keep at least this much of the message list visible while growing the composer. */
 const COMPOSER_MIN_MESSAGES_PX = 80;
+/**
+ * Composer placeholder while the assistant is blocked (GENC-1464). Deliberately
+ * fixed and short, and NOT host-overridable — the banner directly above it
+ * carries the detail, and that one IS overridable via `setBlocked(true, reason)`.
+ * The banner's own default copy is `DEFAULT_BUDGET_EXHAUSTED_MESSAGE`, read
+ * straight from `foundation-ai` so the banner and the driver's transcript bubble
+ * cannot drift apart.
+ */
+const BLOCKED_PLACEHOLDER = 'AI usage limit reached';
+/**
+ * Closing sentence for a wall the user cannot route around. Singular/plural
+ * variants because the banner names one vendor or several.
+ */
+const RAISE_LIMIT_ACTION = 'Contact your administrator to raise it.';
+const RAISE_LIMITS_ACTION = 'Contact your administrator to raise them.';
+/**
+ * Banner copy built from the figures a 402 actually reported, or `undefined`
+ * when the proxy sent none.
+ *
+ * `undefined` is the meaningful return, not a fallback: paired with the
+ * slice's "a re-latch without a reason keeps the existing explanation" rule, it
+ * makes a figureless driver latch leave a host-supplied reason intact rather
+ * than blanking it back to the default at the exact moment the wall is hit.
+ *
+ * Exported for the unit test that pins the formatting; not part of the element
+ * API.
+ *
+ * @internal
+ */
+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 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
+    // administrator" is the honest advice depends on whether any OTHER vendor still
+    // has headroom, which only the composing getter can see. The vendor-agnostic
+    // form keeps its historical trailing sentence — nothing composes onto it.
+    return vendor
+        ? `${vendorDisplayName(vendor)}'s AI usage limit is reached ${figures}.`
+        : `AI usage limit reached ${figures}. Contact your administrator to raise it.`;
+}
+/**
+ * Human-readable name for a vendor, falling back to its raw type.
+ *
+ * `'none'` needs no special case: it is the "no provider configured" sentinel,
+ * it is filtered out of {@link FoundationAiAssistant.reachableVendors}, the latch
+ * refuses to attribute a wall to it, and
+ * {@link FoundationAiAssistant.setVendorBlocked} rejects it at the boundary — so
+ * nothing can put it in front of this function. The `?? vendor` fallback is for a
+ * vendor type added to `AIProviderType` without a label, which would print the
+ * type rather than nothing.
+ */
+function vendorDisplayName(vendor) {
+    var _a;
+    return (_a = VENDOR_LABELS[vendor]) !== null && _a !== void 0 ? _a : vendor;
+}
+/**
+ * `a`, `a and b`, `a, b and c`.
+ *
+ * The general joiner is kept rather than hardcoded to a pair because the list
+ * is `BUDGETED_VENDORS`-shaped, and that list is a cross-repo contract owned by
+ * the proxy (today `anthropic` and `gemini`; `openai` is refused up front with
+ * 400 UNSUPPORTED_PROVIDER and can never be walled) — a vendor added there must
+ * not require an edit here. Its upper bound is not an assertion in a comment — it is
+ * the key count of `VENDOR_LABELS`, since every element of every list passed here
+ * comes from `blockedVendors` or `reachableVendors`, both of which hold
+ * `AIProviderType` values, and the type has five members of which `'none'` is
+ * excluded from both.
+ */
+function formatVendorList(vendors) {
+    var _a;
+    const names = vendors.map(vendorDisplayName);
+    if (names.length <= 1)
+        return (_a = names[0]) !== null && _a !== void 0 ? _a : '';
+    return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+}
 // Register supporting components when the main component module is imported.
 avoidTreeShaking(AiChatMarkdown, AiChatInteractionWrapper, AiHaloOverlay, AiWavesIndicator, AiFlowingWavesIndicator, AiPlasmaOrbIndicator, AiChatBubble, AiActivityHalo, ChatSuggestions, AgentPicker);
 /**
@@ -367,14 +445,25 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
     }
     /**
      * True when a new send must be refused: a turn is running (`busy`), a page-reload
-     * restore is loading history that would clobber it (`restoring`), or a manual
-     * compaction is rewriting history (`compacting`). Mirrors the composer's
-     * `?disabled` gate so a **programmatic** `send`/`submitMessage` (e.g. a host's
-     * custom input while the built-in composer is hidden) can't slip past it and have
-     * its message wiped when the restored/compacted history lands (GENC-1351 §6).
+     * restore is loading history that would clobber it (`restoring`), a manual
+     * compaction is rewriting history (`compacting`), or a backend condition has
+     * locked the assistant outright (`blocked` — e.g. an exhausted AI budget).
+     * Mirrors the composer's `?disabled` gate so a **programmatic**
+     * `send`/`submitMessage` (e.g. a host's custom input while the built-in composer
+     * is hidden) can't slip past it and have its message wiped when the
+     * restored/compacted history lands (GENC-1351 §6).
      */
     get sendBlocked() {
-        return this.busy || this.restoring || this.compacting;
+        return this.busy || this.restoring || this.compacting || this.blocked;
+    }
+    /**
+     * Why a programmatic send was refused, for `submitMessage`'s `errors`. A
+     * backend block is called out distinctly because — unlike the transient
+     * "busy" cases — waiting and retrying will never clear it, and a caller
+     * looping on "Assistant is busy" would spin forever.
+     */
+    sendRefusalReason() {
+        return this.blocked ? this.effectiveBlockedReason : 'Assistant is busy';
     }
     /**
      * Re-runs `agentsChanged` if the live `agents` array no longer matches the
@@ -563,6 +652,514 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         var _a;
         (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setRestoring(value);
     }
+    /**
+     * Whether the assistant is blocked by a backend condition and cannot send —
+     * today, an exhausted AI-spend budget (GENC-1464). While true the composer is
+     * disabled, `send`/`submitMessage` refuse, suggestions stop being fetched, and
+     * a persistent banner (`part="blocked-banner"`) sits above the composer
+     * explaining why. The transcript stays visible and scrollable throughout —
+     * unlike `compacting` and `restoring`, this does not replace the conversation.
+     *
+     * **Latched.** Nothing in the element clears it: not a new turn, not "Clear"
+     * / "New chat", not a pop-in/out. It stays set until the host writes
+     * `false` — because nothing the user can do inside the assistant refills a
+     * budget. Hosts typically set it from their own pre-flight budget check on
+     * mount, and clear it once a later check shows headroom again.
+     *
+     * The driver also latches it automatically when a turn ends with the
+     * `'budget-exhausted'` failure reason — off the `tool-loop-end` activity bus
+     * (which also covers a sub-agent wall, a turn this element did not start, and
+     * an element swapped in mid-turn) and off the driver's return value (which
+     * covers a wall hit during multi-agent classification, where no tool loop ran
+     * and so no bus event fires). So a host that does no pre-flight at all still
+     * gets a correct locked UI the moment the first 402 lands. The bus topic is
+     * tab-scoped, so a wall hit in a popped-out window latches the main window
+     * too — correct for a shared spend cap.
+     *
+     * **Lifetime — read this before relying on it as your source of truth.** The
+     * latch is in-memory and per-`stateKey`:
+     *
+     * - It does **not** survive `switchSession`. Switching away tears the outgoing
+     *   session's store down entirely, so switching back yields a fresh, unblocked
+     *   store.
+     * - It does **not** survive a page reload. It is deliberately absent from the
+     *   persisted session snapshot: the snapshot is long-lived, so a persisted
+     *   latch would outlive an out-of-band budget raise with no in-element way to
+     *   clear it — a stale lock is worse than re-deriving the state.
+     *
+     * The durable source of truth is therefore the **host's pre-flight**, which
+     * should run on mount and on every session switch. See
+     * `docs/migration-GENC-1464.md` §"How to adopt", Option B.
+     *
+     * @beta
+     */
+    get blocked() {
+        var _a;
+        const session = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant;
+        if (!session)
+            return false;
+        if (session.blocked)
+            return true;
+        // Byte-identical to the old stored read for every host that never adopts the
+        // per-vendor API — which is what makes this derivation non-breaking.
+        if (session.blockedVendors.length === 0)
+            return false;
+        // Unknown reachability (statuses not loaded yet, or providers that report no
+        // status) fails SAFE — any wall blocks everything, exactly today's semantics —
+        // and needs no clause of its own: `every` on the empty set is vacuously true.
+        return this.reachableVendors.every((v) => session.blockedVendors.includes(v));
+    }
+    set blocked(value) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setBlocked({ blocked: value });
+    }
+    /**
+     * The distinct vendors the registry can currently reach, from the provider
+     * statuses this element already loads on connect and refreshes on every
+     * observable-registry change.
+     *
+     * This is the element's answer to "which vendor would the next turn use" — a
+     * question that has **no** correct answer and deliberately gets no API. The
+     * provider is resolved per turn AND per agent: `activeProviderInput` may be an
+     * async function of the turn's context, an orchestrated turn picks its agent
+     * with an LLM `classify()` call, and sub-agents resolve their own providers.
+     * Any pre-turn "peek" would therefore be a guess that is wrong precisely on the
+     * multi-agent hosts per-vendor budgets exist for.
+     *
+     * Asking instead which vendors are REACHABLE is answerable, synchronous, and
+     * free — and it is enough: the composer must stay live while any reachable
+     * vendor has headroom, and must lock when none does. It also makes vendor-switch
+     * recovery a derivation rather than a mutation: a host that swaps its registry
+     * to another vendor fires the observable, the statuses reload, the walled vendor
+     * drops out of this set, and `blocked` goes false with every latch left intact.
+     *
+     * @beta
+     */
+    get reachableVendors() {
+        var _a, _b;
+        const seen = new Set();
+        for (const entry of this.providerStatuses) {
+            const provider = (_a = entry.status) === null || _a === void 0 ? void 0 : _a.provider;
+            if (!provider || provider === 'none')
+                continue;
+            // Reachable means "can serve the next turn", and `chat()` is OPTIONAL on
+            // `AIProvider` — the shipped `ChromeProvider` and `OpenAIProvider`
+            // implement `getStatus()` only. Counting a chat-less provider here made
+            // every consumer wrong at once: it was headroom for the `blocked`
+            // derivation (so `otherVendorAvailable: false` failed to lock the
+            // composer and each send burned another doomed 402), and it was a switch
+            // target for the banner ("Switch to Chrome to keep going" toward a
+            // provider that cannot chat).
+            //
+            // The gate is CAPABILITY, not vendor identity, so a host's custom
+            // chat-capable OpenAI provider still counts — the same distinction
+            // `validate-providers.ts` already enforces by throwing. And it drops a
+            // vendor only on positive evidence: statuses normally come from
+            // `providerRegistry.listStatuses()`, whose `name` always resolves, but a
+            // host (or test) that assigns `providerStatuses` directly may have no
+            // matching registry entry, and an unresolvable name must not silently
+            // erase a vendor the status layer vouched for.
+            const registered = (_b = this.providerRegistry) === null || _b === void 0 ? void 0 : _b.get(entry.name);
+            if (registered && typeof registered.chat !== 'function')
+                continue;
+            seen.add(provider);
+        }
+        return [...seen];
+    }
+    /**
+     * Vendors currently walled by the AI-spend budget, in the order they were
+     * walled. Empty for a host that never adopts the per-vendor API.
+     *
+     * May include a vendor this registry cannot reach — either because the registry
+     * moved on after the wall was latched, or because a 402's
+     * `otherVendorAvailable: false` walls every vendor the proxy meters (which is
+     * what that verdict is a statement about; see
+     * {@link FoundationAiAssistant.latchBlockedFrom}). Neither costs anything
+     * internally — {@link FoundationAiAssistant.blocked} asks only about the
+     * reachable set, and the banner reads the reachability-filtered
+     * {@link FoundationAiAssistant.relevantBlockedVendors} — but a host rendering
+     * this list itself should filter it against its own registry.
+     *
+     * Read-only on purpose: a settable array would let a host write a partial list
+     * and silently orphan the per-vendor banner copy.
+     * {@link FoundationAiAssistant.setVendorBlocked} is the write path.
+     *
+     * @beta
+     */
+    get blockedVendors() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.blockedVendors) !== null && _b !== void 0 ? _b : [];
+    }
+    /**
+     * Whether this specific vendor's budget is walled — regardless of whether any
+     * other vendor still has headroom.
+     *
+     * @beta
+     */
+    isVendorBlocked(vendor) {
+        return this.blockedVendors.includes(vendor);
+    }
+    /**
+     * Wall (or release) one vendor's budget, optionally with banner copy for it.
+     * The per-vendor mirror of {@link FoundationAiAssistant.setBlocked}.
+     *
+     * Walling a vendor does **not** on its own disable the composer: while another
+     * reachable vendor has headroom the assistant stays usable and the banner tells
+     * the user to switch. Only when every reachable vendor is walled does `blocked`
+     * become true.
+     *
+     * `reason` is composed into the banner sentence for that vendor, **however many
+     * vendors are walled** — see {@link FoundationAiAssistant.effectiveBlockedReason}.
+     * It is per-vendor copy, not a whole-banner override; {@link FoundationAiAssistant.blockedReason}
+     * is the override. Omitting it keeps whatever explanation that vendor already
+     * carried, so a driver latch landing after a host one cannot blank it.
+     *
+     * `'none'` is rejected with a warning rather than accepted: it is the "no
+     * provider configured" sentinel, not a vendor. Latching it would put the raw
+     * sentinel in the banner ("none's AI usage limit is reached") and could never
+     * be undone by derivation, because `'none'` never appears in
+     * {@link FoundationAiAssistant.reachableVendors} — so `blocked` could never
+     * become derivable from it either. Use {@link FoundationAiAssistant.setBlocked}
+     * for a vendor-agnostic block.
+     *
+     * @beta
+     */
+    setVendorBlocked(vendor, blocked, reason) {
+        var _a;
+        if (vendor === 'none') {
+            logger.warn("FoundationAiAssistant.setVendorBlocked: 'none' is the no-provider sentinel, not a vendor — " +
+                'ignoring. Use setBlocked() for a vendor-agnostic block.');
+            return;
+        }
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setVendorBlocked({ vendor, blocked, reason });
+    }
+    /**
+     * The walled vendors the user can still be routed to — i.e.
+     * {@link FoundationAiAssistant.blockedVendors} narrowed to the reachable set,
+     * which is the only set the banner may name.
+     *
+     * A wall the registry can no longer reach is not news: it cannot be hit, and
+     * naming it puts a vendor in front of the user that is not theirs. The concrete
+     * failure this exists to stop: a host ships Anthropic-only, Anthropic walls, the
+     * host swaps its registry to Gemini, Gemini walls — and the banner reads "AI
+     * usage limits are reached for Anthropic and Gemini" to a user who has never
+     * had an Anthropic key. The spurious second name also flips the copy onto the
+     * plural branch, so even the closing sentence is wrong.
+     *
+     * Falls back to the unfiltered list when nothing is reachable, which is the
+     * same fail-safe {@link FoundationAiAssistant.blocked} takes there: unknown
+     * reachability means every wall counts, so every wall is also worth naming.
+     *
+     * @internal
+     */
+    get relevantBlockedVendors() {
+        const walled = this.blockedVendors;
+        const reachable = this.reachableVendors;
+        if (reachable.length === 0)
+            return walled;
+        return walled.filter((v) => reachable.includes(v));
+    }
+    /**
+     * Whether the blocked banner has anything to say — a vendor-agnostic block, OR
+     * at least one walled vendor the registry can still reach. Broader than
+     * {@link FoundationAiAssistant.blocked} on purpose: partial exhaustion leaves
+     * the composer live but still needs to be announced, because the next turn may
+     * route to the walled vendor and fail.
+     *
+     * Reads the reachability-filtered list for the same reason the copy does — a
+     * host that has swapped its registry away from the walled vendor has nothing
+     * left to announce, and would otherwise get a banner that falls through to the
+     * generic default copy over a perfectly usable composer.
+     *
+     * @internal
+     */
+    get bannerVisible() {
+        return this.blocked || this.relevantBlockedVendors.length > 0;
+    }
+    /**
+     * Whether a suggestions fetch would hit a wall.
+     *
+     * Unlike a chat turn, this one CAN be resolved exactly: both suggestion paths
+     * go to the registry **default** and never to a per-agent override
+     * (`ChatDriver.getSuggestions` calls `providerRegistry.default()`, and
+     * `OrchestratingDriver.getSuggestions` just delegates to it). So the vendor a
+     * suggestions call would use is knowable, and this is the one place in the
+     * feature where that is true.
+     *
+     * Same rationale as the guard it replaces: a doomed suggestions call burns a
+     * `suggestions.failed` meta event and parks a raw transport error in
+     * `suggestionsState` for hosts to find.
+     *
+     * @internal
+     */
+    get suggestionsBlocked() {
+        var _a, _b;
+        if (this.blocked)
+            return true;
+        const defaultVendor = (_b = (_a = this.providerStatuses.find((e) => e.isDefault)) === null || _a === void 0 ? void 0 : _a.status) === null || _b === void 0 ? void 0 : _b.provider;
+        return !!defaultVendor && defaultVendor !== 'none' && this.isVendorBlocked(defaultVendor);
+    }
+    /**
+     * Explanation shown in the blocked banner, or `null` for the element's default
+     * copy. Only meaningful while {@link FoundationAiAssistant.blocked} is true;
+     * setting `blocked = false` clears it.
+     *
+     * Writable, and symmetric with every other store-backed accessor on this
+     * class: writing it re-latches with the CURRENT `blocked` value, so it changes
+     * the copy without disturbing the flag. Assigning `null` clears the
+     * explanation while staying blocked (the banner falls back to the default
+     * copy). {@link FoundationAiAssistant.setBlocked} remains the way to write
+     * both in one atomic action.
+     *
+     * @beta
+     */
+    get blockedReason() {
+        var _a, _b;
+        return (_b = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.blockedReason) !== null && _b !== void 0 ? _b : null;
+    }
+    set blockedReason(value) {
+        var _a;
+        // Deliberately NOT `setBlocked({ blocked: this.blocked, reason })`: `blocked`
+        // is derived now, so re-latching with it would pass `false` for a partially
+        // walled session and clear every per-vendor latch as a side effect of setting
+        // a string.
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setBlockedReason(value);
+    }
+    /**
+     * Latch the backend block off a turn outcome. The single decision point for
+     * both latch sites (the `tool-loop-end` bus subscription and `send()`'s
+     * return-value check), so the rule cannot diverge between them.
+     *
+     * Idempotent and one-way **per vendor**: it never unblocks, and it never
+     * re-writes an existing wall. That guard is load-bearing, not just an
+     * optimisation — the bus fires from the driver's `finally`, i.e. BEFORE
+     * `sendMessage()` resolves, so a host subscribed to `tool-loop-end` (what the
+     * migration guide's Option C recommends) sets its own detailed reason and the
+     * return-value latch would otherwise land a moment later and blank it.
+     *
+     * The guard being per-vendor rather than global is the whole difference. A
+     * single global "already blocked, do nothing" would swallow a second vendor's
+     * wall — so a session walled on Anthropic could never record that Gemini went
+     * too, and under a mixed registry an Anthropic-only wall would lock a composer
+     * that Gemini could still serve.
+     *
+     * **Which field is authoritative**, in order:
+     *
+     * 1. `budget.vendorLabel` — stamped by the transport that was actually refused,
+     *    so it can never be stale. But it is a static per-transport string, so a
+     *    white-labelled or multiplexing gateway fronting several upstreams leaves
+     *    it unclaimed by any vendor.
+     * 2. `budget.vendor` — which the driver resolved from the label where it could,
+     *    and otherwise from the proxy's own `vendor` field on the 402. It is
+     *    therefore NOT simply `vendorLabel` normalised, and the two can disagree;
+     *    that fallback is the only attribution on offer for the gateway case above.
+     * 3. `vendorHint` — the bus detail's top-level vendor, i.e. the driver's
+     *    last-resolved provider. Last resort because it CAN be stale: an
+     *    orchestrated turn classifies against the registry default, a provider the
+     *    chat driver may never have resolved, so its last-resolved provider there is
+     *    the previous turn's vendor or nothing at all.
+     *
+     * A wall that names no recognised vendor falls back to the vendor-agnostic
+     * block — fail-safe, and identical to the pre-per-vendor behaviour.
+     *
+     * **`otherVendorAvailable: false` is server-known truth and outranks every
+     * inference made here.** The proxy meters the pots, so only it can say whether
+     * anything else has headroom; this element can only observe which vendors the
+     * registry can REACH, which says nothing about their remaining spend. So when
+     * the proxy says no, every other *budgeted* vendor is walled in the same pass.
+     * That is what makes `blocked` derive true — locking the composer on the first
+     * response instead of after a second doomed turn — and what empties the "free"
+     * set the banner would otherwise have advised switching to.
+     *
+     * The sweep runs over `BUDGETED_VENDORS`, deliberately **not** over
+     * {@link FoundationAiAssistant.reachableVendors}. Reachability is loaded
+     * asynchronously (`activateSession` kicks off `loadProviderStatuses()` and does
+     * not await it), so a wall landing before the statuses resolve would have swept
+     * an empty set — silently discarding the one fact on the 402 the client cannot
+     * re-derive, with nothing to re-run it when the statuses arrived. Worse, it let
+     * the verdict effectively un-latch: the single wall derived `blocked` only
+     * while the reachable set was empty, so the moment the statuses landed the
+     * composer came back to life against a budget the proxy had already said was
+     * gone. Sweeping the metered vendor list instead makes the verdict independent
+     * of load order and of registry membership, which is exactly what it is: a
+     * statement about the proxy's pots, not about this user's registry.
+     *
+     * Walling a vendor the registry cannot reach costs nothing: `blocked` only asks
+     * whether every REACHABLE vendor is walled, and the banner reads
+     * {@link FoundationAiAssistant.relevantBlockedVendors}, which filters the walls
+     * back down to the reachable set before naming any of them.
+     *
+     * One boundary remains on the sweep: it walls only vendors the proxy meters
+     * (`isBudgetedVendor`). Chrome runs on-device with no pot to exhaust, so "no
+     * other vendor has budget" is not a statement about it, and "Switch to Chrome
+     * to keep going." stays honest advice.
+     *
+     * The sweep runs last but sits OUTSIDE the per-vendor idempotence guard, and
+     * both halves of that matter. Last, so the vendor that actually refused this
+     * turn heads the wall order the multi-vendor banner reads. Outside the guard,
+     * because the verdict can arrive on a LATER 402 for a vendor that is already
+     * walled — turn 1 walls Anthropic while Gemini still has headroom, turn 2 walls
+     * it again and reports that Gemini has since gone too — and an early return
+     * would drop exactly the news the second turn was there to deliver.
+     *
+     * @param reason - the turn's failure reason; anything but `'budget-exhausted'` is ignored.
+     * @param ref - session store to write through; defaults to the live one. `send()`
+     *   passes the ref it captured before its awaits, since a lifecycle event during the
+     *   turn may already have cleared `_sessionRef`.
+     * @param budget - what the 402 reported: figures when the proxy sent any, the
+     *   refusing vendor, and its `otherVendorAvailable` verdict.
+     * @param vendorHint - the `tool-loop-end` detail's top-level vendor, used only
+     *   when the budget payload names none.
+     *
+     * @internal
+     */
+    latchBlockedFrom(reason, ref = this._sessionRef, budget, vendorHint) {
+        var _a, _b;
+        if (reason !== 'budget-exhausted')
+            return;
+        const vendor = (_b = (_a = vendorTypeOfLabel(budget === null || budget === void 0 ? void 0 : budget.vendorLabel)) !== null && _a !== void 0 ? _a : budget === null || budget === void 0 ? void 0 : budget.vendor) !== null && _b !== void 0 ? _b : vendorHint;
+        if (!vendor || vendor === 'none') {
+            if (!this.blocked) {
+                ref === null || ref === void 0 ? void 0 : ref.actions.aiAssistant.setBlocked({ blocked: true, reason: formatBlockedReason(budget) });
+            }
+        }
+        else if (!this.isVendorBlocked(vendor)) {
+            if (this.reachableVendors.length === 0) {
+                // Not fatal — `blocked` still derives to true, so the UI is correct — but
+                // the host gets no per-vendor benefit and would otherwise have no signal.
+                logger.warn(`FoundationAiAssistant: ${vendor} hit its AI budget, but no registered provider counts ` +
+                    'as reachable, so per-vendor blocking degrades to blocking everything. Two causes: no ' +
+                    'provider reports a status (implement AIProvider.getStatus()), or every provider that ' +
+                    'does is chat-less and so cannot serve a turn (implement chat() on at least one).');
+            }
+            ref === null || ref === void 0 ? void 0 : ref.actions.aiAssistant.setVendorBlocked({
+                vendor,
+                blocked: true,
+                reason: formatBlockedReason(budget, vendor),
+            });
+        }
+        // Last, so the vendor that actually refused this turn heads the wall order the
+        // multi-vendor banner reads — and unconditionally, NOT under the per-vendor
+        // idempotence guard above, because the verdict can arrive on a later 402 for a
+        // vendor that is already walled.
+        if ((budget === null || budget === void 0 ? void 0 : budget.otherVendorAvailable) !== false)
+            return;
+        // Over the metered vendor list, NOT the reachable set: the statuses load
+        // asynchronously, so a reachability-scoped sweep dropped the verdict entirely
+        // when the wall beat them home. `relevantBlockedVendors` filters the extra
+        // walls back out before the banner names anyone.
+        for (const other of BUDGETED_VENDORS) {
+            if (other === vendor || this.isVendorBlocked(other))
+                continue;
+            // No reason: the slice's "an omitted reason keeps the existing explanation"
+            // rule applies, and there are no figures for this vendor — only the proxy's
+            // word that it has nothing left. The banner names it either way.
+            ref === null || ref === void 0 ? void 0 : ref.actions.aiAssistant.setVendorBlocked({ vendor: other, blocked: true });
+        }
+    }
+    /**
+     * Block or unblock the assistant, optionally with custom banner copy.
+     * Equivalent to the {@link FoundationAiAssistant.blocked} setter, plus the
+     * reason in one atomic write.
+     *
+     * Blocking writes the **vendor-agnostic** block — what a host with one budget
+     * pot means — and does not populate
+     * {@link FoundationAiAssistant.blockedVendors}. Unblocking clears the
+     * per-vendor walls as well, so a host asserting "the wall is gone" after its
+     * own pre-flight cannot be silently overruled by a driver latch it never saw.
+     *
+     * @beta
+     */
+    setBlocked(blocked, reason) {
+        var _a;
+        (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.actions.aiAssistant.setBlocked({ blocked, reason });
+    }
+    /**
+     * Copy shown in the blocked banner, in ascending specificity:
+     *
+     * 1. the host's `blockedReason` — a whole-banner override, unchanged;
+     * 2. copy composed from the walled vendors (their per-vendor reasons when set,
+     *    otherwise their names) plus the action that is actually available;
+     * 3. the default budget-exhaustion message.
+     *
+     * The action clause is computed here rather than stored, because whether
+     * "switch vendor" or "contact your administrator" is honest depends on whether
+     * another reachable vendor still has headroom — which changes when the registry
+     * changes, long after the wall was latched. Telling a user to switch to a
+     * vendor that is also exhausted is worse than saying nothing.
+     *
+     * The `free` set is a client-side inference — "reachable and not known to be
+     * walled" — and it is only ever allowed to be one. Where the proxy has told us
+     * otherwise (`otherVendorAvailable: false`) the latch has already walled those
+     * vendors, so they are not in `free` here and no "switch to X" clause can be
+     * composed from them. Both lists are filtered by reachability, so the copy
+     * names only vendors this user's registry can actually route to.
+     *
+     * **Per-vendor copy is composed however many vendors are walled**, which is
+     * what {@link FoundationAiAssistant.setVendorBlocked} and
+     * `docs/migration-GENC-1464.md` both promise. It previously reached only the
+     * single-vendor branch, so a host that had carefully set copy for each of its
+     * vendors watched all of it vanish the moment a second one walled — replaced by
+     * generic copy, at the exact moment the situation got worse.
+     *
+     * The compact "AI usage limits are reached for A and B." list is kept for the
+     * case it was written for: NO walled vendor carries copy, so a statement per
+     * vendor would just repeat one boilerplate sentence per name. As soon as any of
+     * them does carry copy, the branch lists one statement per vendor instead —
+     * falling back to that same boilerplate for the ones that have none, so the
+     * sentence set stays complete rather than silently naming a subset.
+     *
+     * @internal
+     */
+    get effectiveBlockedReason() {
+        var _a;
+        if (this.blockedReason)
+            return this.blockedReason;
+        const walled = this.relevantBlockedVendors;
+        if (walled.length === 0)
+            return DEFAULT_BUDGET_EXHAUSTED_MESSAGE;
+        const free = this.reachableVendors.filter((v) => !walled.includes(v));
+        const action = free.length
+            ? `Switch to ${formatVendorList(free)} to keep going.`
+            : walled.length > 1
+                ? RAISE_LIMITS_ACTION
+                : RAISE_LIMIT_ACTION;
+        const reasons = (_a = this._sessionRef) === null || _a === void 0 ? void 0 : _a.store.aiAssistant.blockedVendorReasons;
+        const statementFor = (v) => { var _a; return (_a = reasons === null || reasons === void 0 ? void 0 : reasons[v]) !== null && _a !== void 0 ? _a : `${vendorDisplayName(v)}'s AI usage limit is reached.`; };
+        if (walled.length === 1)
+            return `${statementFor(walled[0])} ${action}`;
+        // Several walled vendors carry several sets of figures, which do not fit one
+        // sentence. With no per-vendor copy to preserve, name them in a list rather
+        // than repeat the same boilerplate sentence per vendor.
+        if (!walled.some((v) => reasons === null || reasons === void 0 ? void 0 : reasons[v])) {
+            return `AI usage limits are reached for ${formatVendorList(walled)}. ${action}`;
+        }
+        return `${walled.map(statementFor).join(' ')} ${action}`;
+    }
+    /**
+     * Copy the driver writes into the TRANSCRIPT when a turn hits the budget wall.
+     *
+     * A host-set `blockedReason` still wins, so a white-labelled host does not read
+     * its own explanation in the banner and the shipped default directly below it —
+     * that is the whole reason the driver takes this at all.
+     *
+     * What it deliberately is NOT is
+     * {@link FoundationAiAssistant.effectiveBlockedReason}. That getter
+     * composes advice — `"…Switch to Gemini to keep going."` — which is true only
+     * while that vendor has headroom, and the transcript is a permanent record. The
+     * driver reads this once at CONSTRUCTION, and `getOrCreateDriver` keys on the
+     * agents list, so an agents swap *after* a wall re-runs `createDriver` and would
+     * freeze that sentence into every later turn's bubble. Reading the latch's own
+     * copy instead is structurally incapable of carrying the advice: the only
+     * writer of `blockedReason` is the vendor-agnostic branch of
+     * `latchBlockedFrom`, whose `formatBlockedReason(budget)` form has no switch
+     * clause. Per-vendor copy lives in `blockedVendorReasons` and reaches the
+     * banner alone.
+     */
+    get transcriptBudgetExhaustedMessage() {
+        var _a;
+        return (_a = this.blockedReason) !== null && _a !== void 0 ? _a : DEFAULT_BUDGET_EXHAUSTED_MESSAGE;
+    }
     /**
      * Name of the agent the user has pinned via the agent picker. `null` means
      * automatic routing (Auto). Persisted on the session store, so it survives
@@ -1057,6 +1654,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 maxFoldOperations: agent.maxFoldOperations,
                 maxTurnSnapshots: agent.maxTurnSnapshots,
                 activityBus: agenticActivityBus,
+                budgetExhaustedMessage: this.transcriptBudgetExhaustedMessage,
             });
         }
         return new ChatDriver(this.providerRegistry, {
@@ -1065,6 +1663,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             maxTurnSnapshots: agent.maxTurnSnapshots,
             sessionKey: (_c = this.getStateKey()) !== null && _c !== void 0 ? _c : '',
             activityBus: agenticActivityBus,
+            budgetExhaustedMessage: this.transcriptBudgetExhaustedMessage,
         });
     }
     /**
@@ -1373,7 +1972,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         });
     }
     connectedCallback() {
-        var _a;
+        var _a, _b;
         // Initialise the store reference BEFORE super.connectedCallback() so that
         // the first FAST render has access to the store. The store Proxy calls
         // Observable.track(observableStore, sliceName) whenever a slice is read,
@@ -1411,6 +2010,18 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             });
         }
         this.wireAppSettingsProvider();
+        // Latch the backend block off the activity bus (GENC-1464). This is the primary
+        // seam: it fires for a turn this element did not start, for a sub-agent's
+        // wall (the child inherits the parent's bus and publishes its own
+        // `tool-loop-end`), and it writes through whichever element is connected NOW
+        // rather than the one that happened to call `send()`. Re-subscribed per
+        // connect (docking/popout remounts); balanced in `disconnectedCallback`.
+        (_b = this._unsubBudgetLatch) === null || _b === void 0 ? void 0 : _b.call(this);
+        this._unsubBudgetLatch = agenticActivityBus.subscribe('tool-loop-end', (d) => 
+        // Pass the figures through: this seam wins the latch for an in-loop wall (the
+        // common case), so dropping them here would render the generic banner copy in
+        // exactly the path `ChatDriverResult.budget` was widened to serve.
+        this.latchBlockedFrom(d === null || d === void 0 ? void 0 : d.failureReason, undefined, d === null || d === void 0 ? void 0 : d.budget, d === null || d === void 0 ? void 0 : d.vendor));
         if (this.messagesEl) {
             this._scrollListener = () => {
                 this._userScrolledAway =
@@ -1500,7 +2111,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         this.switchSession(currentKey !== null && currentKey !== void 0 ? currentKey : targetKey, targetKey);
     }
     disconnectedCallback() {
-        var _a, _b, _c, _d, _e, _f;
+        var _a, _b, _c, _d, _e, _f, _g;
         window.removeEventListener('pagehide', this._handlePageHide);
         super.disconnectedCallback();
         this._sessionActive = false;
@@ -1515,10 +2126,12 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         this.unwireDriver();
         (_a = this.unsubBus) === null || _a === void 0 ? void 0 : _a.call(this);
         this.unsubBus = undefined;
-        (_b = this.unsubProviderRegistry) === null || _b === void 0 ? void 0 : _b.call(this);
+        (_b = this._unsubBudgetLatch) === null || _b === void 0 ? void 0 : _b.call(this);
+        this._unsubBudgetLatch = undefined;
+        (_c = this.unsubProviderRegistry) === null || _c === void 0 ? void 0 : _c.call(this);
         this.unsubProviderRegistry = undefined;
         this.unwireAppSettingsProvider();
-        (_c = this._executionCompletionUnsub) === null || _c === void 0 ? void 0 : _c.call(this);
+        (_d = this._executionCompletionUnsub) === null || _d === void 0 ? void 0 : _d.call(this);
         this._executionCompletionUnsub = undefined;
         // Note: the restore-core autosave AND diagnostics-append timers live on the
         // shared per-session persister (GENC-1351 §5.10), not here — they must survive a
@@ -1536,12 +2149,12 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         // the panel re-mounts open.
         this._agentPickerToggle.finalize();
         if (this.settingsOpen) {
-            (_d = this.settingsModal) === null || _d === void 0 ? void 0 : _d.close();
+            (_e = this.settingsModal) === null || _e === void 0 ? void 0 : _e.close();
             this.settingsOpen = false;
         }
         this._sessionMenuToggle.finalize();
         // Capture before clearing — `wasBusy` reads the driver, which is dropped below.
-        this.logMeta('assistant.disconnected', { wasBusy: (_f = (_e = this.driver) === null || _e === void 0 ? void 0 : _e.isBusy()) !== null && _f !== void 0 ? _f : false });
+        this.logMeta('assistant.disconnected', { wasBusy: (_g = (_f = this.driver) === null || _f === void 0 ? void 0 : _f.isBusy()) !== null && _g !== void 0 ? _g : false });
         // Clear local references only — driver and store stay in their registries.
         this.driver = undefined;
         this._sessionRef = undefined;
@@ -2362,6 +2975,10 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
      * message will go; otherwise falls back to the host-provided placeholder.
      */
     get effectivePlaceholder() {
+        // The block outranks the agent pin: while blocked the composer is disabled
+        // anyway, so naming the pinned agent would only imply a send is possible.
+        if (this.blocked)
+            return BLOCKED_PLACEHOLDER;
         if (this.pinnedAgentName)
             return `Message ${this.pinnedAgentName}...`;
         return this.placeholder;
@@ -2741,6 +3358,11 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         (_b = (_a = this.driver) === null || _a === void 0 ? void 0 : _a.cancel) === null || _b === void 0 ? void 0 : _b.call(_a);
     }
     handleSuggestionClick(suggestion) {
+        // Belt-and-braces with the template gate that hides the chips while blocked:
+        // `send()` refuses, but `inputValue` would already have been written, leaving
+        // the chip's text stranded in a disabled textarea the user cannot clear.
+        if (this.sendBlocked)
+            return;
         this.inputValue = suggestion;
         this.send();
     }
@@ -2769,7 +3391,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
             if (this.sendBlocked) {
-                return { ok: false, errors: ['Assistant is busy'] };
+                return { ok: false, errors: [this.sendRefusalReason()] };
             }
             let nextAttachments = [];
             if ((_a = input.files) === null || _a === void 0 ? void 0 : _a.length) {
@@ -2782,7 +3404,7 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 // (Cast widens through TS's narrowing of `this.state` from the earlier
                 // early-return; the getter can return a different value across an await.)
                 if (this.sendBlocked) {
-                    return { ok: false, errors: ['Assistant is busy'] };
+                    return { ok: false, errors: [this.sendRefusalReason()] };
                 }
                 if (errors.length) {
                     this.attachmentErrors = errors;
@@ -2814,6 +3436,21 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
             if (!this.driver || !suggestionsConfig || suggestionsConfig.behavior === 'never') {
                 return;
             }
+            // A guaranteed 402. This runs from the post-turn `finally` (the turn that
+            // just latched), from `connectedCallback` (a pop-in against a blocked store),
+            // and from the `pinnedAgentName` setter — which resets `suggestionsState`
+            // first, defeating the already-fetched guard below. So without this a blocked
+            // session still fires one doomed request per turn, per pop-in and per pin
+            // change, each one burning a `suggestions.failed` meta event and parking a
+            // raw transport-error string in `suggestionsState.message`.
+            //
+            // Resolved against the registry DEFAULT, not the whole composer gate: both
+            // suggestion paths call `providerRegistry.default()`, so under partial
+            // exhaustion this is knowable exactly — and suggestions stay available when
+            // the default vendor is the one with headroom.
+            if (this.suggestionsBlocked) {
+                return;
+            }
             if (suggestionsConfig.behavior === 'initial' && this.messages.length > 0) {
                 return;
             }
@@ -2895,7 +3532,16 @@ let FoundationAiAssistant = FoundationAiAssistant_1 = class FoundationAiAssistan
                 ? `${input}\n\n*Attached: ${pendingAttachments.map((a) => a.name).join(', ')}*`
                 : input;
             try {
-                yield ((_a = this.driver) === null || _a === void 0 ? void 0 : _a.sendMessage(displayInput, pendingAttachments));
+                const result = yield ((_a = this.driver) === null || _a === void 0 ? void 0 : _a.sendMessage(displayInput, pendingAttachments));
+                // Latch the backend block the moment the driver reports it, so the composer
+                // locks without waiting on the host's next pre-flight. The bus subscription
+                // in `connectedCallback` covers most walls; this covers the one it cannot —
+                // a wall hit during multi-agent classification, where no tool loop ran and
+                // so no `tool-loop-end` was published. `latchBlockedFrom` is idempotent, so
+                // the two seams overlapping is harmless.
+                if ((result === null || result === void 0 ? void 0 : result.reason) === 'done') {
+                    this.latchBlockedFrom(result.failureReason, capturedSessionRef, result.budget);
+                }
             }
             finally {
                 this.stopLoadingTimer();
@@ -3075,6 +3721,24 @@ __decorate([
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "busy", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "blocked", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "reachableVendors", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "relevantBlockedVendors", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "bannerVisible", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "suggestionsBlocked", null);
+__decorate([
+    volatile
+], FoundationAiAssistant.prototype, "effectiveBlockedReason", null);
 __decorate([
     volatile
 ], FoundationAiAssistant.prototype, "effectiveChatInputDuringExecution", null);