@genesislcap/ai-assistant 15.6.2 → 15.7.0

package/dist/custom-elements.json

@@ -1728,9 +1728,20 @@
                 "text": "boolean"
               },
               "privacy": "private",
-              "description": "True when a new send must be refused: a turn is running (`busy`), a page-reload\nrestore is loading history that would clobber it (`restoring`), or a manual\ncompaction is rewriting history (`compacting`). Mirrors the composer's\n`?disabled` gate so a **programmatic** `send`/`submitMessage` (e.g. a host's\ncustom input while the built-in composer is hidden) can't slip past it and have\nits message wiped when the restored/compacted history lands (GENC-1351 §6).",
+              "description": "True when a new send must be refused: a turn is running (`busy`), a page-reload\nrestore is loading history that would clobber it (`restoring`), a manual\ncompaction is rewriting history (`compacting`), or a backend condition has\nlocked the assistant outright (`blocked` — e.g. an exhausted AI budget).\nMirrors the composer's `?disabled` gate so a **programmatic**\n`send`/`submitMessage` (e.g. a host's custom input while the built-in composer\nis hidden) can't slip past it and have its message wiped when the\nrestored/compacted history lands (GENC-1351 §6).",
               "readonly": true
             },
+            {
+              "kind": "method",
+              "name": "sendRefusalReason",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "description": "Why a programmatic send was refused, for `submitMessage`'s `errors`. A\nbackend block is called out distinctly because — unlike the transient\n\"busy\" cases — waiting and retrying will never clear it, and a caller\nlooping on \"Assistant is busy\" would spin forever."
+            },
             {
               "kind": "method",
               "name": "applyDeferredAgentsSwap",
@@ -1845,6 +1856,142 @@
               },
               "description": "Whether a page-reload restore is in flight (GENC-1351 §6). On the session\nstore (like `compacting`) so the \"Restoring…\" view + input-disable stay in\nsync across pop-in/out. Gating input while true prevents a mid-load send from\nbeing clobbered when the restored history loads."
             },
+            {
+              "kind": "field",
+              "name": "blocked",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Whether the assistant is blocked by a backend condition and cannot send —\ntoday, an exhausted AI-spend budget (GENC-1464). While true the composer is\ndisabled, `send`/`submitMessage` refuse, suggestions stop being fetched, and\na persistent banner (`part=\"blocked-banner\"`) sits above the composer\nexplaining why. The transcript stays visible and scrollable throughout —\nunlike `compacting` and `restoring`, this does not replace the conversation.\n\n**Latched.** Nothing in the element clears it: not a new turn, not \"Clear\"\n/ \"New chat\", not a pop-in/out. It stays set until the host writes\n`false` — because nothing the user can do inside the assistant refills a\nbudget. Hosts typically set it from their own pre-flight budget check on\nmount, and clear it once a later check shows headroom again.\n\nThe driver also latches it automatically when a turn ends with the\n`'budget-exhausted'` failure reason — off the `tool-loop-end` activity bus\n(which also covers a sub-agent wall, a turn this element did not start, and\nan element swapped in mid-turn) and off the driver's return value (which\ncovers a wall hit during multi-agent classification, where no tool loop ran\nand so no bus event fires). So a host that does no pre-flight at all still\ngets a correct locked UI the moment the first 402 lands. The bus topic is\ntab-scoped, so a wall hit in a popped-out window latches the main window\ntoo — correct for a shared spend cap.\n\n**Lifetime — read this before relying on it as your source of truth.** The\nlatch is in-memory and per-`stateKey`:\n\n- It does **not** survive `switchSession`. Switching away tears the outgoing\n  session's store down entirely, so switching back yields a fresh, unblocked\n  store.\n- It does **not** survive a page reload. It is deliberately absent from the\n  persisted session snapshot: the snapshot is long-lived, so a persisted\n  latch would outlive an out-of-band budget raise with no in-element way to\n  clear it — a stale lock is worse than re-deriving the state.\n\nThe durable source of truth is therefore the **host's pre-flight**, which\nshould run on mount and on every session switch. See\n`docs/migration-GENC-1464.md` §\"How to adopt\", Option B."
+            },
+            {
+              "kind": "field",
+              "name": "reachableVendors",
+              "type": {
+                "text": "readonly AIProviderType[]"
+              },
+              "description": "The distinct vendors the registry can currently reach, from the provider\nstatuses this element already loads on connect and refreshes on every\nobservable-registry change.\n\nThis is the element's answer to \"which vendor would the next turn use\" — a\nquestion that has **no** correct answer and deliberately gets no API. The\nprovider is resolved per turn AND per agent: `activeProviderInput` may be an\nasync function of the turn's context, an orchestrated turn picks its agent\nwith an LLM `classify()` call, and sub-agents resolve their own providers.\nAny pre-turn \"peek\" would therefore be a guess that is wrong precisely on the\nmulti-agent hosts per-vendor budgets exist for.\n\nAsking instead which vendors are REACHABLE is answerable, synchronous, and\nfree — and it is enough: the composer must stay live while any reachable\nvendor has headroom, and must lock when none does. It also makes vendor-switch\nrecovery a derivation rather than a mutation: a host that swaps its registry\nto another vendor fires the observable, the statuses reload, the walled vendor\ndrops out of this set, and `blocked` goes false with every latch left intact.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "blockedVendors",
+              "type": {
+                "text": "readonly AIProviderType[]"
+              },
+              "description": "Vendors currently walled by the AI-spend budget, in the order they were\nwalled. Empty for a host that never adopts the per-vendor API.\n\nMay include a vendor this registry cannot reach — either because the registry\nmoved on after the wall was latched, or because a 402's\n`otherVendorAvailable: false` walls every vendor the proxy meters (which is\nwhat that verdict is a statement about; see\nFoundationAiAssistant.latchBlockedFrom). Neither costs anything\ninternally — FoundationAiAssistant.blocked asks only about the\nreachable set, and the banner reads the reachability-filtered\nFoundationAiAssistant.relevantBlockedVendors — but a host rendering\nthis list itself should filter it against its own registry.\n\nRead-only on purpose: a settable array would let a host write a partial list\nand silently orphan the per-vendor banner copy.\nFoundationAiAssistant.setVendorBlocked is the write path.",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "isVendorBlocked",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "vendor",
+                  "type": {
+                    "text": "AIProviderType"
+                  }
+                }
+              ],
+              "description": "Whether this specific vendor's budget is walled — regardless of whether any\nother vendor still has headroom."
+            },
+            {
+              "kind": "method",
+              "name": "isVendorSwept",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "boolean"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "vendor",
+                  "type": {
+                    "text": "AIProviderType"
+                  }
+                }
+              ],
+              "description": "Whether this vendor's wall came from the sweep alone — see the slice's `sweptVendors`."
+            },
+            {
+              "kind": "method",
+              "name": "setVendorBlocked",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "vendor",
+                  "type": {
+                    "text": "AIProviderType"
+                  }
+                },
+                {
+                  "name": "blocked",
+                  "type": {
+                    "text": "boolean"
+                  }
+                },
+                {
+                  "name": "reason",
+                  "optional": true,
+                  "type": {
+                    "text": "string | null"
+                  }
+                }
+              ]
+            },
+            {
+              "kind": "field",
+              "name": "blockedReason",
+              "type": {
+                "text": "string | null"
+              },
+              "description": "Explanation shown in the blocked banner, or `null` for the element's default\ncopy. Only meaningful while FoundationAiAssistant.blocked is true;\nsetting `blocked = false` clears it.\n\nWritable, and symmetric with every other store-backed accessor on this\nclass: writing it re-latches with the CURRENT `blocked` value, so it changes\nthe copy without disturbing the flag. Assigning `null` clears the\nexplanation while staying blocked (the banner falls back to the default\ncopy). FoundationAiAssistant.setBlocked remains the way to write\nboth in one atomic action."
+            },
+            {
+              "kind": "method",
+              "name": "setBlocked",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "blocked",
+                  "type": {
+                    "text": "boolean"
+                  }
+                },
+                {
+                  "name": "reason",
+                  "optional": true,
+                  "type": {
+                    "text": "string | null"
+                  }
+                }
+              ],
+              "description": "Block or unblock the assistant, optionally with custom banner copy.\nEquivalent to the FoundationAiAssistant.blocked setter, plus the\nreason in one atomic write.\n\nBlocking writes the **vendor-agnostic** block — what a host with one budget\npot means — and does not populate\nFoundationAiAssistant.blockedVendors. Unblocking clears the\nper-vendor walls as well, so a host asserting \"the wall is gone\" after its\nown pre-flight cannot be silently overruled by a driver latch it never saw."
+            },
+            {
+              "kind": "field",
+              "name": "transcriptBudgetExhaustedMessage",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "description": "Copy the driver writes into the TRANSCRIPT when a turn hits the budget wall.\n\nA host-set `blockedReason` still wins, so a white-labelled host does not read\nits own explanation in the banner and the shipped default directly below it —\nthat is the whole reason the driver takes this at all.\n\nWhat it deliberately is NOT is\nFoundationAiAssistant.effectiveBlockedReason. That getter\ncomposes advice — `\"…Switch to Gemini to keep going.\"` — which is true only\nwhile that vendor has headroom, and the transcript is a permanent record. The\ndriver reads this once at CONSTRUCTION, and `getOrCreateDriver` keys on the\nagents list, so an agents swap *after* a wall re-runs `createDriver` and would\nfreeze that sentence into every later turn's bubble. Reading the latch's own\ncopy instead is structurally incapable of carrying the advice: the only\nwriter of `blockedReason` is the vendor-agnostic branch of\n`latchBlockedFrom`, whose `formatBlockedReason(budget)` form has no switch\nclause. Per-vendor copy lives in `blockedVendorReasons` and reaches the\nbanner alone.",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "pinnedAgentName",
@@ -2375,6 +2522,15 @@
               },
               "privacy": "private"
             },
+            {
+              "kind": "field",
+              "name": "_unsubBudgetLatch",
+              "type": {
+                "text": "() => void | undefined"
+              },
+              "privacy": "private",
+              "description": "Unsubscribe handle for the `tool-loop-end` budget latch (GENC-1464)."
+            },
             {
               "kind": "field",
               "name": "unsubProviderRegistry",
@@ -4475,8 +4631,8 @@
           "type": {
             "text": "readonly string[]"
           },
-          "default": "[\n  'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',\n  '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',\n  'Timestamps are millisecond-resolution; entries that share the same millisecond are ordered by a fixed kind rank (event, then turn, then message), which is a heuristic and may not reflect exact causal order within that millisecond — e.g. a user message and the turn it triggered, or a final assistant message and its turn.end event, can appear in either order depending on whether they landed in the same millisecond. Read the logical structure of a turn rather than over-interpreting the micro-ordering of co-timestamped entries of different kinds.',\n  \"kind:'message' — the conversation. `role` is user/assistant/tool/system-event/synthetic-user; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message LLM usage, where `inputTokens` is the WHOLE prompt for that request and `cacheReadTokens`/`cacheWriteTokens` BREAK IT DOWN rather than add to it — uncached input is `inputTokens` minus those two, and adding the cache fields to `inputTokens` counts the prompt twice. The cache fields are absent on providers that report no cache split (Gemini reports reads only, since implicit caching bills no write) and on messages persisted before they existed, so read them as 0 when missing. Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a large token count at a small cost means the prompt was mostly cache hits. `externalCostUsd` is any non-LLM cost a widget reported for its own external service calls (folded into the session cost total alongside `cost`). On model-produced assistant messages, `model` is the concrete model id that generated it (e.g. 'gemini-2.5-flash-lite') and `providerName` is the registry slot it resolved under (e.g. a tier name like 'high'/'low', or the default); together they attribute the message — and any tool calls it carries — to an exact model even across a mid-session vendor/tier switch, where one slot name can map to different models before and after the switch. Both are undefined on any entry that is NOT an LLM response: non-assistant roles (user/tool/system-event) and 'synthetic-user' echoes; assistant interaction/widget entries (empty content carrying an `interaction` — a rendered widget, not a model turn); driver-authored assistant fallbacks (the timeout, repeated-malformed-call, and empty-response apology messages); and messages restored from a session persisted before these fields existed. One partial case: on a genuine model turn whose provider exposes no `getStatus` (or reports no model), `providerName` is still set but `model` alone is undefined. A 'synthetic-user' message is a display-only echo of an interaction outcome (e.g. the answer a widget reported): it renders on the user's side of the chat and `agentName` is the agent that created it, but it is never sent to the LLM — so it has no matching 'turn' and the model learns the outcome only from the corresponding tool result.\",\n  \"Sub-agent messages appear inline. When a tool delegates to a sub-agent (via `requestSubAgent`), the sub-agent's whole conversation — its own assistant/tool messages, each with their own `content`/`thinking`/`toolCalls`/`toolResult` and per-message `model`/`providerName`/`inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheWriteTokens`/`cost` — is hoisted into the timeline as ordinary kind:'message' entries, interleaved by timestamp right after the tool call that spawned them (so you read the delegation top-to-bottom). A hoisted entry is marked: `subAgentDepth` is its delegation depth (1 for a sub-agent, 2 for a sub-agent's sub-agent, …), `subAgentOf` is the id of the parent tool call that spawned it (correlates it back even when two sub-agents run in one parent turn), `subAgentName` is the sub-agent's own name, and `agentName` is rewritten to a `\\\"<parent> › <sub-agent>\\\"` breadcrumb (composing when nested, e.g. `\\\"UI Builder › Planner › Grounding\\\"`). The sub-agent's per-LLM-call snapshots also surface as kind:'turn' entries with an N-M `turnIndex`, and subagent.started/completed (or subagent.failed) events bracket the run. Per-message `cost` on hoisted entries is already part of the session total (it is summed from the un-flattened history), so summing the top-level timeline does NOT double-count.\",\n  \"kind:'turn' — one LLM call. `turnIndex` is a string: a top-level turn is the bare counter ('0', '1', …); a sub-agent's turns are numbered under the parent turn that activated them ('3-1', '3-2', …, and a nested sub-agent contributes '3-2-1', …), and `agentName` names the agent that ran the turn. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.\",\n  \"kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.\",\n  \"kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.\",\n  \"Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.\",\n  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',\n  'Sub-agent meta events: a sub-agent\\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `\"<parent> › <sub-agent>\"` breadcrumb that composes when nested (e.g. `\"UI Builder › Planner › Grounding\"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\\'s span.',\n  \"`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, token usage, session cost), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.\",\n  'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it.',\n]",
-          "description": "Human/agent-facing guide emitted as the first key of the exported debug log,\nso whoever opens the JSON (often an AI agent) knows how to read it without\nreverse-engineering the shape. Kept here next to the event catalogue it\ndescribes so the two stay in sync."
+          "default": "[\n  'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',\n  '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',\n  'Timestamps are millisecond-resolution; entries that share the same millisecond are ordered by a fixed kind rank (event, then turn, then message), which is a heuristic and may not reflect exact causal order within that millisecond — e.g. a user message and the turn it triggered, or a final assistant message and its turn.end event, can appear in either order depending on whether they landed in the same millisecond. Read the logical structure of a turn rather than over-interpreting the micro-ordering of co-timestamped entries of different kinds.',\n  \"kind:'message' — the conversation. `role` is user/assistant/tool/system-event/synthetic-user; `agentName` says which agent produced it; `toolCalls`/`toolResult`/`interaction` carry tool and widget activity; `inputTokens`/`outputTokens`/`cost` are per-message LLM usage, where `inputTokens` is the WHOLE prompt for that request and `cacheReadTokens`/`cacheWriteTokens` BREAK IT DOWN rather than add to it — uncached input is `inputTokens` minus those two, and adding the cache fields to `inputTokens` counts the prompt twice. The cache fields are absent on providers that report no cache split (Gemini reports reads only, since implicit caching bills no write) and on messages persisted before they existed, so read them as 0 when missing. Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a large token count at a small cost means the prompt was mostly cache hits. `externalCostUsd` is any non-LLM cost a widget reported for its own external service calls (folded into the session cost total alongside `cost`). On model-produced assistant messages, `model` is the concrete model id that generated it (e.g. 'gemini-2.5-flash-lite') and `providerName` is the registry slot it resolved under (e.g. a tier name like 'high'/'low', or the default); together they attribute the message — and any tool calls it carries — to an exact model even across a mid-session vendor/tier switch, where one slot name can map to different models before and after the switch. Both are undefined on any entry that is NOT an LLM response: non-assistant roles (user/tool/system-event) and 'synthetic-user' echoes; assistant interaction/widget entries (empty content carrying an `interaction` — a rendered widget, not a model turn); driver-authored assistant fallbacks (the timeout, repeated-malformed-call, and empty-response apology messages); and messages restored from a session persisted before these fields existed. One partial case: on a genuine model turn whose provider exposes no `getStatus` (or reports no model), `providerName` is still set but `model` alone is undefined. A 'synthetic-user' message is a display-only echo of an interaction outcome (e.g. the answer a widget reported): it renders on the user's side of the chat and `agentName` is the agent that created it, but it is never sent to the LLM — so it has no matching 'turn' and the model learns the outcome only from the corresponding tool result.\",\n  \"Sub-agent messages appear inline. When a tool delegates to a sub-agent (via `requestSubAgent`), the sub-agent's whole conversation — its own assistant/tool messages, each with their own `content`/`thinking`/`toolCalls`/`toolResult` and per-message `model`/`providerName`/`inputTokens`/`outputTokens`/`cacheReadTokens`/`cacheWriteTokens`/`cost` — is hoisted into the timeline as ordinary kind:'message' entries, interleaved by timestamp right after the tool call that spawned them (so you read the delegation top-to-bottom). A hoisted entry is marked: `subAgentDepth` is its delegation depth (1 for a sub-agent, 2 for a sub-agent's sub-agent, …), `subAgentOf` is the id of the parent tool call that spawned it (correlates it back even when two sub-agents run in one parent turn), `subAgentName` is the sub-agent's own name, and `agentName` is rewritten to a `\\\"<parent> › <sub-agent>\\\"` breadcrumb (composing when nested, e.g. `\\\"UI Builder › Planner › Grounding\\\"`). The sub-agent's per-LLM-call snapshots also surface as kind:'turn' entries with an N-M `turnIndex`, and subagent.started/completed (or subagent.failed) events bracket the run. Per-message `cost` on hoisted entries is already part of the session total (it is summed from the un-flattened history), so summing the top-level timeline does NOT double-count.\",\n  \"kind:'turn' — one LLM call. `turnIndex` is a string: a top-level turn is the bare counter ('0', '1', …); a sub-agent's turns are numbered under the parent turn that activated them ('3-1', '3-2', …, and a nested sub-agent contributes '3-2-1', …), and `agentName` names the agent that ran the turn. `systemPrompt` and `toolNames` are what the model saw. A systemPrompt of '<repeated — identical to turn N>' was byte-identical to turn N and de-duplicated; the full prompt is shown whenever it changes (often because a stateful agent advanced), so prompt evolution is visible.\",\n  \"kind:'turn'.`agentSnapshot` — the active agent's own view of its internal state, captured at that turn. An agent opts into this by exposing a `getDebugSnapshot()` that returns JSON-serializable per-state info; stateful/flow agents wire it automatically, so you can watch a flow advance turn-by-turn (e.g. current step, cursor, collected fields, pending changes). Absent for agents that don't expose one.\",\n  \"kind:'event' — a meta/lifecycle event. `type` names it (see below); `detail` carries structured data. `detail.placement` is the emitting UI instance: 'bubble' (collapsed), 'panel' (popped-out), or 'standalone'.\",\n  \"Each 'event' also has an `importance`: 'high' (failures/limits — turn.error, tool.failed, subagent.failed, file.read-failed, suggestions.failed, context.threshold-crossed), 'normal' (session flow — connects, turns, retries, handoffs, agent/provider changes, interactions, sub-agent start/complete), or 'low' (skippable UI/bookkeeping noise — panel.toggled, attachment.added, driver.wired/unwired, context.updated, context.condensed). To skim, ignore importance:'low'; to triage a failure, filter to importance:'high' then read the nearby messages and turns. A 'high' turn.error is often preceded by one or more 'normal' turn.retry events for the same reason — read them together to see how many attempts were made before bailing. 'message' and 'turn' entries carry no importance — they are the substance, always read them.\",\n  'Event types: assistant.connected/disconnected (mount + placement + whether the session was created or restored), assistant.popout/popin (window placement), driver.created/wired/unwired (which driver is live and why it stops/starts responding across a popout), state.changed (idle↔loading), turn.start/turn.end (turn boundary; turn.end carries durationMs), turn.retry (a recoverable in-turn retry — detail.reason plus attempt/maxAttempts; for malformed calls also finishMessage; for empty responses also the provider finishReason + thoughtsTokens + parts breakdown), turn.error (a turn failed or hit a guardrail — detail.reason is one of exception/malformed-function-call/empty-response/unknown-tool-limit/max-iterations/response-truncated/refusal/budget-exhausted, plus reason-specific diagnostics: attempts (for empty-response also finishReason + thoughtsTokens + a parts breakdown, distinguishing a thinking-only STOP from a truly empty turn), finishMessage, for response-truncated the model + maxTokens + outputTokens + tools, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, for budget-exhausted the budgetUsd + spentUsd figures reported by the proxy plus the resolved vendor, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout/response_truncated/refusal/budget_exhausted; budget_exhausted is terminal for the PARENT turn too — the parent stops rather than calling the model again into the same wall), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',\n  'Sub-agent meta events: a sub-agent\\'s own turn.retry/turn.error/tool.failed/tool.unresolved events are merged into this same timeline, tagged with `detail.subAgent` — a `\"<parent> › <sub-agent>\"` breadcrumb that composes when nested (e.g. `\"UI Builder › Planner › Grounding\"`) — and interleaved by their original timestamps within the subagent.started→completed/failed bracket. These are the per-attempt/per-failure signals that do NOT appear among the sub-agent\\'s (hoisted) messages: a malformed/empty attempt that gets retried produces no message, and the stale-vs-hallucinated split and streak counts live only on the event. A sub-agent\\'s high-volume, message-derivable events (turn.start/turn.end, provider.selected, context.updated) are intentionally NOT merged — read its hoisted messages for model/tokens/cost and turn-by-turn activity, and the bracketing subagent.* events for the run\\'s span.',\n  \"`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, token usage, session cost), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.\",\n  'To debug a failure: find the last turn.error or tool.failed, then read upward for the user message, the turn(s), and the agent/provider/state events that led into it.',\n]",
+          "description": "Human/agent-facing guide emitted as the first key of the exported debug log,\nso whoever opens the JSON (often an AI agent) knows how to read it without\nreverse-engineering the shape. Kept here next to the event catalogue it\ndescribes — but proximity alone demonstrably did NOT keep the two in sync\n(`refusal` was missing from both reason lists for a whole release), so\n`debug-event-log.test.ts` now asserts that every `TurnFailureReason` and every\n`SubAgentFailureReason` is named here, and fails the build when one is added\nwithout a matching sentence. Enumerations below read as exhaustive and WILL be\ntrusted by an agent reading the JSON — keep them so."
         }
       ],
       "exports": [
@@ -7254,10 +7410,10 @@
               "kind": "field",
               "name": "subAgentFailure",
               "type": {
-                "text": "{ reason: SubAgentFailureReason } | undefined"
+                "text": "{ reason: SubAgentFailureReason; budget?: BudgetDetail } | undefined"
               },
               "privacy": "private",
-              "description": "Set when a sub-agent's tool loop ends without `completeSubAgent` being\ncalled. Read by the parent's `invokeSubAgent` to build the `{ ok: false }`\nbranch of `requestSubAgent`. Only ever set when `isSubAgent` is true."
+              "description": "Set when a sub-agent's tool loop ends without `completeSubAgent` being\ncalled. Read by the parent's `invokeSubAgent` to build the `{ ok: false }`\nbranch of `requestSubAgent`. Only ever set when `isSubAgent` is true.\n\n`budget` rides along on a `'budget_exhausted'` failure so the parent inherits\nthe child's ATTRIBUTION, not just the fact of a wall — see\n`budgetWallDetail`."
             },
             {
               "kind": "field",
@@ -7538,6 +7694,46 @@
               "description": "Injected activity bus; defaults to a no-op off-browser (Node/tests/headless).",
               "default": "activityBus"
             },
+            {
+              "kind": "field",
+              "name": "budgetExhaustedMessage",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "private",
+              "readonly": true,
+              "description": "Transcript copy for a budget wall — see `ChatDriverConfig.budgetExhaustedMessage`.",
+              "default": "budgetExhaustedMessage"
+            },
+            {
+              "kind": "field",
+              "name": "budgetExhaustedThisTurn",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Set the moment a budget wall is observed anywhere in this turn — this\ndriver's own 402, or a sub-agent's (which surfaces here only as a\n`'budget_exhausted'` tool result). Read at the top of the tool loop to end\nthe turn before issuing another model call that would hit the same wall.\nReset per turn alongside the other per-turn counters."
+            },
+            {
+              "kind": "field",
+              "name": "budgetWallDetail",
+              "type": {
+                "text": "BudgetDetail | undefined"
+              },
+              "privacy": "private",
+              "description": "The refusing vendor's own attribution for the wall `budgetExhaustedThisTurn`\nrecords, when it was knowable. Kept SEPARATE from the flag rather than\nreplacing it: a figure-less 402 from a transport no vendor claims yields no\ndetail at all (`budgetDetailOf` returns `undefined`), and folding the two\nwould make that case stop ending the turn.\n\nIt matters most for a sub-agent's wall. The child can sit on a different\nvendor from its parent — `applyAgent` reads `config.provider` — so without\nthis the parent's short-circuit reports `lastResolvedProvider`, i.e. the one\nvendor that did NOT refuse. Under a mixed registry that walls Gemini because\nan Anthropic child 402'd, and if those are the only two reachable vendors the\nhost then derives `blocked` and locks a composer that still had headroom."
+            },
+            {
+              "kind": "field",
+              "name": "budgetWallViaSubAgent",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether this turn's budget wall came from a SUB-AGENT rather than this\ndriver's own request. Decides whether `lastResolvedProvider` is a valid\nattribution fallback: for an own wall it is the refusing vendor, for a\nchild's wall it is the parent's vendor — the one known NOT to have refused.\nReset per turn alongside `budgetWallDetail`."
+            },
             {
               "kind": "method",
               "name": "dispose",
@@ -7607,6 +7803,13 @@
                   "type": {
                     "text": "TurnFailureReason"
                   }
+                },
+                {
+                  "name": "budget",
+                  "optional": true,
+                  "type": {
+                    "text": "BudgetDetail"
+                  }
                 }
               ],
               "description": "Build the `done` loop result, carrying the typed failure reason when the turn\nbailed (PTC-0). The discriminant stays `'done'` either way — the same value a\nclean turn returns — so consumers matching on `reason === 'done'` are unchanged;\n`failureReason` is simply present on a failure and absent on success. Omitted\n(rather than set to `undefined`) so a happy-path result stays byte-identical to\nthe historical `{ reason: 'done' }`."
@@ -7635,10 +7838,9 @@
               "kind": "method",
               "name": "loopEndDetail",
               "privacy": "private",
-              "static": true,
               "return": {
                 "type": {
-                  "text": "{ failureReason: TurnFailureReason } | undefined"
+                  "text": "| {\n        failureReason: TurnFailureReason;\n        vendor?: AIProviderType;\n        budget?: BudgetDetail;\n      }\n    | undefined"
                 }
               },
               "parameters": [
@@ -7649,7 +7851,7 @@
                   }
                 }
               ],
-              "description": "Build the `tool-loop-end` event detail for a turn's result. A failure carries a\n`{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,\nkept byte-identical so subscribers see exactly what they always have."
+              "description": "Build the `tool-loop-end` event detail for a turn's result. A failure carries a\n`{ failureReason }` detail; a clean turn emits `undefined` — the historical shape,\nkept byte-identical so subscribers see exactly what they always have.\n\nA budget failure additionally carries `vendor` — the concrete vendor\n(`'anthropic'`/`'gemini'`) the walled turn resolved to, which the driver knows\nand used to discard. Optional and additive: a subscriber reading only\n`failureReason` is unaffected, a non-budget failure still emits the historical\n`{ failureReason }` with no `vendor` key, and the value is a plain string so\nthe detail stays structured-cloneable for the cross-tab hop. It is the field a\nper-vendor budget model needs and the one that would be awkward to retrofit."
             },
             {
               "kind": "method",
@@ -7829,7 +8031,7 @@
               "name": "getSubAgentFailure",
               "return": {
                 "type": {
-                  "text": "{ reason: SubAgentFailureReason } | undefined"
+                  "text": "{ reason: SubAgentFailureReason; budget?: BudgetDetail } | undefined"
                 }
               },
               "description": "Returns the typed failure recorded when a sub-agent run ended without\n`completeSubAgent`, if any. Called by a parent `ChatDriver` after running\nthis instance as a sub-agent."
@@ -7849,6 +8051,13 @@
                   "type": {
                     "text": "SubAgentFailureReason"
                   }
+                },
+                {
+                  "name": "budget",
+                  "optional": true,
+                  "type": {
+                    "text": "BudgetDetail"
+                  }
                 }
               ],
               "description": "Record a sub-agent failure reason (first one wins). No-op for top-level\nagents, so loop-exit sites can call it unconditionally. The parent reads\nthis via `getSubAgentFailure()` and emits the `subagent.failed` meta event\nunder its *own* session — see `invokeSubAgent`. (A child sub-agent runs\nunder a separate session key, so recording here would orphan the event off\nthe user-visible debug-log timeline.)"
@@ -8867,7 +9076,7 @@
               },
               "privacy": "private",
               "readonly": true,
-              "default": "new ChatDriver(providerRegistry, {\n      maxToolIterations: options.maxToolIterations,\n      maxFoldOperations: options.maxFoldOperations,\n      maxTurnSnapshots: options.maxTurnSnapshots,\n      sessionKey: this.sessionKey,\n      activityBus: options.activityBus,\n    })"
+              "default": "new ChatDriver(providerRegistry, {\n      maxToolIterations: options.maxToolIterations,\n      maxFoldOperations: options.maxFoldOperations,\n      maxTurnSnapshots: options.maxTurnSnapshots,\n      sessionKey: this.sessionKey,\n      activityBus: options.activityBus,\n      budgetExhaustedMessage: options.budgetExhaustedMessage,\n    })"
             },
             {
               "kind": "field",
@@ -8941,6 +9150,16 @@
               "default": "false",
               "description": "Set by `cancel()` for the duration of a `sendMessage` run. Breaks the\nhandoff loop so we don't classify or start another agent turn after the\nuser stops. Reset at the start of each `sendMessage`."
             },
+            {
+              "kind": "field",
+              "name": "userMessageAppended",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "Whether the CURRENT turn's user message has reached the inner driver's\nhistory. False through the pre-first-turn classify (where the only echo of\nthe message is an optimistic `history-updated` dispatch), true from the\nmoment `chatDriver.sendMessage` is entered — including through every later\nhandoff classify. Read by the budget-wall catch in `sendMessage` to decide\nwhether `reportBudgetExhausted` must append the message itself: appending\nit when already appended duplicated it; not appending it when unappended\nmade it vanish. Reset at the top of each `runOrchestratedTurn`."
+            },
             {
               "kind": "field",
               "name": "pinnedAgentName",
@@ -9199,6 +9418,31 @@
                 }
               ]
             },
+            {
+              "kind": "method",
+              "name": "runOrchestratedTurn",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Promise<ChatDriverResult>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "input",
+                  "type": {
+                    "text": "string"
+                  }
+                },
+                {
+                  "name": "attachments",
+                  "optional": true,
+                  "type": {
+                    "text": "ChatAttachment[]"
+                  }
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "continueFromHistory",

package/dist/dts/channel/ai-activity-channel.d.ts

@@ -1,4 +1,4 @@
-import type { TurnFailureReason } from '@genesislcap/foundation-ai';
+import type { AIProviderType, TurnFailureReason } from '@genesislcap/foundation-ai';
 /**
  * Event map for the AI activity bus.
  *
@@ -68,9 +68,59 @@ export 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

package/dist/dts/channel/ai-activity-channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-activity-channel.d.ts","sourceRoot":"","sources":["../../../src/channel/ai-activity-channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,qBAAqB;IACpC,2FAA2F;IAC3F,YAAY,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACtC,iFAAiF;IACjF,WAAW,EAAE,SAAS,CAAC;IACvB,mJAAmJ;IACnJ,aAAa,EAAE,SAAS,CAAC;IACzB,wJAAwJ;IACxJ,YAAY,EAAE,SAAS,CAAC;IACxB;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,EAAE,SAAS,CAAC;IAC7B;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,eAAe,EAAE;QAAE,aAAa,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,SAAS,CAAC;IACnE;;;;;;;;;;;OAWG;IACH,uBAAuB,EAAE,SAAS,CAAC;IACnC;;;;;OAKG;IACH,sBAAsB,EAAE,SAAS,CAAC;CACnC"}
+{"version":3,"file":"ai-activity-channel.d.ts","sourceRoot":"","sources":["../../../src/channel/ai-activity-channel.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpF;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,qBAAqB;IACpC,2FAA2F;IAC3F,YAAY,EAAE;QAAE,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACtC,iFAAiF;IACjF,WAAW,EAAE,SAAS,CAAC;IACvB,mJAAmJ;IACnJ,aAAa,EAAE,SAAS,CAAC;IACzB,wJAAwJ;IACxJ,YAAY,EAAE,SAAS,CAAC;IACxB;;;;;;;;;;;;;;;;;;OAkBG;IACH,iBAAiB,EAAE,SAAS,CAAC;IAC7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,eAAe,EACX;QACE,aAAa,CAAC,EAAE,iBAAiB,CAAC;QAClC,MAAM,CAAC,EAAE,cAAc,CAAC;QACxB;;;;;;;;;WASG;QACH,MAAM,CAAC,EAAE;YACP,SAAS,CAAC,EAAE,MAAM,CAAC;YACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;YAClB,WAAW,EAAE,MAAM,CAAC;YACpB;;;;;;;;;;eAUG;YACH,MAAM,CAAC,EAAE,cAAc,CAAC;YACxB;;;;;;eAMG;YACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;SAChC,CAAC;KACH,GACD,SAAS,CAAC;IACd;;;;;;;;;;;OAWG;IACH,uBAAuB,EAAE,SAAS,CAAC;IACnC;;;;;OAKG;IACH,sBAAsB,EAAE,SAAS,CAAC;CACnC"}