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

package/src/main/main.ts

@@ -23,12 +23,22 @@
 
 import type {
   AIProviderRegistryStatusEntry,
+  AIProviderType,
   ChatAttachment,
   ChatConfig,
+  ChatDriverResult,
   ChatInputDuringExecutionMode,
   ChatMessage,
+  TurnFailureReason,
+} from '@genesislcap/foundation-ai';
+import {
+  AIProviderRegistry,
+  BUDGETED_VENDORS,
+  DEFAULT_BUDGET_EXHAUSTED_MESSAGE,
+  isObservableAIProviderRegistry,
+  VENDOR_LABELS,
+  vendorTypeOfLabel,
 } from '@genesislcap/foundation-ai';
-import { AIProviderRegistry, isObservableAIProviderRegistry } from '@genesislcap/foundation-ai';
 import { showNotificationDialog } from '@genesislcap/foundation-notifications';
 import { avoidTreeShaking } from '@genesislcap/foundation-utils';
 import type { Modal } from '@genesislcap/rapid-design-system';
@@ -196,6 +206,88 @@ 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?: Extract<ChatDriverResult, { reason: 'done' }>['budget'],
+  vendor?: AIProviderType,
+): string | undefined {
+  if (!budget || (budget.budgetUsd == null && budget.spentUsd == null)) return undefined;
+  const money = (v?: number) => (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: AIProviderType): string {
+  return (VENDOR_LABELS as Partial<Record<AIProviderType, string>>)[vendor] ?? 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: readonly AIProviderType[]): string {
+  const names = vendors.map(vendorDisplayName);
+  if (names.length <= 1) return names[0] ?? '';
+  return `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+}
+
 // Register supporting components when the main component module is imported.
 avoidTreeShaking(
   AiChatMarkdown,
@@ -410,14 +502,26 @@ export class FoundationAiAssistant extends GenesisElement {
 
   /**
    * 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).
    */
   private get sendBlocked(): boolean {
-    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.
+   */
+  private sendRefusalReason(): string {
+    return this.blocked ? this.effectiveBlockedReason : 'Assistant is busy';
   }
 
   /**
@@ -589,6 +693,521 @@ export class FoundationAiAssistant extends GenesisElement {
     this._sessionRef?.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
+   */
+  @volatile
+  get blocked(): boolean {
+    const session = this._sessionRef?.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: boolean) {
+    this._sessionRef?.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
+   */
+  @volatile
+  get reachableVendors(): readonly AIProviderType[] {
+    const seen = new Set<AIProviderType>();
+    for (const entry of this.providerStatuses) {
+      const provider = entry.status?.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 = this.providerRegistry?.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(): readonly AIProviderType[] {
+    return this._sessionRef?.store.aiAssistant.blockedVendors ?? [];
+  }
+
+  /**
+   * Whether this specific vendor's budget is walled — regardless of whether any
+   * other vendor still has headroom.
+   *
+   * @beta
+   */
+  isVendorBlocked(vendor: AIProviderType): boolean {
+    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: AIProviderType, blocked: boolean, reason?: string | null): void {
+    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;
+    }
+    this._sessionRef?.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
+   */
+  @volatile
+  private get relevantBlockedVendors(): readonly AIProviderType[] {
+    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
+   */
+  @volatile
+  get bannerVisible(): boolean {
+    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
+   */
+  @volatile
+  get suggestionsBlocked(): boolean {
+    if (this.blocked) return true;
+    const defaultVendor = this.providerStatuses.find((e) => e.isDefault)?.status?.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(): string | null {
+    return this._sessionRef?.store.aiAssistant.blockedReason ?? null;
+  }
+  set blockedReason(value: string | null) {
+    // 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.
+    this._sessionRef?.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
+   */
+  private latchBlockedFrom(
+    reason?: TurnFailureReason,
+    ref = this._sessionRef,
+    budget?: Extract<ChatDriverResult, { reason: 'done' }>['budget'],
+    vendorHint?: AIProviderType,
+  ): void {
+    if (reason !== 'budget-exhausted') return;
+    const vendor = vendorTypeOfLabel(budget?.vendorLabel) ?? budget?.vendor ?? vendorHint;
+    if (!vendor || vendor === 'none') {
+      if (!this.blocked) {
+        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?.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?.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?.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: boolean, reason?: string | null): void {
+    this._sessionRef?.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
+   */
+  @volatile
+  get effectiveBlockedReason(): string {
+    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 = this._sessionRef?.store.aiAssistant.blockedVendorReasons;
+    const statementFor = (v: AIProviderType) =>
+      reasons?.[v] ?? `${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?.[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.
+   */
+  private get transcriptBudgetExhaustedMessage(): string {
+    return this.blockedReason ?? 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
@@ -893,6 +1512,8 @@ export class FoundationAiAssistant extends GenesisElement {
   private driverCleanup?: () => void;
   private loadingTimer: ReturnType<typeof setTimeout> | undefined;
   private unsubBus?: () => void;
+  /** Unsubscribe handle for the `tool-loop-end` budget latch (GENC-1464). */
+  private _unsubBudgetLatch?: () => void;
   /** Unsubscribe handle for the provider-registry change listener (observable registries only). */
   private unsubProviderRegistry?: () => void;
   /** Unsubscribe handle for {@link (AssistantAppSettingsProvider:interface).subscribe}. */
@@ -1250,6 +1871,7 @@ export class FoundationAiAssistant extends GenesisElement {
         maxFoldOperations: agent.maxFoldOperations,
         maxTurnSnapshots: agent.maxTurnSnapshots,
         activityBus: agenticActivityBus,
+        budgetExhaustedMessage: this.transcriptBudgetExhaustedMessage,
       });
     }
 
@@ -1259,6 +1881,7 @@ export class FoundationAiAssistant extends GenesisElement {
       maxTurnSnapshots: agent.maxTurnSnapshots,
       sessionKey: this.getStateKey() ?? '',
       activityBus: agenticActivityBus,
+      budgetExhaustedMessage: this.transcriptBudgetExhaustedMessage,
     });
   }
 
@@ -1622,6 +2245,19 @@ export class FoundationAiAssistant extends GenesisElement {
       });
     }
     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`.
+    this._unsubBudgetLatch?.();
+    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?.failureReason, undefined, d?.budget, d?.vendor),
+    );
     if (this.messagesEl) {
       this._scrollListener = () => {
         this._userScrolledAway =
@@ -1725,6 +2361,8 @@ export class FoundationAiAssistant extends GenesisElement {
     this.unwireDriver();
     this.unsubBus?.();
     this.unsubBus = undefined;
+    this._unsubBudgetLatch?.();
+    this._unsubBudgetLatch = undefined;
     this.unsubProviderRegistry?.();
     this.unsubProviderRegistry = undefined;
     this.unwireAppSettingsProvider();
@@ -2634,6 +3272,9 @@ export class FoundationAiAssistant extends GenesisElement {
    */
   @volatile
   get effectivePlaceholder(): string {
+    // 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;
   }
@@ -3024,6 +3665,10 @@ export class FoundationAiAssistant extends GenesisElement {
   }
 
   handleSuggestionClick(suggestion: string) {
+    // 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();
   }
@@ -3051,7 +3696,7 @@ export class FoundationAiAssistant extends GenesisElement {
    */
   async submitMessage(input: { text?: string; files?: File[] }): Promise<SubmitMessageResult> {
     if (this.sendBlocked) {
-      return { ok: false, errors: ['Assistant is busy'] };
+      return { ok: false, errors: [this.sendRefusalReason()] };
     }
 
     let nextAttachments: ChatAttachment[] = [];
@@ -3065,7 +3710,7 @@ export class FoundationAiAssistant extends GenesisElement {
       // (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;
@@ -3097,6 +3742,22 @@ export class FoundationAiAssistant extends GenesisElement {
       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;
     }
@@ -3186,7 +3847,16 @@ export class FoundationAiAssistant extends GenesisElement {
       ? `${input}\n\n*Attached: ${pendingAttachments.map((a) => a.name).join(', ')}*`
       : input;
     try {
-      await this.driver?.sendMessage(displayInput, pendingAttachments);
+      const result = await this.driver?.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?.reason === 'done') {
+        this.latchBlockedFrom(result.failureReason, capturedSessionRef, result.budget);
+      }
     } finally {
       this.stopLoadingTimer();
       this._pendingSendPrompt = undefined;