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

package/dist/ai-assistant.d.ts

@@ -2,6 +2,7 @@ import { AgentPickerMode } from '@genesislcap/foundation-ai';
 import { AIProviderRegistry } from '@genesislcap/foundation-ai';
 import type { AIProviderRegistryStatusEntry } from '@genesislcap/foundation-ai';
 import type { AIProviderType } from '@genesislcap/foundation-ai';
+import { BudgetExhaustedError } from '@genesislcap/foundation-ai';
 import type { CachePolicy } from '@genesislcap/foundation-ai';
 import type { ChatAttachment } from '@genesislcap/foundation-ai';
 import type { ChatConfig } from '@genesislcap/foundation-ai';
@@ -217,9 +218,59 @@ export declare interface AgenticActivityEvents {
      * driver dispose, and an agent handoff the detail is `undefined` — the historical shape,
      * kept byte-identical so subscribers that only care about the boundary can keep ignoring
      * it. Structured-cloneable so it survives the cross-tab BroadcastChannel hop.
+     *
+     * A `'budget-exhausted'` failure additionally carries `vendor` — the concrete
+     * vendor the walled turn resolved to (GENC-1464), which is NOT the same thing as
+     * the registry alias recorded on the debug-log entry. Optional and additive: a
+     * subscriber reading only `failureReason` is unaffected, and every other
+     * failure still emits the historical `{ failureReason }` with no `vendor` key.
+     * It exists so a later per-vendor budget model is an additive change rather
+     * than a retrofit — the vendor is known at the transport and at the driver, and
+     * was previously discarded between them.
+     *
+     * Note this topic is forwarded on the tab-scoped channel, so a wall hit in a
+     * popped-out window reaches the main window's subscribers too — which is why
+     * the assistant's blocked latch fires there as well. Correct for a shared spend
+     * cap; see `docs/migration-GENC-1464.md` §Scope.
      */
     'tool-loop-end': {
         failureReason?: TurnFailureReason;
+        vendor?: AIProviderType;
+        /**
+         * Proxy-reported spend figures, present only on `budget-exhausted`. Carried
+         * here because this event — not the driver's return value — is what latches
+         * the blocked state for a wall hit INSIDE the tool loop (the common case):
+         * the publish happens in `sendMessage`'s `finally`, so it lands before the
+         * return-value seam and wins the latch. Without these the banner would fall
+         * back to the generic copy in exactly the path the figures were added for.
+         * Plain numbers + string keep the detail structured-cloneable for the
+         * cross-tab hop.
+         */
+        budget?: {
+            budgetUsd?: number;
+            spentUsd?: number;
+            vendorLabel: string;
+            /**
+             * The refusing vendor as a typed value: normalised from `vendorLabel`
+             * where a vendor claims that label, otherwise from the proxy's own
+             * `vendor` field on the 402 — so it can disagree with `vendorLabel`,
+             * which is what keeps attribution working behind a white-labelled or
+             * multiplexing gateway.
+             *
+             * Distinct from the detail's top-level `vendor` (the driver's
+             * last-resolved provider): this one comes from the transport that was
+             * actually refused, so it is the one a per-vendor latch trusts first.
+             */
+            vendor?: AIProviderType;
+            /**
+             * The proxy's verdict on whether any OTHER vendor it meters still has
+             * headroom. The one fact here a subscriber cannot work out for itself:
+             * the registry says which vendors EXIST, never which still have
+             * budget. A `false` is what stops the banner advising a switch to a
+             * vendor that is equally spent.
+             */
+            otherVendorAvailable?: boolean;
+        };
     } | undefined;
     /**
      * Fired when a tool handler hands a widget to the user mid-loop and parks awaiting it
@@ -997,6 +1048,45 @@ declare interface BaseAgentConfig {
     notResumableMessage?: string;
 }
 
+/**
+ * Id of the blocked banner, referenced by the composer controls'
+ * `aria-describedby`. Shadow-DOM-scoped, so a fixed string cannot collide with
+ * the host page — and IDREF resolution is same-root, which is exactly where both
+ * ends of this reference live.
+ *
+ * @internal
+ */
+export declare const BLOCKED_BANNER_ID = "blocked-banner";
+
+/**
+ * Class list for the banner below, joined rather than interpolated so an
+ * inapplicable modifier contributes nothing. Two interpolations directly in the
+ * attribute emitted `class="blocked-banner  "` in the common (unblocked) case —
+ * harmless to the browser, but it shows up in every DOM snapshot and every
+ * innerHTML assertion a host writes against this element.
+ *
+ * The two modifiers name what they actually gate, which is why neither is
+ * `is-blocked`: `is-visible` means the banner has something to say, and that
+ * includes PARTIAL exhaustion — one vendor walled, composer still live, `blocked`
+ * false. `is-partial` then softens the treatment for exactly that case. Naming
+ * the first after `blocked` read as a contradiction beside the second, and made
+ * the styles say `.blocked-banner.is-blocked` to mean "visible".
+ *
+ * Exported for the unit test that pins the attribute; not part of the element
+ * API.
+ *
+ * @internal
+ */
+export declare const blockedBannerClasses: (x: FoundationAiAssistant) => string;
+
+/**
+ * The `budget` payload carried on a `'budget-exhausted'` {@link ChatDriverResult}.
+ * Derived from the type rather than restated so the two cannot drift.
+ */
+declare type BudgetDetail = NonNullable<Extract<ChatDriverResult, {
+    reason: 'done';
+}>['budget']>;
+
 export { CachePolicy }
 
 /**
@@ -1179,6 +1269,10 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * Set when a sub-agent's tool loop ends without `completeSubAgent` being
      * called. Read by the parent's `invokeSubAgent` to build the `{ ok: false }`
      * branch of `requestSubAgent`. Only ever set when `isSubAgent` is true.
+     *
+     * `budget` rides along on a `'budget_exhausted'` failure so the parent inherits
+     * the child's ATTRIBUTION, not just the fact of a wall — see
+     * `budgetWallDetail`.
      */
     private subAgentFailure;
     /**
@@ -1325,6 +1419,39 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
     private readonly sessionKey;
     /** Injected activity bus; defaults to a no-op off-browser (Node/tests/headless). */
     private readonly activityBus;
+    /** Transcript copy for a budget wall — see `ChatDriverConfig.budgetExhaustedMessage`. */
+    private readonly budgetExhaustedMessage;
+    /**
+     * Set the moment a budget wall is observed anywhere in this turn — this
+     * driver's own 402, or a sub-agent's (which surfaces here only as a
+     * `'budget_exhausted'` tool result). Read at the top of the tool loop to end
+     * the turn before issuing another model call that would hit the same wall.
+     * Reset per turn alongside the other per-turn counters.
+     */
+    private budgetExhaustedThisTurn;
+    /**
+     * The refusing vendor's own attribution for the wall `budgetExhaustedThisTurn`
+     * records, when it was knowable. Kept SEPARATE from the flag rather than
+     * replacing it: a figure-less 402 from a transport no vendor claims yields no
+     * detail at all (`budgetDetailOf` returns `undefined`), and folding the two
+     * would make that case stop ending the turn.
+     *
+     * It matters most for a sub-agent's wall. The child can sit on a different
+     * vendor from its parent — `applyAgent` reads `config.provider` — so without
+     * this the parent's short-circuit reports `lastResolvedProvider`, i.e. the one
+     * vendor that did NOT refuse. Under a mixed registry that walls Gemini because
+     * an Anthropic child 402'd, and if those are the only two reachable vendors the
+     * host then derives `blocked` and locks a composer that still had headroom.
+     */
+    private budgetWallDetail?;
+    /**
+     * Whether this turn's budget wall came from a SUB-AGENT rather than this
+     * driver's own request. Decides whether `lastResolvedProvider` is a valid
+     * attribution fallback: for an own wall it is the refusing vendor, for a
+     * child's wall it is the parent's vendor — the one known NOT to have refused.
+     * Reset per turn alongside `budgetWallDetail`.
+     */
+    private budgetWallViaSubAgent;
     constructor(providerRegistry: AIProviderRegistry, config?: ChatDriverConfig);
     /**
      * Tear down the driver: aborts the lifecycle signal so any in-flight provider
@@ -1371,14 +1498,49 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      * the historical `{ reason: 'done' }`.
      */
     private turnDone;
+    /**
+     * Terminal budget outcome for a wall hit **outside** the tool loop — today,
+     * `OrchestratingDriver`'s classification phase, which calls the provider
+     * directly and so never enters `runToolLoop`.
+     *
+     * Does **not** publish `tool-loop-end`: no `tool-loop-start` was published for
+     * the classify phase, and an unbalanced end would break start/end pairing for
+     * subscribers that rely on it. The driver **return value** is what reports this
+     * case — see `FoundationAiAssistant`'s latch, which reads both seams for
+     * exactly this reason.
+     *
+     * The non-sub-agent tail of the in-loop `BudgetExhaustedError` branch lives
+     * here so there is one copy of the log line, the debug-log entry, the
+     * transcript bubble and the result shape rather than two that can drift.
+     *
+     * @param pendingUserMessage - a user message that has NOT yet been appended,
+     *   appended first so the answer does not end up replying to nothing. Only the
+     *   classification seam passes it: `OrchestratingDriver` dispatches the user's
+     *   text as an optimistic `history-updated` detail and leaves the real append
+     *   to `chatDriver.sendMessage`, which never runs when `classify()` throws — so
+     *   the bubble below would re-dispatch a history the user's own message was
+     *   never in, and it would vanish from the transcript on the next render. The
+     *   in-loop caller has already appended it and passes nothing.
+     *
+     * @internal
+     */
+    reportBudgetExhausted(e: BudgetExhaustedError, pendingUserMessage?: ChatMessage): ChatDriverResult;
     /** The typed failure reason on a loop result, or `undefined` for a clean turn / handoff. */
     private static failureReasonOf;
     /**
      * Build the `tool-loop-end` event detail for a turn's result. A failure carries a
      * `{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,
      * kept byte-identical so subscribers see exactly what they always have.
+     *
+     * A budget failure additionally carries `vendor` — the concrete vendor
+     * (`'anthropic'`/`'gemini'`) the walled turn resolved to, which the driver knows
+     * and used to discard. Optional and additive: a subscriber reading only
+     * `failureReason` is unaffected, a non-budget failure still emits the historical
+     * `{ failureReason }` with no `vendor` key, and the value is a plain string so
+     * the detail stays structured-cloneable for the cross-tab hop. It is the field a
+     * per-vendor budget model needs and the one that would be awkward to retrofit.
      */
-    private static loopEndDetail;
+    private loopEndDetail;
     /**
      * Swap in a new agent's configuration. Called by OrchestratingDriver before
      * each specialist turn so the shared driver runs with the right tools and prompt.
@@ -1445,6 +1607,7 @@ export declare class ChatDriver extends EventTarget implements AiDriver {
      */
     getSubAgentFailure(): {
         reason: SubAgentFailureReason;
+        budget?: BudgetDetail;
     } | undefined;
     /**
      * Record a sub-agent failure reason (first one wins). No-op for top-level
@@ -1667,6 +1830,22 @@ export declare interface ChatDriverConfig {
      * it defaults to {@link NOOP_ACTIVITY_BUS} so no `BroadcastChannel` is ever opened.
      */
     activityBus?: ActivityBus;
+    /**
+     * Transcript copy appended when the AI-spend budget wall is hit (GENC-1464).
+     * Defaults to `DEFAULT_BUDGET_EXHAUSTED_MESSAGE`.
+     *
+     * The assistant element already lets a host override the blocked **banner**
+     * via `setBlocked(true, reason)`; without this the transcript **bubble** stayed
+     * on the default, so a white-labelled host got its own copy in the banner and
+     * the shipped default directly below it. Passing the same effective copy here
+     * keeps the two surfaces saying one thing.
+     *
+     * Deliberately a driver-config field rather than something read off a chat
+     * config: `ChatDriver` has no `chatConfig` and is used standalone (see
+     * `chat-driver-node`), so threading one in would be a much larger and less
+     * reversible change.
+     */
+    budgetExhaustedMessage?: string;
 }
 
 export { ChatFallback }
@@ -1698,6 +1877,31 @@ declare type ChatInteractionEventsMap = {
 
 export { ChatToolChoice }
 
+/**
+ * `aria-describedby` for the composer's textarea, send button and attach button:
+ * the banner's id whenever the banner has something to say, otherwise `null` (so
+ * the attribute is omitted rather than emitted empty).
+ *
+ * Keyed on `bannerVisible`, NOT on `blocked`, and that is the point. The
+ * PARTIAL state — some vendor walled, composer still live — is the state this
+ * feature exists to create, and it was the one state with no accessible
+ * explanation at all: `aria-disabled` and `aria-label` bind only on `blocked`, and
+ * a live composer keeps the host's own placeholder, so a screen-reader user
+ * arriving at the textarea heard "Type a message" with no hint that the next turn
+ * might be refused. The banner's `role="status"` announces the text when it
+ * CHANGES; this is what makes the same explanation reachable afterwards, on
+ * demand, from the control it is about.
+ *
+ * Applied in the fully blocked state too, where it is additive: the `aria-label`
+ * there states the reason as the control's name, and this restates it as its
+ * description for the send/attach buttons, which carry neither.
+ *
+ * Exported for the unit test that pins it; not part of the element API.
+ *
+ * @internal
+ */
+export declare const composerDescribedBy: (x: FoundationAiAssistant) => string | null;
+
 /** A model used during a finalized cost session. */
 export declare interface CostSessionModelEntry {
     model: string;
@@ -1892,6 +2096,24 @@ export declare interface FallbackAgentConfig extends BaseAgentConfig {
     description?: never;
 }
 
+/**
+ * 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 declare function formatBlockedReason(budget?: Extract<ChatDriverResult, {
+    reason: 'done';
+}>['budget'], vendor?: AIProviderType): string | undefined;
+
 /**
  * Foundation AI Assistant component.
  *
@@ -2019,13 +2241,22 @@ export declare class FoundationAiAssistant extends GenesisElement {
     get busy(): boolean;
     /**
      * 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();
+    /**
+     * 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;
     /**
      * Re-runs `agentsChanged` if the live `agents` array no longer matches the
      * fingerprint of the currently installed driver. Used to apply swaps that
@@ -2096,6 +2327,356 @@ export declare class FoundationAiAssistant extends GenesisElement {
      */
     get restoring(): boolean;
     set restoring(value: boolean);
+    /**
+     * 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(): boolean;
+    set blocked(value: boolean);
+    /**
+     * 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(): readonly AIProviderType[];
+    /**
+     * 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[];
+    /**
+     * Whether this specific vendor's budget is walled — regardless of whether any
+     * other vendor still has headroom.
+     *
+     * @beta
+     */
+    isVendorBlocked(vendor: AIProviderType): boolean;
+    /**
+     * 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;
+    /**
+     * 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
+     */
+    private get relevantBlockedVendors();
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): boolean;
+    /**
+     * 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;
+    set blockedReason(value: string | null);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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(): string;
+    /**
+     * 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();
     /**
      * 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
@@ -2216,6 +2797,8 @@ export declare class FoundationAiAssistant extends GenesisElement {
     private driverCleanup?;
     private loadingTimer;
     private unsubBus?;
+    /** Unsubscribe handle for the `tool-loop-end` budget latch (GENC-1464). */
+    private _unsubBudgetLatch?;
     /** Unsubscribe handle for the provider-registry change listener (observable registries only). */
     private unsubProviderRegistry?;
     /** Unsubscribe handle for {@link (AssistantAppSettingsProvider:interface).subscribe}. */
@@ -3051,6 +3634,17 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
      * user stops. Reset at the start of each `sendMessage`.
      */
     private cancelled;
+    /**
+     * Whether the CURRENT turn's user message has reached the inner driver's
+     * history. False through the pre-first-turn classify (where the only echo of
+     * the message is an optimistic `history-updated` dispatch), true from the
+     * moment `chatDriver.sendMessage` is entered — including through every later
+     * handoff classify. Read by the budget-wall catch in `sendMessage` to decide
+     * whether `reportBudgetExhausted` must append the message itself: appending
+     * it when already appended duplicated it; not appending it when unappended
+     * made it vanish. Reset at the top of each `runOrchestratedTurn`.
+     */
+    private userMessageAppended;
     /**
      * Sticky user pick from the picker (or the host's `setAgent` API). Only
      * changes on explicit user action. Survives flow completion: when a stateful
@@ -3084,6 +3678,8 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
         maxTurnSnapshots?: number;
         /** Activity bus passed through to the inner ChatDriver (browser host injects the singleton). */
         activityBus?: ActivityBus;
+        /** Budget-wall transcript copy, passed through to the inner ChatDriver (GENC-1464). */
+        budgetExhaustedMessage?: string;
     });
     resolveInteraction(interactionId: string, result: unknown): void;
     getInteractionContext(interactionId: string): InteractionContext | undefined;
@@ -3116,6 +3712,7 @@ export declare class OrchestratingDriver extends EventTarget implements AiDriver
     getExternalDiagnostics(): ReadonlyArray<DiagnosticEntry>;
     getSuggestions(history: ChatMessage[], prompt: string, count: number, allAgentInfo?: AllAgentSummary[]): Promise<string[]>;
     sendMessage(input: string, attachments?: ChatAttachment[]): Promise<ChatDriverResult>;
+    private runOrchestratedTurn;
     continueFromHistory(transientPrimer?: ChatMessage[]): Promise<ChatDriverResult>;
     /** {@inheritDoc AiDriver.primeRestoredAgentState} */
     primeRestoredAgentState(snapshots: Record<string, unknown>): void;