@genesislcap/ai-assistant 15.4.1 → 15.6.0

package/src/provider/assistant-app-settings.ts

@@ -21,16 +21,42 @@ export interface AssistantAppSettingsToggle {
 }
 
 /**
- * App-supplied settings for the platform settings modal UI Builder section.
- * Register a concrete implementation on the DI token at app bootstrap; the
- * assistant renders toggles with the same row layout as AI Chat Bot settings.
+ * Optional heading above a provider's toggle group.
+ *
+ * Entirely host-supplied — the assistant has no default title and no default icon, because the
+ * section belongs to the host. Omit it and the toggles render bare, which is right when the
+ * host's slotted content already titles them.
+ *
+ * @beta
+ */
+export interface AssistantAppSettingsHeading {
+  readonly title: string;
+  /**
+   * Icon name for the design system's icon element (a Font Awesome free name, e.g.
+   * `'object-group'`). Omitted renders text only; an unknown name renders nothing at all, so
+   * check it against the installed Font Awesome set.
+   */
+  readonly icon?: string;
+}
+
+/**
+ * App-supplied settings for the host's own section of the settings modal. Register a concrete
+ * implementation on the DI token at app bootstrap; the assistant renders the toggles with the
+ * same row layout as AI Chat Bot settings.
+ *
+ * The section itself is untitled by the assistant — no heading text and no icon — because only
+ * the host knows what it is. Title it from the `settings-app` slot, which renders above these
+ * toggles, and apply `assistantSettingsSectionTitleStyles` to match the built-in headings.
  *
  * @beta
  */
 export interface AssistantAppSettingsProvider {
-  /** Section heading. Default: `"UI Builder Settings"`. */
-  readonly sectionTitle?: string;
   readonly toggles: readonly AssistantAppSettingsToggle[];
+  /**
+   * Heading for the toggle group, for hosts that put other controls in the `settings-app` slot
+   * and need these distinguished from them. No default: absent means no heading.
+   */
+  readonly togglesHeading?: AssistantAppSettingsHeading;
   getValue(id: string): boolean;
   setValue(id: string, value: boolean): void;
   /** Notify the assistant to re-read toggle values / visibility. */

package/src/state/ai-assistant-slice.test.ts

@@ -28,10 +28,14 @@ Suite('loadSession hydrates the restorable fields and forces idle', () => {
   let start = createDefaultSessionState();
   start = reduce(start, setState('loading')); // prove it overrides any prior state
   const payload: LoadSessionPayload = {
-    messages: [{ role: 'user', content: 'hi' }] as ChatMessage[],
+    // Usage rides on the message: `loadSession` derives the session totals from the
+    // restored transcript rather than from a stored counter, so the cost has to be in
+    // the messages for the assertion below to see it.
+    messages: [
+      { role: 'user', content: 'hi', cost: 1.25, inputTokens: 100, outputTokens: 20 },
+    ] as ChatMessage[],
     pinnedAgentName: 'Guided Booking',
     flowOwnerAgentName: 'Guided Booking',
-    sessionCostUsd: 1.25,
     contextTokens: 1200,
     contextLimit: 200000,
     activeModel: 'claude-sonnet-4-6',
@@ -41,7 +45,11 @@ Suite('loadSession hydrates the restorable fields and forces idle', () => {
   assert.is(next.messages.length, 1);
   assert.is(next.pinnedAgentName, 'Guided Booking');
   assert.is(next.flowOwnerAgentName, 'Guided Booking');
-  assert.is(next.sessionCostUsd, 1.25);
+  assert.is(next.sessionUsage.costUsd, 1.25);
+  // Derived from the same walk: 100 prompt tokens with no cache split reported, so all
+  // of it is uncached input, plus the 20 generated.
+  assert.is(next.sessionUsage.uncachedInputTokens, 100);
+  assert.is(next.sessionUsage.outputTokens, 20);
   assert.is(next.contextTokens, 1200);
   assert.is(next.contextLimit, 200000);
   assert.is(next.activeModel, 'claude-sonnet-4-6');
@@ -58,7 +66,6 @@ Suite('resetSession wipes back to a fresh default', () => {
       messages: [],
       pinnedAgentName: 'A',
       flowOwnerAgentName: 'A',
-      sessionCostUsd: 9,
       contextTokens: 5,
       contextLimit: 10,
       activeModel: 'm',
@@ -67,7 +74,7 @@ Suite('resetSession wipes back to a fresh default', () => {
   );
   const cleared = reduce(state, resetSession());
   assert.is(cleared.messages.length, 0);
-  assert.is(cleared.sessionCostUsd, 0);
+  assert.is(cleared.sessionUsage.costUsd, 0);
   assert.is(cleared.pinnedAgentName, null);
   assert.is(cleared.flowOwnerAgentName, null);
   assert.is(cleared.contextTokens, undefined);

package/src/state/ai-assistant-slice.ts

@@ -1,4 +1,5 @@
 import type {
+  AggregateUsage,
   AIProviderRegistryStatusEntry,
   ChatInputDuringExecutionMode,
   ChatMessage,
@@ -7,6 +8,7 @@ import type { PayloadAction } from '@genesislcap/foundation-redux';
 import { createSlice } from '@genesislcap/foundation-redux';
 import type { AgentConfig } from '../config/config';
 import type { AiAssistantAnimation, AiAssistantState, SuggestionsState } from '../main/main.types';
+import { emptyUsage, sumUsage } from '../utils/sum-usage';
 
 /**
  * A single in-flight per-call chat-input override pushed by a `requestSubAgent`
@@ -40,10 +42,15 @@ export interface AiAssistantSessionState {
   suggestionsState: SuggestionsState;
   contextTokens: number | undefined;
   contextLimit: number | undefined;
-  /** Aggregated USD cost across every chat turn in this session. */
-  sessionCostUsd: number;
-  /** Cumulative input + output tokens across every chat turn in this session. */
-  sessionTokensConsumed: number;
+  /**
+   * Cost and per-bucket token totals across every chat turn in this session,
+   * including sub-agent turns and spend banked by a compaction.
+   *
+   * One field rather than a cost scalar plus a token scalar: they are derived from
+   * the same walk of the transcript, so keeping them together makes it impossible
+   * for the two to disagree about which turns they counted.
+   */
+  sessionUsage: AggregateUsage;
   /** Active model id (e.g. `claude-sonnet-4-6`), resolved on connect. */
   activeModel: string | undefined;
   /**
@@ -137,7 +144,6 @@ export interface LoadSessionPayload {
   messages: ChatMessage[];
   pinnedAgentName: string | null;
   flowOwnerAgentName: string | null;
-  sessionCostUsd: number;
   contextTokens: number | undefined;
   contextLimit: number | undefined;
   activeModel: string | undefined;
@@ -161,8 +167,7 @@ export function createDefaultSessionState(): AiAssistantSessionState {
     suggestionsState: { status: 'idle' },
     contextTokens: undefined,
     contextLimit: undefined,
-    sessionCostUsd: 0,
-    sessionTokensConsumed: 0,
+    sessionUsage: emptyUsage(),
     activeModel: undefined,
     activeProviderName: undefined,
     providerStatuses: [],
@@ -217,11 +222,8 @@ export const aiAssistantSlice = createSlice({
     setContextLimit(state, action: PayloadAction<number | undefined>) {
       state.contextLimit = action.payload;
     },
-    setSessionCostUsd(state, action: PayloadAction<number>) {
-      state.sessionCostUsd = action.payload;
-    },
-    setSessionTokensConsumed(state, action: PayloadAction<number>) {
-      state.sessionTokensConsumed = action.payload;
+    setSessionUsage(state, action: PayloadAction<AggregateUsage>) {
+      state.sessionUsage = action.payload;
     },
     setActiveModel(state, action: PayloadAction<string | undefined>) {
       state.activeModel = action.payload;
@@ -282,7 +284,13 @@ export const aiAssistantSlice = createSlice({
       state.messages = p.messages;
       state.pinnedAgentName = p.pinnedAgentName;
       state.flowOwnerAgentName = p.flowOwnerAgentName;
-      state.sessionCostUsd = p.sessionCostUsd;
+      // Derive the totals from the restored transcript rather than trusting a stored
+      // counter. Restore dispatches this action directly, bypassing the host's
+      // `messages` setter — the thing that normally recomputes — so a stored total
+      // would sit stale (historically at 0) until the next turn arrived. The
+      // transcript is the source of truth: per-message usage survives the snapshot,
+      // and a compacted summary carries the usage of the turns it replaced.
+      state.sessionUsage = sumUsage(p.messages);
       state.contextTokens = p.contextTokens;
       state.contextLimit = p.contextLimit;
       state.activeModel = p.activeModel;

package/src/state/debug-event-log.ts

@@ -313,8 +313,8 @@ export const DEBUG_LOG_README: readonly string[] = [
   'This is an exported debug log for the Genesis AI assistant. Read it top-to-bottom.',
   '`timeline` is the entire session as one array, already sorted chronologically by `timestamp` (ISO 8601). Every entry has a `kind`.',
   '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.',
-  "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, and `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.",
-  "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`/`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.",
+  "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.",
+  "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.",
   "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.",
   "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.",
   "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'.",

package/src/state/persistence/session-persistence-provider.ts

@@ -1,3 +1,4 @@
+import type { CostSessionRecord } from '../../utils/cost-session-history';
 import type { DiagnosticEntry } from './diagnostics';
 import type { PersistedSession } from './session-snapshot';
 
@@ -43,6 +44,29 @@ export interface SessionPersistenceProvider {
   /** Persist the user's UI preferences for `sessionKey` (kept across `clear`). */
   savePreferences?(sessionKey: string, preferences: SessionPreferences): Promise<void>;
 
+  /**
+   * Scoped cost/build history — the per-project usage rows behind the Usage tab.
+   *
+   * ‼️ **Keyed by SCOPE, not `sessionKey`**, unlike every other method on this interface.
+   * A row holds one project's lifetime usage and the list spans projects, so keying it
+   * per session would defeat the model. The scope comes from
+   * `chatConfig.costHistory.scope`, falling back to the element `id`, then `'default'`.
+   *
+   * Optional: when a provider omits these, the assistant falls back to `localStorage`, so
+   * hosts that don't implement them are unaffected. Implementing them moves the ledger to
+   * the host's own backend, which is what stops it being stranded in one browser.
+   *
+   * Read/written **independently of the `enabled` toggle** (as with preferences and
+   * diagnostics): usage accounting is not conversation content, so a user turning off
+   * chat retention should not lose their cost ledger. Best-effort — a failed write must
+   * never affect the chat.
+   *
+   * `undefined` from `loadCostHistory` means "nothing stored", the same as `[]`.
+   */
+  loadCostHistory?(scope: string): Promise<CostSessionRecord[] | undefined>;
+  /** Replace the stored row list for `scope`. See {@link SessionPersistenceProvider.loadCostHistory}. */
+  saveCostHistory?(scope: string, records: CostSessionRecord[]): Promise<void>;
+
   /**
    * Server-saved diagnostics (GENC-1351 §5.8) — a **forward-only append** stream
    * that lets the downloadable debug log span the whole session lifetime, not just

package/src/state/persistence/session-persistence.integration.test.ts

@@ -77,7 +77,14 @@ Suite('save → reload → restore brings back messages, selection, counters', a
   const restored = reduce(freshStore, loadSession(toLoadSessionPayload(snapshot!)));
   assert.is(restored.messages.length, 2);
   assert.is(restored.pinnedAgentName, 'Guided Booking');
-  assert.is(restored.sessionCostUsd, 0.5);
+  // Cost comes from the restored transcript, NOT the snapshot's stored counter — so it
+  // is whatever the messages actually carry. Computed independently here rather than
+  // by calling the summing helper under test.
+  const expectedCost = restored.messages.reduce(
+    (sum, m) => sum + (m.cost ?? 0) + (m.externalCostUsd ?? 0),
+    0,
+  );
+  assert.is(restored.sessionUsage.costUsd, expectedCost);
   assert.is(restored.contextTokens, 800);
   assert.is(restored.contextLimit, 200000);
   assert.is(restored.activeModel, 'claude-sonnet-4-6');

package/src/state/persistence/session-persister.test.ts

@@ -101,7 +101,16 @@ function makePersister(over: Partial<Fakes> = {}): { p: SessionPersister; f: Fak
         flowActivationPrompt: null,
         activeAgent: undefined,
         pinnedAgentName: null,
-        sessionCostUsd: 0,
+        // Inline rather than via `emptyUsage()` to keep this mock self-contained. The
+        // shape matters: the persister reads `sessionUsage.costUsd`, so a mock missing
+        // the object crashes the autosave timer rather than failing an assertion.
+        sessionUsage: {
+          costUsd: 0,
+          uncachedInputTokens: 0,
+          cacheReadTokens: 0,
+          cacheWriteTokens: 0,
+          outputTokens: 0,
+        },
         get restoring() {
           return f.restoring;
         },

package/src/state/persistence/session-persister.ts

@@ -282,7 +282,7 @@ export class SessionPersister {
           activeAgentName: s.activeAgent?.name,
           pinnedAgentName: s.pinnedAgentName,
           flowOwnerAgentName: null,
-          sessionCostUsd: s.sessionCostUsd,
+          sessionCostUsd: s.sessionUsage.costUsd,
           contextTokens: s.contextTokens,
           contextLimit: s.contextLimit,
           activeModel: s.activeModel,
@@ -316,7 +316,7 @@ export class SessionPersister {
       activeAgentName: s.activeAgent?.name,
       pinnedAgentName: s.pinnedAgentName,
       flowOwnerAgentName: s.flowOwnerAgentName,
-      sessionCostUsd: s.sessionCostUsd,
+      sessionCostUsd: s.sessionUsage.costUsd,
       contextTokens: s.contextTokens,
       contextLimit: s.contextLimit,
       activeModel: s.activeModel,

package/src/state/persistence/session-snapshot.test.ts

@@ -74,7 +74,10 @@ Suite('toLoadSessionPayload projects only the redux-restorable fields', () => {
   const p = toLoadSessionPayload(base());
   assert.is(p.pinnedAgentName, 'A');
   assert.is(p.flowOwnerAgentName, null);
-  assert.is(p.sessionCostUsd, 2);
+  // Cost is deliberately NOT projected — the slice re-derives it (and the token
+  // buckets) from `messages`, so a stored counter would be a second, divergeable
+  // source of truth.
+  assert.is((p as { sessionCostUsd?: number }).sessionCostUsd, undefined);
   assert.is(p.contextTokens, 10);
   assert.is(p.contextLimit, 100);
   assert.is(p.activeModel, 'm');

package/src/state/persistence/session-snapshot.ts

@@ -190,7 +190,11 @@ export function toLoadSessionPayload(s: PersistedSession): LoadSessionPayload {
     messages: s.messages,
     pinnedAgentName: s.pinnedAgentName ?? null,
     flowOwnerAgentName: s.flowOwnerAgentName ?? null,
-    sessionCostUsd: s.sessionCostUsd ?? 0,
+    // `sessionCostUsd` is deliberately NOT projected: the slice re-derives cost and
+    // token totals from `messages` on load. The snapshot field is still written (its
+    // shape is public, and it is a useful cross-check in a saved blob), but it is no
+    // longer authoritative — a snapshot saved mid-reset could hold a zeroed total
+    // while its transcript still shows the spend.
     contextTokens: s.contextTokens,
     contextLimit: s.contextLimit,
     activeModel: s.activeModel,

package/src/state/persistence/stateful-restore.e2e.test.ts

@@ -81,7 +81,15 @@ function makeStoreFake(over: Record<string, unknown> = {}) {
         flowActivationPrompt: null as string | null,
         activeAgent: undefined as { name: string } | undefined,
         pinnedAgentName: null as string | null,
-        sessionCostUsd: 0,
+        // The persister reads `sessionUsage.costUsd` when building a snapshot, so this
+        // has to be the object rather than a bare cost scalar.
+        sessionUsage: {
+          costUsd: 0,
+          uncachedInputTokens: 0,
+          cacheReadTokens: 0,
+          cacheWriteTokens: 0,
+          outputTokens: 0,
+        },
         contextTokens: 0,
         contextLimit: 0,
         activeModel: undefined,

package/src/styles/settings-section.ts

@@ -0,0 +1,40 @@
+import { css, type ElementStyles } from '@genesislcap/web-core';
+
+/**
+ * Heading style for a settings-modal section, published so a host can title its own section.
+ *
+ * The assistant renders no heading for the `settings-app` slot — no text and no icon — because
+ * only the host knows what that section is. The consequence is that a host supplying one has to
+ * reproduce the styling of the built-in headings beside it, and a copied rule drifts the moment
+ * either side changes. So the declarations live here, are applied by the assistant's own
+ * headings, and are exported for the host to apply to its.
+ *
+ * Compose it into a component's styles and put `ai-settings-section-title` on the heading:
+ *
+ * ```ts
+ * import { assistantSettingsSectionTitleStyles } from '@genesislcap/ai-assistant';
+ *
+ * const styles = css`
+ *   ${assistantSettingsSectionTitleStyles}
+ *   :host { display: block; }
+ * `;
+ * ```
+ *
+ * Carries no margin on purpose: spacing belongs to the surrounding layout, which differs
+ * between the assistant's own sections and a slotted one, and is the single declaration hosts
+ * had to diverge on when they copied this rule.
+ *
+ * @beta
+ */
+export const assistantSettingsSectionTitleStyles: ElementStyles = css`
+  .ai-settings-section-title {
+    display: flex;
+    align-items: center;
+    gap: calc(var(--design-unit) * 2px);
+    font-size: 11px;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--neutral-foreground-hint);
+  }
+`;

package/src/utils/condense-history.test.ts

@@ -44,12 +44,14 @@ const ctx = (
     turn?: number;
     activationEnded?: (a: number) => boolean;
     phaseEnded?: (e: number) => boolean;
+    batchCalls?: number;
   } = {},
 ): CondenseContext => ({
   modelCall: o.modelCall ?? 0,
   turn: o.turn ?? 0,
   activationEnded: o.activationEnded ?? (() => false),
   phaseEnded: o.phaseEnded ?? (() => false),
+  batchCalls: o.batchCalls,
 });
 
 const sink = () => {
@@ -434,3 +436,104 @@ suite('multi-trigger first-wins: the earliest-listed firing trigger is the reaso
 });
 
 suite.run();
+
+// ── batched collapse (GENC-1476) ───────────────────────────────────────────
+// Condensation rewrites history in place, so collapsing the instant a trigger fires
+// breaks the prompt cache on nearly every call of a re-read loop. Batching holds the
+// collapse set still between boundaries.
+
+const batch = createLogicSuite('applyCondensation batching');
+
+/** A re-read loop: `n` reads of the same path, each registered one model-call apart. */
+const reReadLoop = (n: number) => {
+  const history: ChatMessage[] = [];
+  const policies = new Map<string, RegisteredCondensePolicy>();
+  for (let i = 1; i <= n; i += 1) {
+    history.push(asstCall(`r${i}`, 'vfs_read', { path: 'A.tsx' }), toolMsg(`r${i}`, big()));
+    policies.set(
+      `r${i}`,
+      reg({ on: { kind: 'superseded', by: 'A.tsx' }, response: 'pointer' }, { iteration: i }),
+    );
+  }
+  return { history, policies };
+};
+
+/** Result content of every tool message, in order. */
+const results = (out: ChatMessage[]): string[] =>
+  out.filter((m) => m.role === 'tool').map((m) => m.toolResult?.content ?? '');
+
+batch('without batching every superseded read collapses immediately', () => {
+  const { history, policies } = reReadLoop(4);
+  const out = results(applyCondensation(history, policies, ctx({ modelCall: 4 }), sink().on));
+  // Only the newest survives; the other three are already stubs.
+  assert.is(out.filter((c) => c.startsWith('[')).length, 3);
+  assert.is(out[3].length, big().length);
+});
+
+batch('batching leaves the prefix untouched between boundaries', () => {
+  const { history, policies } = reReadLoop(4);
+  // Boundary is floor(4/10)*10 = 0, so no call is within the batch yet.
+  const out = results(
+    applyCondensation(history, policies, ctx({ modelCall: 4, batchCalls: 10 }), sink().on),
+  );
+  assert.equal(
+    out.map((c) => c.length),
+    [big().length, big().length, big().length, big().length],
+  );
+});
+
+batch('the batch boundary collapses the backlog in one step', () => {
+  const { history, policies } = reReadLoop(12);
+  const before = results(
+    applyCondensation(history, policies, ctx({ modelCall: 9, batchCalls: 10 }), sink().on),
+  );
+  const after = results(
+    applyCondensation(history, policies, ctx({ modelCall: 10, batchCalls: 10 }), sink().on),
+  );
+  assert.is(before.filter((c) => c.startsWith('[')).length, 0);
+  // At the boundary, reads 1-9 collapse together; 10-12 are past it and stay full.
+  assert.is(after.filter((c) => c.startsWith('[')).length, 9);
+});
+
+batch('a call past the boundary neither collapses nor supersedes an older one', () => {
+  // The regression this guards: excluding the new call as a SUPERSEDER but still letting
+  // it collapse would elide the very result the agent just fetched.
+  const { history, policies } = reReadLoop(2);
+  policies.set(
+    'r2',
+    reg({ on: { kind: 'superseded', by: 'A.tsx' }, response: 'pointer' }, { iteration: 7 }),
+  );
+  const out = results(
+    applyCondensation(history, policies, ctx({ modelCall: 7, batchCalls: 5 }), sink().on),
+  );
+  assert.is(out[1].length, big().length, 'the newest read must stay full');
+  assert.is(out[0].length, big().length, 'the older read must not collapse early either');
+});
+
+batch('age is measured against the boundary, not the live clock', () => {
+  const history = [asstCall('g1', 'grep', {}), toolMsg('g1', big())];
+  const policies = new Map([
+    ['g1', reg({ on: { kind: 'age', turns: 1 }, response: 'pointer' }, { iteration: 1 })],
+  ]);
+  // Live clock says age 4 > 1 (would collapse); the boundary says 0, so it holds.
+  const held = results(
+    applyCondensation(history, policies, ctx({ modelCall: 5, batchCalls: 10 }), sink().on),
+  );
+  assert.is(held[0].length, big().length);
+  const collapsed = results(
+    applyCondensation(history, policies, ctx({ modelCall: 10, batchCalls: 10 }), sink().on),
+  );
+  assert.ok(collapsed[0].startsWith('['));
+});
+
+batch('batchCalls of 1, 0 or absent all keep the historical behaviour', () => {
+  for (const batchCalls of [1, 0, undefined]) {
+    const { history, policies } = reReadLoop(3);
+    const out = results(
+      applyCondensation(history, policies, ctx({ modelCall: 3, batchCalls }), sink().on),
+    );
+    assert.is(out.filter((c) => c.startsWith('[')).length, 2, `batchCalls=${batchCalls}`);
+  }
+});
+
+batch.run();

package/src/utils/condense-history.ts

@@ -75,6 +75,20 @@ export interface CondenseContext {
    * `phaseEnd` clock. True once `endPhase()` has been called since the call.
    */
   phaseEnded: (phaseEpoch: number) => boolean;
+  /**
+   * Collapse in batches of this many model-calls instead of continuously. A positive
+   * integer; decimals are floored and anything below `1` becomes `1`. Omit (or `1`) to
+   * collapse as soon as a trigger fires, which is the historical behaviour.
+   *
+   * Condensation rewrites a payload *in place*, so the model-bound history is not
+   * append-only and every prompt-cache entry written before the rewrite is invalidated
+   * from that position on. Collapsing the moment each trigger fires therefore breaks the
+   * cache on nearly every call of a re-read loop — the case condensation exists to
+   * contain. Batching holds the collapse set still between boundaries so the prefix is
+   * append-only in between, trading up to `batchCalls` calls' worth of extra context for
+   * one cache break per batch instead of one per call.
+   */
+  batchCalls?: number;
 }
 
 /**
@@ -193,6 +207,20 @@ export function applyCondensation(
   // lookup. For each `superseded` key the LAST call in history order survives.
   // The name lookup lets a tool message (which carries only an id) name its tool
   // in stubs and events.
+  // Batch boundary: the collapse set is resolved as of this model-call and stays put
+  // until the next boundary, so the prefix is append-only in between. `batchCalls` of 1
+  // (the default) makes this `ctx.modelCall` — i.e. no batching.
+  const batchCalls = Math.max(1, Math.floor(ctx.batchCalls ?? 1));
+  const asOf =
+    batchCalls === 1 ? ctx.modelCall : Math.floor(ctx.modelCall / batchCalls) * batchCalls;
+  // A call made after the boundary is invisible to this pass in BOTH directions: it
+  // cannot supersede an older call (which would collapse the older payload early), and
+  // it cannot itself collapse (which would elide the very result just fetched). Unbatched,
+  // the boundary is the live clock and this gate is off entirely — a call registered on
+  // the current model-call is still eligible, as it always was.
+  const withinBatch = (entry: RegisteredCondensePolicy): boolean =>
+    batchCalls === 1 || entry.iteration <= asOf;
+
   const latestByKey = new Map<string, string>();
   const nameById = new Map<string, string>();
   for (const msg of history) {
@@ -200,7 +228,7 @@ export function applyCondensation(
     for (const tc of msg.toolCalls) {
       nameById.set(tc.id, tc.name);
       const entry = policies.get(tc.id);
-      if (!entry) continue;
+      if (!entry || !withinBatch(entry)) continue;
       for (const t of triggersOf(entry)) {
         if (t.kind === 'superseded') latestByKey.set(t.by, tc.id);
       }
@@ -217,7 +245,7 @@ export function applyCondensation(
       // past the last allowed view: turns:1 → seen once, then gone. Monotonic
       // clock, so this holds across turn boundaries too.
       case 'age':
-        return ctx.modelCall - entry.iteration > trig.turns;
+        return asOf - entry.iteration > trig.turns;
       case 'turnEnd':
         return ctx.turn > entry.turn;
       case 'agentEnd':
@@ -238,7 +266,9 @@ export function applyCondensation(
     toolCallId: string,
     entry: RegisteredCondensePolicy,
   ): CondenseTrigger | undefined =>
-    triggersOf(entry).find((t) => triggerFires(toolCallId, entry, t));
+    withinBatch(entry)
+      ? triggersOf(entry).find((t) => triggerFires(toolCallId, entry, t))
+      : undefined;
 
   return history.map((msg) => {
     // Tool-call ARGS live on the assistant message.