@genesislcap/ai-assistant 15.19.6 → 15.20.0

package/dist/custom-elements.json

@@ -3586,6 +3586,27 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "syncContextGuard",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Push the mid-loop context guard down to the driver (GENC-1567).\n\nCalled wherever the inputs can change — the resolved provider status, and a\nfreshly built driver. A driver that never receives one simply runs without\nthe guard, which is the right default: it fires only when a real context\nwindow is known."
+            },
+            {
+              "kind": "field",
+              "name": "contextGuardPolicy",
+              "type": {
+                "text": "ContextGuardPolicy | undefined"
+              },
+              "privacy": "private",
+              "description": "Guard policy pushed to the driver, or `undefined` when the host has switched\nthe gate off — so `enabled: false` really does mean no local blocking of any\nkind, UI or mid-loop.\n\nA MARGIN, not a threshold: the driver resolves the window of the provider\neach call actually goes to. The fallback window rides along because the\ndriver cannot learn it any other way — without it, a host that knows its\nwindow while its provider does not report one had `fallbackContextLimit`\nprotecting the composer and nothing else.",
+              "readonly": true
+            },
             {
               "kind": "method",
               "name": "loadProviderStatuses",
@@ -3938,13 +3959,40 @@
               "description": "Whether persistence is currently active (on + a provider) for this session.",
               "readonly": true
             },
+            {
+              "kind": "field",
+              "name": "contextBudget",
+              "type": {
+                "text": "ResolvedContextBudget"
+              },
+              "description": "Context-headroom thresholds for the active model (GENC-1567) — the warning\nand block lines, plus the tail budget compaction aims at.\n\nThe agent's own `contextReserve` is deliberately NOT folded in here. This is\nthe AMBIENT budget, which protects any turn from any agent; a per-agent\nreserve is an additional, larger requirement checked when that agent takes\nownership of a flow, where there is a turn context to resolve its function\nform against.\n\nOverhead is read off `messages` (the Redux mirror) rather than the driver's\nown history, which the compaction plan uses. That is safe rather than sloppy:\n`estimateSystemOverhead` only looks at messages BEFORE the first usage-bearing\none, and the two lists agree completely that early — the drift between mirror\nand driver history is only ever at the tail.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "compactionPlan",
+              "type": {
+                "text": "CompactionProjection | null"
+              },
+              "description": "What compacting right now would reclaim, or `null` when it would not be\nworth it (GENC-1567). Sized against FoundationAiAssistant.contextBudget,\nso the plan aims at this model's window rather than a fixed default.\n\nReads `messages` to stay reactive as the conversation grows: the driver's\nhistory is not a tracked observable, so every consumer of this keys its\nre-evaluation off the Redux mirror.",
+              "readonly": true
+            },
+            {
+              "kind": "field",
+              "name": "contextGate",
+              "type": {
+                "text": "'ok' | 'warn' | 'blocked'"
+              },
+              "description": "How close this conversation is to the model's context window (GENC-1567).\n\n**Derived, never latched** — the opposite of FoundationAiAssistant.blocked.\nA budget wall stays set because nothing the user does fixes it; this clears\nitself the moment the conversation shrinks, which is precisely what the user\nis being asked to do. The two must not be conflated: `blocked` is also\ndeliberately preserved across `resetSession`, and a context gate obviously\nmust not survive starting a new chat.\n\n**A flow in progress is never blocked, only warned.** Machine state lives\noutside the transcript, so a stateful flow is not desynced by compaction —\nbut the summary can still drop detail the flow's own prompt leans on, and\nblocking mid-journey would strand the user between a flow they cannot finish\nand a compaction that is a poor idea right there. Letting the flow complete\nand gating on the way out is the lesser harm; the headroom reserve exists so\nthis is rare rather than routine.",
+              "readonly": true
+            },
             {
               "kind": "field",
               "name": "compactable",
               "type": {
                 "text": "boolean"
               },
-              "description": "Whether the menu's \"Compact\" action would do anything (GENC-1351 §5.7).\nDelegates to `driver.canCompact()` so the gate uses the exact same history\n`compact()` acts on — one source of truth. Also reads `messages`, purely to\nstay reactive as the conversation grows: the driver's history isn't a tracked\nobservable, so the button keys its re-evaluation off the Redux mirror.",
+              "description": "Whether the menu's \"Compact\" action would do anything (GENC-1351 §5.7,\nGENC-1567). Delegates to the driver's plan so the gate uses the exact same\nhistory `compact()` acts on, judged against the same budget — one source of\ntruth for both whether a cut is legal and whether it reclaims enough.",
               "readonly": true
             },
             {
@@ -5421,7 +5469,7 @@
           "type": {
             "text": "readonly string[]"
           },
-          "default": "[\n  'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',\n  \"`sessionUsage` is what this session spent: `costUsd` (USD, provider-reported per request and summed, cache discounts already applied) plus the four TOKEN BUCKETS — `uncachedInputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `outputTokens`. Those four are disjoint and safe to add up for a total-tokens figure; the per-message fields further down are NOT (see kind:'message'). Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a big token count against a small cost means the prompt was mostly cache hits, not a missing charge. It covers sub-agent turns and spend a compaction banked, so for the CONVERSATION it is the authoritative total: prefer it over re-summing the timeline, which can be short by whatever the ring buffers evicted. The same figures appear under `meta.context`. It is as current as the snapshot it came from: the assistant's own download stamps a fresh one, but a log stitched by another tool can carry an older one — compare `meta.timestamp` with the last timeline entry, and if it is well behind, read these totals as historical and fall back to summing the timeline. One scope caveat: it is derived from the transcript, so it excludes billed calls that produced no message (a blank or refused attempt that was retried — see kind:'turn'.`usage`). Summing the turns can therefore come out HIGHER than this, and the difference is exactly that discarded spend, not a double-count.\",\n  \"What 'session' means for those figures: the CURRENT conversation under this session key (a host-supplied per-project id, or the element id + header title when the host supplies none) — which is not necessarily everything in `timeline`. It is re-derived from the live transcript, so it spans page loads only when the chat is being remembered, and a Clear resets it to zero. `timeline` is append-only regardless: it keeps every page load and the pre-Clear conversation, with the session.cleared event as the boundary. So on a long-lived log, read these totals as the latest conversation's and the earlier sections as history — not as a total of the whole file.\",\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'.`model`/`providerName`/`provider` — which model ran that call: the concrete model id, the registry slot it resolved under (a tier name like 'high'/'low', or the default), and the vendor. Recorded per CALL, so an agent whose `provider` selector varies by state — a flow that plans on a high tier and executes on a low one — has every step attributed, including calls that produced no message. `model` is the SERVING model where the provider reports one, so a turn answered by a server-side fallback names the model that answered rather than the one requested; it always matches the `model` on the message that call produced. Absent when the provider exposes no `getStatus` and the transport stamped nothing.\",\n  \"kind:'turn'.`usage` — what that ONE call cost, in the same four-bucket + `costUsd` shape as `sessionUsage`. Absent while a call is in flight and on providers that report no usage. This is the SAME money as the message the call produced, not extra money: never add turn usage to message usage, and read a turn plus its message as one charge. Its distinct value is the calls that produced NO message — a blank or refused response is billed and then discarded before the retry, so the turn entry is the only record of that spend, and a turn with `usage` but no message after it is exactly that. `costUsd: 0` alongside a nonzero token count means the provider reported no price, not that the call was free.\",\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/provider-refused, 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, for provider-refused the kind (spend|auth) plus the upstream status and error type — the vendor refusing the ACCOUNT rather than us refusing to spend, so the remedy is a top-up or a key rotation rather than a raised cap, and the kind is the only place that distinction survives because the user-facing copy is deliberately cause-free, 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/provider_refused; budget_exhausted and provider_refused are both 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 (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), 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, contextTokens/contextLimit/contextUsagePercent for the last call, and the session totals — sessionCostUsd, sessionTokensConsumed, and the four-bucket sessionUsage lifted to the top of this log), 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  'Note the two different scopes in `meta.context`: `contextTokens` is the prompt size of the LAST call (against `contextLimit`, the model context window), while `sessionUsage`/`sessionTokensConsumed` are cumulative BILLED throughput. Every turn resends the conversation, so the cumulative figure counts each turn’s prompt again in the next turn’s and is expected to dwarf the context size — that is not double-counting.',\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]",
+          "default": "[\n  'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',\n  \"`sessionUsage` is what this session spent: `costUsd` (USD, provider-reported per request and summed, cache discounts already applied) plus the four TOKEN BUCKETS — `uncachedInputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `outputTokens`. Those four are disjoint and safe to add up for a total-tokens figure; the per-message fields further down are NOT (see kind:'message'). Each bucket bills at a different rate — cache reads a fraction of uncached input, cache writes a premium, output highest — so a big token count against a small cost means the prompt was mostly cache hits, not a missing charge. It covers sub-agent turns and spend a compaction banked, so for the CONVERSATION it is the authoritative total: prefer it over re-summing the timeline, which can be short by whatever the ring buffers evicted. The same figures appear under `meta.context`. It is as current as the snapshot it came from: the assistant's own download stamps a fresh one, but a log stitched by another tool can carry an older one — compare `meta.timestamp` with the last timeline entry, and if it is well behind, read these totals as historical and fall back to summing the timeline. One scope caveat: it is derived from the transcript, so it excludes billed calls that produced no message (a blank or refused attempt that was retried — see kind:'turn'.`usage`). Summing the turns can therefore come out HIGHER than this, and the difference is exactly that discarded spend, not a double-count.\",\n  \"What 'session' means for those figures: the CURRENT conversation under this session key (a host-supplied per-project id, or the element id + header title when the host supplies none) — which is not necessarily everything in `timeline`. It is re-derived from the live transcript, so it spans page loads only when the chat is being remembered, and a Clear resets it to zero. `timeline` is append-only regardless: it keeps every page load and the pre-Clear conversation, with the session.cleared event as the boundary. So on a long-lived log, read these totals as the latest conversation's and the earlier sections as history — not as a total of the whole file.\",\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'.`model`/`providerName`/`provider` — which model ran that call: the concrete model id, the registry slot it resolved under (a tier name like 'high'/'low', or the default), and the vendor. Recorded per CALL, so an agent whose `provider` selector varies by state — a flow that plans on a high tier and executes on a low one — has every step attributed, including calls that produced no message. `model` is the SERVING model where the provider reports one, so a turn answered by a server-side fallback names the model that answered rather than the one requested; it always matches the `model` on the message that call produced. Absent when the provider exposes no `getStatus` and the transport stamped nothing.\",\n  \"kind:'turn'.`usage` — what that ONE call cost, in the same four-bucket + `costUsd` shape as `sessionUsage`. Absent while a call is in flight and on providers that report no usage. This is the SAME money as the message the call produced, not extra money: never add turn usage to message usage, and read a turn plus its message as one charge. Its distinct value is the calls that produced NO message — a blank or refused response is billed and then discarded before the retry, so the turn entry is the only record of that spend, and a turn with `usage` but no message after it is exactly that. `costUsd: 0` alongside a nonzero token count means the provider reported no price, not that the call was free.\",\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/provider-refused/context-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, for provider-refused the kind (spend|auth) plus the upstream status and error type — the vendor refusing the ACCOUNT rather than us refusing to spend, so the remedy is a top-up or a key rotation rather than a raised cap, and the kind is the only place that distinction survives because the user-facing copy is deliberately cause-free, for context-exhausted the estimated contextTokens against the guard that stopped the turn plus the iterations reached — the driver ending a runaway tool loop at the edge of the context window rather than issuing a request the provider would reject, so the transcript survives intact and can still be compacted, 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/provider_refused/context_exhausted; budget_exhausted, provider_refused and context_exhausted are all 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 (the resolved provider for the upcoming turns — detail.provider is the registry SLOT/tier name, detail.model the concrete model behind it and detail.vendor its vendor; emitted only when the slot CHANGES, so read the per-turn `model` for the model of any given call rather than assuming the nearest event still applies), 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, contextTokens/contextLimit/contextUsagePercent for the last call, and the session totals — sessionCostUsd, sessionTokensConsumed, and the four-bucket sessionUsage lifted to the top of this log), 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  'Note the two different scopes in `meta.context`: `contextTokens` is the prompt size of the LAST call (against `contextLimit`, the model context window), while `sessionUsage`/`sessionTokensConsumed` are cumulative BILLED throughput. Every turn resends the conversation, so the cumulative figure counts each turn’s prompt again in the next turn’s and is expected to dwarf the context size — that is not double-counting.',\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."
         }
       ],
@@ -6144,6 +6192,249 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/context-tokens.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "APPROX_CHARS_PER_TOKEN",
+          "type": {
+            "text": "number"
+          },
+          "default": "4",
+          "description": "Fallback ratio for messages with no measured anchor nearby. Shared with\n`condense-history.ts`, which uses it for the same purpose (reporting bytes\nshed as tokens) — one definition so the two never drift."
+        },
+        {
+          "kind": "variable",
+          "name": "COMPACTION_SUMMARY_TOKEN_ESTIMATE",
+          "type": {
+            "text": "number"
+          },
+          "default": "1_200",
+          "description": "Allowance for the summary a compaction will produce, used when projecting the\npost-compaction size before the summarizer has run. The system prompt asks for\nconcise prose, but the length is the model's choice, so this is a ceiling\nrather than an average — a projection that under-estimates the summary is a\ngate that promises a reclaim it cannot deliver."
+        },
+        {
+          "kind": "function",
+          "name": "reachesProvider",
+          "return": {
+            "type": {
+              "text": "boolean"
+            }
+          },
+          "parameters": [
+            {
+              "name": "m",
+              "type": {
+                "text": "ChatMessage"
+              }
+            }
+          ],
+          "description": "Whether a message contributes to the provider request at all.\n\nExported because the cut logic needs the same answer: a boundary is judged by\nwhat the provider will actually see, so a display-only row sitting between an\n`assistant(toolCalls)` and its results must not be mistaken for a safe split.\n\nMirrors what the request-build chokepoint and the transports actually send:\n`system-event` / `synthetic-user` are display-only rows, and the\nreasoning/narration splits (GENC-1410, plus the legacy `thinking` flag they\nsuperseded) are skipped when building the request. Counting any of them would\ninflate every estimate against a prompt that never carries them."
+        },
+        {
+          "kind": "function",
+          "name": "isContextMeasurable",
+          "return": {
+            "type": {
+              "text": "boolean"
+            }
+          },
+          "parameters": [
+            {
+              "name": "history",
+              "type": {
+                "text": "readonly ChatMessage[]"
+              }
+            }
+          ],
+          "description": "Whether anything about this transcript's size is knowable.\n\nThe gate's \"should I have an opinion at all?\" question. Deliberately broader\nthan \"is there a USABLE anchor\": a compaction invalidates every retained\nmeasurement, which is the normal state immediately after one runs, and gating\nthe recompute on a usable anchor there meant no assignment at all — leaving a\nblocked figure latched on a conversation that had just shrunk. That is the very\ndead end this machinery exists to prevent, so the question has to be whether the\ntranscript was EVER measured, not whether the measurement is still good.\n\nWhen it is true, estimateContextTokens is the figure to use — it drops\nthe invalidated anchors itself and falls back to characters, which is still the\ntruth about the current history and, crucially, is not the stale number.\n\nA `compacted-summary` counts on its own: a conversation only reaches one by\nbeing large, and a compaction can summarise away every measured turn.\n\nWhen it is false nothing has ever reported usage, and the honest answer is to\nleave the gate inert rather than let a character estimate invent a percentage."
+        },
+        {
+          "kind": "function",
+          "name": "estimateMessageTokens",
+          "return": {
+            "type": {
+              "text": "number[]"
+            }
+          },
+          "parameters": [
+            {
+              "name": "history",
+              "type": {
+                "text": "readonly ChatMessage[]"
+              }
+            }
+          ],
+          "description": "Per-message token estimates, calibrated against measured prompt sizes wherever\nthe transcript provides them.\n\n**How the calibration works.** `inputTokens` on the message produced by a call\nis the size of that call's WHOLE prompt (the cache buckets break it down\nrather than add to it), so it covers `history[0 … i-1]`. Two consecutive\nanchors therefore bracket a segment whose exact measured cost is their\ndifference: `inputTokens[b] − inputTokens[a]` is what `history[a … b-1]` cost.\nWithin a segment the measured total is redistributed across its messages in\nproportion to their baseline estimate — segment granularity is all that is\nneeded, since compaction only ever cuts on boundaries.\n\nA non-positive delta means history SHRANK between the two calls (a compaction\nor a `condenseWhen` collapse landed in between); there is nothing to\ndistribute, so those messages keep their baseline.\n\nThe region before the first anchor keeps its baseline too: that anchor's\nmeasurement also contains the system prompt and tool definitions, which are\nnot attributable to any message — see estimateSystemOverhead."
+        },
+        {
+          "kind": "function",
+          "name": "estimateSystemOverhead",
+          "return": {
+            "type": {
+              "text": "number"
+            }
+          },
+          "parameters": [
+            {
+              "name": "history",
+              "type": {
+                "text": "readonly ChatMessage[]"
+              }
+            }
+          ],
+          "description": "Context consumed by everything that is NOT a message — the system prompt and\nthe tool definitions.\n\nDerived rather than guessed: the first measured prompt covers the messages\nbefore it plus that fixed preamble, so subtracting our estimate of those\nmessages leaves the preamble. Floored at zero, since an over-estimate of the\nearly messages would otherwise produce a negative overhead.\n\nIt matters for the gate because it is real context the user never sees in the\ntranscript, it does not shrink when history does, and on an agent with a large\ntool surface it is far from negligible."
+        },
+        {
+          "kind": "function",
+          "name": "estimateContextTokens",
+          "return": {
+            "type": {
+              "text": "number"
+            }
+          },
+          "parameters": [
+            {
+              "name": "history",
+              "type": {
+                "text": "readonly ChatMessage[]"
+              }
+            }
+          ],
+          "description": "Total estimated context for a transcript — the preamble plus every message.\n\nOn a transcript with measured anchors this lands close to the last observed\n`inputTokens` by construction; the value of computing it rather than reading\nthat figure is that it stays defined for a hypothetical history (the tail a\ncompaction would leave behind), which is what projectCompaction needs."
+        },
+        {
+          "kind": "function",
+          "name": "estimateRequestTokens",
+          "return": {
+            "type": {
+              "text": "number"
+            }
+          },
+          "parameters": [
+            {
+              "name": "storedHistory",
+              "type": {
+                "text": "readonly ChatMessage[]"
+              }
+            },
+            {
+              "name": "requestHistory",
+              "type": {
+                "text": "readonly ChatMessage[]"
+              }
+            }
+          ],
+          "description": "Estimated size of the request that will actually be SENT, given the stored\nhistory it was derived from.\n\nThe two differ by design and can differ by a lot. `condenseWhen` replaces spent\ntool payloads with short stubs, and multi-agent masking blanks another agent's\npayloads — both on a copy, leaving stored history full-fat for the UI and the\nlog. A guard that measured stored history would therefore refuse turns whose\nreal request is a fraction of the size.\n\nNaively estimating the transformed copy does NOT work either, and the reason is\nsubtle: `inputTokens` anchors live on the stored messages and measured the\nuntransformed prompt, so calibrating against them re-inflates the estimate back\nto roughly what it was before the transform — exactly the figure we were trying\nto avoid.\n\nSo the calibrated total is scaled by how much smaller the request is in\ncharacters. That keeps the accuracy the measurements buy while still reflecting\nwhat the transform removed. The preamble is carried across unscaled: the system\nprompt and tool definitions are not what condensation touches."
+        },
+        {
+          "kind": "function",
+          "name": "projectCompaction",
+          "return": {
+            "type": {
+              "text": "CompactionProjection"
+            }
+          },
+          "parameters": [
+            {
+              "name": "history",
+              "type": {
+                "text": "readonly ChatMessage[]"
+              }
+            },
+            {
+              "name": "cut",
+              "type": {
+                "text": "number"
+              }
+            },
+            {
+              "name": "summaryTokens",
+              "default": "COMPACTION_SUMMARY_TOKEN_ESTIMATE",
+              "type": {
+                "text": "number"
+              }
+            }
+          ],
+          "description": "Project the effect of compacting at `cut`, WITHOUT running the summarizer.\n\nThis is what lets a gate tell the difference between \"compaction will unblock\nyou\" and \"compaction will spend a call and leave you exactly where you are\" —\na distinction the old boolean `canCompact()` could not express, because it\nanswered only whether a legal cut existed. A legal cut that covers four short\nmessages while a large tool loop sits in the tail is legal and useless.\n\nThe system preamble is carried across unchanged: compaction removes messages,\nnever the system prompt or the tool definitions."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "APPROX_CHARS_PER_TOKEN",
+          "declaration": {
+            "name": "APPROX_CHARS_PER_TOKEN",
+            "module": "src/utils/context-tokens.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "COMPACTION_SUMMARY_TOKEN_ESTIMATE",
+          "declaration": {
+            "name": "COMPACTION_SUMMARY_TOKEN_ESTIMATE",
+            "module": "src/utils/context-tokens.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "reachesProvider",
+          "declaration": {
+            "name": "reachesProvider",
+            "module": "src/utils/context-tokens.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "isContextMeasurable",
+          "declaration": {
+            "name": "isContextMeasurable",
+            "module": "src/utils/context-tokens.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "estimateMessageTokens",
+          "declaration": {
+            "name": "estimateMessageTokens",
+            "module": "src/utils/context-tokens.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "estimateSystemOverhead",
+          "declaration": {
+            "name": "estimateSystemOverhead",
+            "module": "src/utils/context-tokens.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "estimateContextTokens",
+          "declaration": {
+            "name": "estimateContextTokens",
+            "module": "src/utils/context-tokens.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "estimateRequestTokens",
+          "declaration": {
+            "name": "estimateRequestTokens",
+            "module": "src/utils/context-tokens.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "projectCompaction",
+          "declaration": {
+            "name": "projectCompaction",
+            "module": "src/utils/context-tokens.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/cost-session-history.ts",
@@ -6670,21 +6961,45 @@
         },
         {
           "kind": "variable",
-          "name": "COMPACT_KEEP_RECENT_MESSAGES",
+          "name": "DEFAULT_TAIL_TOKEN_BUDGET",
           "type": {
             "text": "number"
           },
-          "default": "4",
-          "description": "Recent messages kept verbatim when compacting; everything earlier is summarized."
+          "default": "30_000",
+          "description": "Default size of the verbatim tail a compaction leaves behind, in tokens —\nMESSAGES only, since the system preamble is not something compaction can\nremove. A caller with a resolved context limit should pass a budget derived\nfrom it rather than relying on this."
         },
         {
           "kind": "variable",
-          "name": "COMPACT_MIN_MESSAGES_TO_COMPACT",
+          "name": "DEFAULT_MIN_RECLAIM_TOKENS",
           "type": {
             "text": "number"
           },
-          "default": "4",
-          "description": "Don't bother compacting unless at least this many messages would be summarized."
+          "default": "5_000",
+          "description": "Default floor on what a compaction must reclaim to be worth running. Below\nthis the summarizer call costs more than the space it buys — and, crucially,\na gate that offered compaction as its escape would be promising a reclaim\nthat does not clear the gate."
+        },
+        {
+          "kind": "function",
+          "name": "isSafeCompactionCut",
+          "return": {
+            "type": {
+              "text": "boolean"
+            }
+          },
+          "parameters": [
+            {
+              "name": "history",
+              "type": {
+                "text": "readonly ChatMessage[]"
+              }
+            },
+            {
+              "name": "i",
+              "type": {
+                "text": "number"
+              }
+            }
+          ],
+          "description": "Whether cutting at `i` — summarizing `[0, i)` and keeping `[i, end)` verbatim\n— leaves a request the provider will accept.\n\nThe one hard constraint is tool pairing: a `tool_result` whose `tool_use` was\nsummarized away is rejected outright by every provider. So the first message\nthe tail actually SENDS must not be a tool result.\n\nThis replaces the old \"cut only on a `user` message\" rule (GENC-1351), which\nwas a proxy for the same invariant — a user message never appears between a\ntool call and its results, so it was guaranteed safe without any pairing\ncheck. The proxy was sound but far too narrow: an agentic tool loop contains\nno user messages at all, so the whole loop was one indivisible block and a\nrunaway turn could not be compacted at any point. Checking the invariant\ndirectly opens up every gap between tool groups (GENC-1567).\n\nDisplay-only rows are skipped when looking for that first sent message: a\n`system-event` (e.g. \"Stopped.\") sitting between an `assistant(toolCalls)` and\nits results reaches no transport, so cutting in front of it would still orphan\nthe results behind it."
         },
         {
           "kind": "function",
@@ -6700,9 +7015,41 @@
               "type": {
                 "text": "readonly ChatMessage[]"
               }
+            },
+            {
+              "name": "tailTokenBudget",
+              "default": "DEFAULT_TAIL_TOKEN_BUDGET",
+              "type": {
+                "text": "number"
+              }
+            }
+          ],
+          "description": "Index at which the verbatim tail begins — everything before it gets summarized\n— chosen so the tail fits `tailTokenBudget` (GENC-1567).\n\nWalks back from the end accumulating estimated tokens until the next message\nwould overrun the budget, then snaps FORWARD to the nearest safe boundary.\nForward is the correct direction: it can only shrink the tail, so the budget\nstill holds after the snap, whereas snapping backwards could blow it.\n\nReturns `null` when the whole transcript already fits (nothing worth doing) or\nwhen no safe boundary exists ahead of the walk — e.g. a tail that is one\nenormous, indivisible tool group, which no cut can shrink because a cut cannot\nsplit a message."
+        },
+        {
+          "kind": "function",
+          "name": "planCompaction",
+          "return": {
+            "type": {
+              "text": "CompactionProjection | null"
+            }
+          },
+          "parameters": [
+            {
+              "name": "history",
+              "type": {
+                "text": "readonly ChatMessage[]"
+              }
+            },
+            {
+              "name": "options",
+              "default": "{}",
+              "type": {
+                "text": "CompactionPlanOptions"
+              }
             }
           ],
-          "description": "Index at which the verbatim tail begins — everything before it gets summarized.\nThe tail starts on a clean turn boundary (a `user` message): a user message\nnever appears between a `tool_use` and its `tool_result`, so cutting there\nguarantees the summarized region is tool-pair-balanced (compaction only runs\nwhen idle, so history is turn-complete). Returns `null` when there is nothing\nworth compacting (too short, or no earlier user boundary) — e.g. a freshly\nrestored session whose only user turn is the current one."
+          "description": "The single answer to \"what would compacting do right now, and is it worth it?\"\n\nEvery consumer reads this one function — the menu's enabled state, its\ntooltip, the gate's banner copy, and the action itself — so the affordance can\nnever promise something the action does not deliver. That is the same\none-source-of-truth argument that produced `canCompact()` (the GENC-1351\nfollow-up which stopped the gate reading a different history from the action);\nthis extends it from *legality* to *sufficiency*, which is what a blocking\ngate needs. A legal cut that covers four short messages while a large tool\nloop sits in the tail is legal and useless, and the old boolean could not say\nso.\n\nReturns `null` when there is no safe cut, or when the projected reclaim does\nnot clear `minReclaimTokens`."
         },
         {
           "kind": "function",
@@ -6778,17 +7125,25 @@
         },
         {
           "kind": "js",
-          "name": "COMPACT_KEEP_RECENT_MESSAGES",
+          "name": "DEFAULT_TAIL_TOKEN_BUDGET",
+          "declaration": {
+            "name": "DEFAULT_TAIL_TOKEN_BUDGET",
+            "module": "src/utils/history-transform.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "DEFAULT_MIN_RECLAIM_TOKENS",
           "declaration": {
-            "name": "COMPACT_KEEP_RECENT_MESSAGES",
+            "name": "DEFAULT_MIN_RECLAIM_TOKENS",
             "module": "src/utils/history-transform.ts"
           }
         },
         {
           "kind": "js",
-          "name": "COMPACT_MIN_MESSAGES_TO_COMPACT",
+          "name": "isSafeCompactionCut",
           "declaration": {
-            "name": "COMPACT_MIN_MESSAGES_TO_COMPACT",
+            "name": "isSafeCompactionCut",
             "module": "src/utils/history-transform.ts"
           }
         },
@@ -6800,6 +7155,14 @@
             "module": "src/utils/history-transform.ts"
           }
         },
+        {
+          "kind": "js",
+          "name": "planCompaction",
+          "declaration": {
+            "name": "planCompaction",
+            "module": "src/utils/history-transform.ts"
+          }
+        },
         {
           "kind": "js",
           "name": "buildCompactionSummaryPrompt",
@@ -6969,6 +7332,99 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/utils/resolve-context-budget.ts",
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "DEFAULT_RESERVE_TOKENS",
+          "type": {
+            "text": "number"
+          },
+          "default": "25_000",
+          "description": "Tokens kept free for a single turn by default.\n\nA turn is not atomic in cost: a send allowed just under a threshold can run a\nlong tool loop and add a great deal on its own, so what has to be bounded is\nthe growth of ONE turn — a token count, not a fraction of the window. On a\n200k model this leaves ~12% free; on a 1M model the same absolute room, rather\nthan the 200k a percentage rule would strand.\n\nChosen as a starting position, not a measured figure. Per-turn `inputTokens`\nis recorded for every call, so this should be revisited against real traffic."
+        },
+        {
+          "kind": "variable",
+          "name": "DEFAULT_WARN_MULTIPLIER",
+          "type": {
+            "text": "number"
+          },
+          "default": "2",
+          "description": "Warning appears this many reserves ahead of the block."
+        },
+        {
+          "kind": "variable",
+          "name": "CONTEXT_ABORT_MARGIN_TOKENS",
+          "type": {
+            "text": "number"
+          },
+          "default": "4_096",
+          "description": "How close to the window a running turn is allowed to get before the driver\nstops it (GENC-1567). Roughly one more tool result plus a reply — enough that\nthe next request would very likely be refused."
+        },
+        {
+          "kind": "function",
+          "name": "resolveContextBudget",
+          "return": {
+            "type": {
+              "text": "ResolvedContextBudget"
+            }
+          },
+          "parameters": [
+            {
+              "name": "input",
+              "type": {
+                "text": "ContextBudgetInput"
+              }
+            }
+          ],
+          "description": "Resolve the headroom thresholds for the active model and agent.\n\nEverything downstream — the warning, the block, the compaction planner and the\nbanner copy — reads this one result, so the thresholds a user is judged\nagainst and the budget compaction aims at can never disagree."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "DEFAULT_MIN_RECLAIM_TOKENS",
+          "declaration": {
+            "name": "DEFAULT_MIN_RECLAIM_TOKENS",
+            "module": "src/utils/resolve-context-budget.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "DEFAULT_RESERVE_TOKENS",
+          "declaration": {
+            "name": "DEFAULT_RESERVE_TOKENS",
+            "module": "src/utils/resolve-context-budget.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "DEFAULT_WARN_MULTIPLIER",
+          "declaration": {
+            "name": "DEFAULT_WARN_MULTIPLIER",
+            "module": "src/utils/resolve-context-budget.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "CONTEXT_ABORT_MARGIN_TOKENS",
+          "declaration": {
+            "name": "CONTEXT_ABORT_MARGIN_TOKENS",
+            "module": "src/utils/resolve-context-budget.ts"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "resolveContextBudget",
+          "declaration": {
+            "name": "resolveContextBudget",
+            "module": "src/utils/resolve-context-budget.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/utils/resolve-cost-history-config.ts",
@@ -8153,7 +8609,7 @@
         },
         {
           "kind": "class",
-          "description": "Plain TS class that drives a multi-turn chat conversation, including the tool-call loop.\nOwned by `FoundationAiAssistant` — created in `connectedCallback`, torn down in `disconnectedCallback`.\n\nDispatches `'history-updated'` events on itself so the owning element can observe changes.",
+          "description": "",
           "name": "ChatDriver",
           "members": [
             {
@@ -8676,7 +9132,7 @@
               "kind": "field",
               "name": "resolvedStatusCache",
               "privacy": "private",
-              "default": "new Map<string, { model?: string; provider?: AIProviderType }>()",
+              "default": "new Map<\n    string,\n    { model?: string; provider?: AIProviderType; contextLimit?: number }\n  >()",
               "description": "Memoised `name → getStatus()` lookups, so per-turn resolution doesn't\nre-await `getStatus()` every turn. Cleared (with `resolvedProviderCache`) on\nan observable-registry change, so a model swapped behind a stable name is\npicked up on the next turn."
             },
             {
@@ -9091,7 +9547,7 @@
               "privacy": "private",
               "return": {
                 "type": {
-                  "text": "Promise<{ model?: string; provider?: AIProviderType }>"
+                  "text": "Promise<{ model?: string; provider?: AIProviderType; contextLimit?: number }>"
                 }
               },
               "parameters": [
@@ -9284,6 +9740,69 @@
               ],
               "description": "Push one snapshot to the ring buffer. Called inside `runToolLoop` just\nbefore each LLM call — that's the latest point where the prompt, tool\nsurface, and agent state line up with what the model is about to see.\n\nReturns the pushed object so the caller can back-fill what only the response\nknows (`usage`). Mutating it after the fact is safe whether or not the ring\nbuffer has since evicted it — an evicted snapshot is simply no longer exported."
             },
+            {
+              "kind": "field",
+              "name": "contextGuard",
+              "type": {
+                "text": "ContextGuardPolicy | undefined"
+              },
+              "privacy": "private",
+              "description": "Mid-loop context guard policy (GENC-1567). `undefined` disables the guard.\n\nCarries a MARGIN rather than an absolute threshold, and the difference is the\nwhole point: the threshold depends on the window of whichever provider the\nnext call resolves to, which the driver learns during the call and the host\ncannot know until afterwards. The host owns the policy; the driver applies it\nagainst the model actually being addressed."
+            },
+            {
+              "kind": "field",
+              "name": "lastResolvedContextLimit",
+              "type": {
+                "text": "number | undefined"
+              },
+              "privacy": "private",
+              "description": "Window of the provider the current call resolved to, if it reports one."
+            },
+            {
+              "kind": "method",
+              "name": "setContextGuard",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "policy",
+                  "optional": true,
+                  "type": {
+                    "text": "ContextGuardPolicy"
+                  }
+                }
+              ],
+              "description": "Set the mid-loop context guard. Its margin is deliberately far smaller than\nthe reserve that blocks NEW turns: that reserve exists so an accepted turn can\nspend it, and a guard set at the same line would kill every turn that used\nthe headroom it was given."
+            },
+            {
+              "kind": "method",
+              "name": "contextExhausted",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "{ estimated: number; threshold: number } | undefined"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "requestHistory",
+                  "type": {
+                    "text": "readonly ChatMessage[]"
+                  }
+                },
+                {
+                  "name": "pendingInput",
+                  "optional": true,
+                  "type": {
+                    "text": "{ content: string; attachments?: ChatAttachment[] }"
+                  }
+                }
+              ],
+              "description": "Whether issuing `requestHistory` would run the context window out.\n\nInert unless a margin has been set AND the resolved provider reports a\nwindow — with no window there is nothing to measure against, and inventing\none to refuse a request is worse than letting the provider answer.\n\nStopping here is strictly better than letting the request go: the provider\nwould reject an oversized prompt outright, leaving a transcript still too\nlarge to retry and no explanation the user can act on, whereas ending the\nturn keeps history intact so compaction is still available and the work so\nfar is not lost."
+            },
             {
               "kind": "method",
               "name": "setProviderHistoryTransform",
@@ -9300,8 +9819,7 @@
                     "text": "(history: ChatMessage[]) => ChatMessage[]"
                   }
                 }
-              ],
-              "description": "Optional transform applied to conversation history immediately before each LLM request.\nCleared when `undefined`. Does not alter stored history."
+              ]
             },
             {
               "kind": "method",
@@ -9375,8 +9893,36 @@
                   "text": "boolean"
                 }
               },
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "CompactionPlanOptions"
+                  }
+                }
+              ],
               "description": "Whether `compact()` would do anything right now — a summarizable run of older\nturns exists behind a clean boundary. Uses the same `history` `compact()`\nacts on, so the UI's gate can't disagree with the action (GENC-1351 follow-up)."
             },
+            {
+              "kind": "method",
+              "name": "getCompactionPlan",
+              "return": {
+                "type": {
+                  "text": "CompactionProjection | null"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "CompactionPlanOptions"
+                  }
+                }
+              ],
+              "description": "{@inheritDoc AiDriver.getCompactionPlan}\n\nRuns against the driver's own `history` — the exact list `compact()` acts on\n— so a projection and the compaction it describes can never be computed from\ndifferent transcripts (the GENC-1351 follow-up that first made `canCompact`\nread `history` rather than a mirrored copy)."
+            },
             {
               "kind": "method",
               "name": "compact",
@@ -9385,6 +9931,15 @@
                   "text": "Promise<ChatMessage | null>"
                 }
               },
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "CompactionPlanOptions"
+                  }
+                }
+              ],
               "description": "Destructively compact older turns into a single `compacted-summary` message\n(GENC-1351 §5.7). Summarizes everything before a clean recent-tail boundary\nvia the registry-default provider's one-shot `prompt()`, then **atomically**\nreplaces the covered turns with one summary message at the head — history is\nmutated only on success. Rolling: any existing head summary is folded into\nthe new one. Returns the created summary message, or `null` when there is\nnothing worth compacting or the default provider cannot summarize."
             },
             {
@@ -9893,8 +10448,7 @@
               "name": "history-updated",
               "type": {
                 "text": "CustomEvent"
-              },
-              "description": "Fired whenever the in-memory chat history changes (append, tool loop, interaction resolution, post-resolve external cost) with the full history snapshot. detail: `ReadonlyArray<ChatMessage>`"
+              }
             },
             {
               "name": "interaction-stop",
@@ -10515,6 +11069,25 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "setContextGuard",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "policy",
+                  "optional": true,
+                  "type": {
+                    "text": "ContextGuardPolicy"
+                  }
+                }
+              ],
+              "description": "{@inheritDoc AiDriver.setContextGuard}"
+            },
             {
               "kind": "method",
               "name": "compact",
@@ -10523,6 +11096,15 @@
                   "text": "Promise<ChatMessage | null>"
                 }
               },
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "CompactionPlanOptions"
+                  }
+                }
+              ],
               "description": "{@inheritDoc AiDriver.compact}"
             },
             {
@@ -10533,8 +11115,36 @@
                   "text": "boolean"
                 }
               },
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "CompactionPlanOptions"
+                  }
+                }
+              ],
               "description": "{@inheritDoc AiDriver.canCompact}"
             },
+            {
+              "kind": "method",
+              "name": "getCompactionPlan",
+              "return": {
+                "type": {
+                  "text": "CompactionProjection | null"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "options",
+                  "optional": true,
+                  "type": {
+                    "text": "CompactionPlanOptions"
+                  }
+                }
+              ],
+              "description": "{@inheritDoc AiDriver.getCompactionPlan}"
+            },
             {
               "kind": "method",
               "name": "getTurnSnapshots",