@genesislcap/ai-assistant 14.467.2 → 14.468.0

package/src/components/chat-driver/chat-driver.ts

@@ -9,6 +9,8 @@ import type {
   ChatToolChoice,
   ChatToolDefinition,
   ChatToolHandlers,
+  CondensePolicy,
+  CondenseTrigger,
   InteractionRequestOptions,
   InteractionResult,
   SubAgentFailureReason,
@@ -40,6 +42,7 @@ import {
   recordTurnError,
   recordTurnRetry,
 } from '../../state/debug-event-log';
+import { applyCondensation, type RegisteredCondensePolicy } from '../../utils/condense-history';
 import { applyHistoryCap } from '../../utils/history-transform';
 import { logger } from '../../utils/logger';
 import { TOOL_FOLD_SYMBOL, type ToolFold } from '../../utils/tool-fold';
@@ -245,6 +248,40 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * sent to the model — stored `history` stays unchanged for UI and logging.
    */
   private providerHistoryTransform?: (history: ChatMessage[]) => ChatMessage[];
+  /**
+   * Tool-declared condensation policies, keyed by tool-call id. Populated by
+   * `condenseWhen` (first-wins per call); read by `applyCondensation` before each
+   * provider call to collapse stale payloads from the model-bound history only.
+   * Accumulates across agents on a shared driver (a superseded read collapses no
+   * matter which agent made it) and is never cleared — it dies with the driver.
+   */
+  private readonly condensePolicies = new Map<string, RegisteredCondensePolicy>();
+  /**
+   * Monotonic model-call counter for the driver's whole lifetime — the age clock
+   * for `condenseWhen({ on: { kind: 'age' } })`. The per-`sendMessage` `iterations`
+   * loop counter resets to 0 every turn, so it can only measure age WITHIN a
+   * single turn; this never resets, so `age` counts model-calls since the result
+   * appeared across turn boundaries (each short turn still advances it ≥ 1).
+   * Bumped once per tool-loop iteration (provider call).
+   */
+  private modelCallSeq = 0;
+  /**
+   * Monotonic turn counter — the `turnEnd` clock. Bumped once per `sendMessage`
+   * (a user turn; NOT per handoff continuation, which is the same request), never
+   * reset. `turnEnd` collapses a payload once `turnSeq` exceeds the turn it was
+   * created in.
+   */
+  private turnSeq = 0;
+  /**
+   * Monotonic agent-activation counter — the `agentEnd` clock. Advances when the
+   * active flow ends: a swap to a different-named agent (`applyAgent`) OR an
+   * explicit `releaseAgent` / `completeSubAgent`. A stateful agent re-resolving
+   * the same name across turns keeps one activation. `agentEnd` fires for a
+   * payload once a LATER activation is current (`callActivation < currentActivation`)
+   * — so a re-run of a released agent gets a fresh activation and is NOT
+   * collapsed until IT ends.
+   */
+  private currentActivation = 0;
 
   /** Stack of fold frames — grows when a fold opens, shrinks when it closes. */
   private foldStack: FoldStackFrame[] = [];
@@ -528,6 +565,11 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * each specialist turn so the shared driver runs with the right tools and prompt.
    */
   applyAgent(config: AgentConfig): void {
+    // A real swap to a different agent begins a NEW activation — the prior agent's
+    // flow is over, so its `agentEnd`-tagged payloads become collapsible. Guarded
+    // on a name change so re-applying the same agent (e.g. a per-turn re-resolve)
+    // does not spuriously advance the clock and prematurely drop its payloads.
+    if (config.name !== this.activeAgentName) this.currentActivation += 1;
     this.systemPrompt = config.systemPrompt;
     if (typeof config.toolDefinitions === 'function') {
       this.toolDefinitionsFactory = config.toolDefinitions;
@@ -1175,6 +1217,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
     this.busy = true;
     this.beginTurn();
+    // A new user turn — advances the `turnEnd` clock (continuations after a
+    // handoff stay on the same turn; they go through `continueFromHistory`).
+    this.turnSeq += 1;
     this.subAgentCompletion = undefined;
     this.subAgentFailure = undefined;
     this.agentReleaseRequested = false;
@@ -1219,11 +1264,15 @@ export class ChatDriver extends EventTarget implements AiDriver {
    * Centralised here so fold shortcut dispatch and the main tool loop use the
    * same context without duplication.
    *
+   * @param activeToolCallId - The id of the tool call this context belongs to, so
+   *   `condenseWhen` can register against the right call (it stamps the clocks
+   *   straight off the driver). Absent for dispatch paths with no addressable tool
+   *   call (e.g. the fold-close handler), where `condenseWhen` is a no-op.
    * @param traceCapture - Optional per-invocation slot. When provided, the trace
    *   from any sub-agent call is written here rather than to shared instance state,
    *   so parallel tool calls each capture their own trace independently.
    */
-  private buildHandlerContext(traceCapture?: { trace?: ChatMessage[] }) {
+  private buildHandlerContext(activeToolCallId?: string, traceCapture?: { trace?: ChatMessage[] }) {
     return {
       requestInteraction: <T>(
         componentName: string,
@@ -1251,6 +1300,9 @@ export class ChatDriver extends EventTarget implements AiDriver {
           return;
         }
         this.subAgentCompletion = { result };
+        // This activation's flow has ended — advance the clock so its
+        // `agentEnd` payloads collapse and a re-run starts a fresh activation.
+        this.currentActivation += 1;
       },
       releaseAgent: (): void => {
         if (this.agentReleaseRequested) {
@@ -1260,6 +1312,48 @@ export class ChatDriver extends EventTarget implements AiDriver {
           return;
         }
         this.agentReleaseRequested = true;
+        // The stateful flow has wrapped up — advance the clock so its `agentEnd`
+        // payloads collapse and a re-run starts a fresh activation.
+        this.currentActivation += 1;
+      },
+      condenseWhen: (policy: CondensePolicy): void => {
+        // No addressable tool call (e.g. fold-close handler) — nothing to attach to.
+        if (!activeToolCallId) return;
+        if (!policy?.args && !policy?.response) {
+          logger.warn(
+            `ChatDriver(${this.activeAgentName ?? 'unknown'}): condenseWhen called with neither args nor response — ignoring`,
+          );
+          return;
+        }
+        const triggers = Array.isArray(policy.on) ? policy.on : [policy.on];
+        const validTrigger = (t: CondenseTrigger | undefined): boolean =>
+          t?.kind === 'superseded'
+            ? typeof t.by === 'string' && t.by.length > 0
+            : t?.kind === 'age'
+              ? typeof t.turns === 'number' && t.turns >= 1
+              : t?.kind === 'turnEnd' || t?.kind === 'agentEnd';
+        if (triggers.length === 0 || !triggers.every(validTrigger)) {
+          logger.warn(
+            `ChatDriver(${this.activeAgentName ?? 'unknown'}): condenseWhen called with an invalid trigger — ignoring`,
+          );
+          return;
+        }
+        // First-wins: a handler declares its policy once per call. A second
+        // declaration for the same tool call is a handler bug, not a refinement.
+        if (this.condensePolicies.has(activeToolCallId)) {
+          logger.error(
+            `ChatDriver(${this.activeAgentName ?? 'unknown'}): condenseWhen called more than once for the same tool call — keeping the first policy, ignoring this one`,
+          );
+          return;
+        }
+        // Stamp the three clocks NOW (read straight off the driver — the handler
+        // runs during the current model-call's tool batch).
+        this.condensePolicies.set(activeToolCallId, {
+          policy,
+          iteration: this.modelCallSeq,
+          turn: this.turnSeq,
+          activation: this.currentActivation,
+        });
       },
     };
   }
@@ -1611,6 +1705,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
     foldName: string,
     fold: ToolFold,
     args: Record<string, unknown>,
+    activeToolCallId?: string,
   ): Promise<string> {
     // Shortcut dispatch: model passed inner tool args directly, e.g.
     // trading_tools({ search_trades: { side: "BUY" } })
@@ -1626,7 +1721,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
           typeof args[key] === 'object' && args[key] !== null
             ? (args[key] as Record<string, unknown>)
             : {};
-        return innerHandler(innerArgs, this.buildHandlerContext()).then((r) =>
+        return innerHandler(innerArgs, this.buildHandlerContext(activeToolCallId)).then((r) =>
           typeof r === 'string' ? r : JSON.stringify(r),
         );
       }
@@ -1727,6 +1822,10 @@ export class ChatDriver extends EventTarget implements AiDriver {
 
     while (iterations < this.maxToolIterations) {
       iterations += 1;
+      // Monotonic across the driver's life — the age clock. Unlike `iterations`,
+      // it is NOT reset per turn and NOT decremented for folds, so `age` keeps
+      // counting model-calls once a turn ends. (See the `modelCallSeq` field.)
+      this.modelCallSeq += 1;
 
       // A cancel (or dispose) that landed while the previous iteration's tool
       // batch was running takes effect here — before issuing another LLM call.
@@ -1804,9 +1903,24 @@ export class ChatDriver extends EventTarget implements AiDriver {
       const primer = [...(this.primerHistory ?? []), ...(transientPrimer ?? [])];
       const baseHistory = firstLlmCall ? this.history.slice(0, -1) : this.history;
       firstLlmCall = false;
+      // Collapse stale tool payloads this agent declared via `condenseWhen`, then
+      // pipe through any externally-set transform (e.g. multi-agent masking).
+      // Both run on a copy — stored history is untouched.
+      const condensedHistory = applyCondensation(
+        [...baseHistory],
+        this.condensePolicies,
+        {
+          modelCall: this.modelCallSeq,
+          turn: this.turnSeq,
+          // A call's activation has ended once a later activation is current — a
+          // swap or release/complete both advance the counter.
+          activationEnded: (activation) => activation < this.currentActivation,
+        },
+        (detail) => recordMetaEvent(this.sessionKey, 'context.condensed', detail),
+      );
       const historyForProvider = this.providerHistoryTransform
-        ? this.providerHistoryTransform([...baseHistory])
-        : baseHistory;
+        ? this.providerHistoryTransform(condensedHistory)
+        : condensedHistory;
       const historyForCall = [...primer, ...historyForProvider];
 
       const systemPrompt =
@@ -2059,7 +2173,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
                 });
                 return;
               }
-              const content = await this.openFold(tc.name, fold, tc.args);
+              const content = await this.openFold(tc.name, fold, tc.args, tc.id);
               executedById.set(tc.id, { toolCallId: tc.id, content });
               // Fold open/close does NOT count as a real iteration — decrement to compensate
               iterations -= 1;
@@ -2186,7 +2300,7 @@ export class ChatDriver extends EventTarget implements AiDriver {
             // Real tool execution
             try {
               const traceCapture: { trace?: ChatMessage[] } = {};
-              const result = await handler(tc.args, this.buildHandlerContext(traceCapture));
+              const result = await handler(tc.args, this.buildHandlerContext(tc.id, traceCapture));
               const content = typeof result === 'string' ? result : JSON.stringify(result);
               executedById.set(tc.id, {
                 toolCallId: tc.id,

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

@@ -60,6 +60,7 @@ export type MetaEventType =
   // Context / cost
   | 'context.updated'
   | 'context.threshold-crossed'
+  | 'context.condensed'
   // UI + input
   | 'panel.toggled'
   | 'attachment.added'
@@ -113,6 +114,7 @@ export const META_EVENT_IMPORTANCE: Record<MetaEventType, MetaEventImportance> =
   'driver.wired': 'low',
   'driver.unwired': 'low',
   'context.updated': 'low',
+  'context.condensed': 'low',
   'panel.toggled': 'low',
   'attachment.added': 'low',
 };
@@ -298,8 +300,8 @@ export const DEBUG_LOG_README: readonly string[] = [
   "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'.",
-  "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). 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.",
-  '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, 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, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
+  "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.",
+  '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, 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, unknownTools (split into staleTools — real earlier this activation but retired by the current state or hidden behind an open exclusive fold — and hallucinatedTools — never advertised) + availableTools, iterations + limit, or name + message for exceptions), tool.failed (a tool threw), tool.unresolved (the model called a tool that could not be dispatched — detail.kind is folded/fold-hidden/stale/unknown, plus tool + agent and, for the counted kinds, the consecutive streak; the recurring lead-up to an unknown-tool-limit turn.error), subagent.started/completed/failed (the lifecycle of a `requestSubAgent` delegation — detail.agent names the sub-agent; these bracket the sub-agent turns that appear as kind:turn entries with an N-M `turnIndex`; subagent.failed also carries detail.reason, one of max_iterations/malformed_tool_call/empty_response/unknown_tool_limit/timeout), agent.handoff (routing; from=null is the initial activation), agent.pinned/unpinned (forced routing), provider.selected (model/provider for the upcoming turns), interaction.requested/resolved (blocking user widgets — explain quiet gaps; note that when a sub-agent opens a widget, detail.agent — and the agentName on the interaction message — is the HOST agent that owns the widget, NOT the sub-agent that asked, because widgets render and resolve on the host driver), context.updated/threshold-crossed (token + cost), context.condensed (a stale tool payload was collapsed out of the model-bound history by a `condenseWhen` declaration on the tool — detail.tool + toolCallId, target args|response, trigger (superseded:<key> or age:<n>), stubLen, and an estimated tokensSaved; stored history and this log keep the FULL payload, so the model-visible slice at any point is the full history minus the condensations recorded up to then), panel.toggled, attachment.added, file.read-failed, suggestions.failed.',
   '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.',
   "`meta` holds context captured at export time: agentSummary (full agent configs), context (active model, token usage, session cost), activeDebugSnapshot (the active agent's `getDebugSnapshot()` taken fresh at export — reflects state NOW, which may have advanced beyond the last turn's agentSnapshot), debug (optional host-supplied debug state), host, and the export timestamp.",
   '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.',

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

@@ -0,0 +1,373 @@
+import type { ChatMessage, CondensePolicy } from '@genesislcap/foundation-ai';
+import { assert, createLogicSuite } from '@genesislcap/foundation-testing';
+import {
+  applyCondensation,
+  CONDENSE_MIN_CHARS,
+  type CondenseContext,
+  type CondensedEventDetail,
+  type RegisteredCondensePolicy,
+} from './condense-history';
+
+const suite = createLogicSuite('applyCondensation');
+
+// Payloads must clear the driver-level floor to be condensed.
+const big = (n: number = CONDENSE_MIN_CHARS + 500): string => 'x'.repeat(n);
+
+const asstCall = (
+  id: string,
+  name: string,
+  args: Record<string, unknown> = {},
+  extra: Record<string, unknown> = {},
+): ChatMessage => ({ role: 'assistant', content: '', toolCalls: [{ id, name, args, ...extra }] });
+
+const toolMsg = (toolCallId: string, content: string): ChatMessage => ({
+  role: 'tool',
+  content: '',
+  toolResult: { toolCallId, content },
+});
+
+const reg = (
+  policy: CondensePolicy,
+  clocks: { iteration?: number; turn?: number; activation?: number } = {},
+): RegisteredCondensePolicy => ({
+  policy,
+  iteration: clocks.iteration ?? 1,
+  turn: clocks.turn ?? 1,
+  activation: clocks.activation ?? 1,
+});
+
+/** A CondenseContext for the pure transform. Defaults fire nothing; override per test. */
+const ctx = (
+  o: { modelCall?: number; turn?: number; activationEnded?: (a: number) => boolean } = {},
+): CondenseContext => ({
+  modelCall: o.modelCall ?? 0,
+  turn: o.turn ?? 0,
+  activationEnded: o.activationEnded ?? (() => false),
+});
+
+const sink = () => {
+  const events: CondensedEventDetail[] = [];
+  return { events, on: (d: CondensedEventDetail) => events.push(d) };
+};
+
+// ---------------------------------------------------------------------------
+// supersession
+// ---------------------------------------------------------------------------
+
+suite('superseded response: collapses the earlier call, keeps the latest full', () => {
+  const history: ChatMessage[] = [
+    asstCall('r1', 'vfs_read', { path: 'A' }),
+    toolMsg('r1', big()),
+    asstCall('r2', 'vfs_read', { path: 'A' }),
+    toolMsg('r2', big()),
+  ];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['r1', reg({ on: { kind: 'superseded', by: 'A' }, response: 'pointer' })],
+    ['r2', reg({ on: { kind: 'superseded', by: 'A' }, response: 'pointer' })],
+  ]);
+  const { events, on } = sink();
+  const out = applyCondensation(history, policies, ctx(), on);
+
+  assert.match(out[1].toolResult!.content, /re-call to restore/);
+  assert.is(out[3].toolResult!.content, big(), 'latest call for the key stays full');
+  // Exactly one transition reported, for the earlier call's response.
+  assert.is(events.length, 1);
+  assert.is(events[0].toolCallId, 'r1');
+  assert.is(events[0].target, 'response');
+  assert.is(events[0].trigger, 'superseded:A');
+  // Input is never mutated; unchanged messages keep their identity.
+  assert.is(history[1].toolResult!.content, big(), 'stored history untouched');
+  assert.is(out[3], history[3], 'unchanged message reuses the same object');
+  assert.ok(out[1] !== history[1], 'collapsed message is a new object');
+});
+
+suite('superseded crosses tools: a read collapses the earlier write args of the same key', () => {
+  const history: ChatMessage[] = [
+    asstCall('w1', 'vfs_write', { path: 'A', content: big() }),
+    toolMsg('w1', 'written'),
+    asstCall('r1', 'vfs_read', { path: 'A' }),
+    toolMsg('r1', big()),
+  ];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['w1', reg({ on: { kind: 'superseded', by: 'A' }, args: 'pointer' })],
+    ['r1', reg({ on: { kind: 'superseded', by: 'A' }, response: 'pointer' })],
+  ]);
+  const { events, on } = sink();
+  const out = applyCondensation(history, policies, ctx(), on);
+
+  // Earlier write is superseded by the later read of the same key → its args collapse.
+  assert.match(String(out[0].toolCalls![0].args.condensed), /re-call to restore/);
+  // The read is the latest for key A → its response stays full.
+  assert.is(out[3].toolResult!.content, big());
+  assert.is(events.length, 1);
+  assert.is(events[0].toolCallId, 'w1');
+  assert.is(events[0].target, 'args');
+});
+
+// ---------------------------------------------------------------------------
+// age
+// ---------------------------------------------------------------------------
+
+suite('age: the model sees the result on `turns` turns, then it collapses', () => {
+  // Call made on iteration 1 → the result is first visible to the model on
+  // iteration 2. With turns:1 it may be read on that one turn, then collapses.
+  const history: ChatMessage[] = [asstCall('g1', 'grep_source', {}), toolMsg('g1', big())];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['g1', reg({ on: { kind: 'age', turns: 1 }, response: 'pointer' }, { iteration: 1 })],
+  ]);
+  const { events, on } = sink();
+
+  // Iteration 2 — its one allowed look: still full, nothing reported.
+  const seen = applyCondensation(history, policies, ctx({ modelCall: 2 }), on);
+  assert.is(seen[1].toolResult!.content, big(), 'full on the one turn it may be seen');
+  assert.is(events.length, 0, 'not collapsed while the model may still see it');
+
+  // Iteration 3 — one turn past the allowed view: collapses.
+  const collapsed = applyCondensation(history, policies, ctx({ modelCall: 3 }), on);
+  assert.match(collapsed[1].toolResult!.content, /aged out/);
+  assert.match(collapsed[1].toolResult!.content, /re-call to restore/);
+  assert.is(events.length, 1);
+  assert.is(events[0].trigger, 'age:1');
+});
+
+// ---------------------------------------------------------------------------
+// min-size floor
+// ---------------------------------------------------------------------------
+
+suite('payloads below the size floor are never condensed', () => {
+  const history: ChatMessage[] = [
+    asstCall('r1', 'vfs_read', { path: 'A' }),
+    toolMsg('r1', 'tiny'),
+    asstCall('r2', 'vfs_read', { path: 'A' }),
+    toolMsg('r2', big()),
+  ];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['r1', reg({ on: { kind: 'superseded', by: 'A' }, response: 'pointer' })],
+    ['r2', reg({ on: { kind: 'superseded', by: 'A' }, response: 'pointer' })],
+  ]);
+  const { events, on } = sink();
+  const out = applyCondensation(history, policies, ctx(), on);
+
+  assert.is(out[1].toolResult!.content, 'tiny', 'superseded but too small to bother');
+  assert.is(events.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// result modes
+// ---------------------------------------------------------------------------
+
+suite('drop / pointer / replaceWith produce distinct collapsed forms', () => {
+  const mk = (id: string, result: CondensePolicy['response']): [ChatMessage, ChatMessage] => [
+    asstCall(id, 'vfs_read', { path: id }),
+    toolMsg(id, big()),
+  ];
+  // Each call is superseded by a later same-key call so it actually fires.
+  const history: ChatMessage[] = [
+    ...mk('drop', 'drop'),
+    asstCall('drop2', 'vfs_read', { path: 'drop' }),
+    toolMsg('drop2', big()),
+    ...mk('ptr', 'pointer'),
+    asstCall('ptr2', 'vfs_read', { path: 'ptr' }),
+    toolMsg('ptr2', big()),
+    ...mk('rep', { replaceWith: 'SUMMARY' }),
+    asstCall('rep2', 'vfs_read', { path: 'rep' }),
+    toolMsg('rep2', big()),
+  ];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['drop', reg({ on: { kind: 'superseded', by: 'drop' }, response: 'drop' })],
+    ['drop2', reg({ on: { kind: 'superseded', by: 'drop' }, response: 'drop' })],
+    ['ptr', reg({ on: { kind: 'superseded', by: 'ptr' }, response: 'pointer' })],
+    ['ptr2', reg({ on: { kind: 'superseded', by: 'ptr' }, response: 'pointer' })],
+    ['rep', reg({ on: { kind: 'superseded', by: 'rep' }, response: { replaceWith: 'SUMMARY' } })],
+    ['rep2', reg({ on: { kind: 'superseded', by: 'rep' }, response: { replaceWith: 'SUMMARY' } })],
+  ]);
+  const { on } = sink();
+  const out = applyCondensation(history, policies, ctx(), on);
+
+  assert.is(out[1].toolResult!.content, '[elided]', 'drop is a minimal non-empty placeholder');
+  assert.match(
+    out[5].toolResult!.content,
+    /re-call to restore/,
+    'pointer carries the restore hint',
+  );
+  assert.is(out[9].toolResult!.content, 'SUMMARY', 'replaceWith is verbatim — no hint appended');
+});
+
+suite('args drop yields an empty object; pointer stashes a stub under one key', () => {
+  const history: ChatMessage[] = [
+    asstCall('w1', 'vfs_write', { path: 'A', content: big() }),
+    toolMsg('w1', 'ok'),
+    asstCall('w2', 'vfs_write', { path: 'A', content: big() }),
+    toolMsg('w2', 'ok'),
+  ];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['w1', reg({ on: { kind: 'superseded', by: 'A' }, args: 'drop' })],
+    ['w2', reg({ on: { kind: 'superseded', by: 'A' }, args: 'drop' })],
+  ]);
+  const { on } = sink();
+  const out = applyCondensation(history, policies, ctx(), on);
+  assert.equal(out[0].toolCalls![0].args, {}, 'dropped args is an empty object');
+  assert.equal(out[2].toolCalls![0].args, { path: 'A', content: big() }, 'latest write kept');
+});
+
+// ---------------------------------------------------------------------------
+// envelope + metadata invariants
+// ---------------------------------------------------------------------------
+
+suite('collapsing args preserves the tool-call envelope and providerMetadata', () => {
+  const history: ChatMessage[] = [
+    asstCall(
+      'w1',
+      'vfs_write',
+      { path: 'A', content: big() },
+      { providerMetadata: { sig: 'keep' } },
+    ),
+    toolMsg('w1', 'ok'),
+    asstCall('w2', 'vfs_write', { path: 'A', content: big() }),
+    toolMsg('w2', 'ok'),
+  ];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['w1', reg({ on: { kind: 'superseded', by: 'A' }, args: 'pointer' })],
+    ['w2', reg({ on: { kind: 'superseded', by: 'A' }, args: 'pointer' })],
+  ]);
+  const { on } = sink();
+  const out = applyCondensation(history, policies, ctx(), on);
+  const tc = out[0].toolCalls![0];
+  assert.is(tc.id, 'w1', 'id preserved');
+  assert.is(tc.name, 'vfs_write', 'name preserved');
+  assert.equal(tc.providerMetadata, { sig: 'keep' }, 'reasoning signature round-trips');
+});
+
+// ---------------------------------------------------------------------------
+// report-once + no-op
+// ---------------------------------------------------------------------------
+
+suite('the event fires once per payload across repeated applies', () => {
+  const history: ChatMessage[] = [
+    asstCall('r1', 'vfs_read', { path: 'A' }),
+    toolMsg('r1', big()),
+    asstCall('r2', 'vfs_read', { path: 'A' }),
+    toolMsg('r2', big()),
+  ];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['r1', reg({ on: { kind: 'superseded', by: 'A' }, response: 'pointer' })],
+    ['r2', reg({ on: { kind: 'superseded', by: 'A' }, response: 'pointer' })],
+  ]);
+  const { events, on } = sink();
+  applyCondensation(history, policies, ctx(), on);
+  applyCondensation(history, policies, ctx(), on);
+  applyCondensation(history, policies, ctx(), on);
+  assert.is(events.length, 1, 'collapse re-runs every call but the transition is reported once');
+});
+
+suite('an empty registry is a pure pass-through (same array reference)', () => {
+  const history: ChatMessage[] = [asstCall('r1', 'vfs_read'), toolMsg('r1', big())];
+  const { events, on } = sink();
+  const out = applyCondensation(history, new Map(), ctx(), on);
+  assert.is(out, history);
+  assert.is(events.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// turnEnd
+// ---------------------------------------------------------------------------
+
+suite('turnEnd: full during its own turn, collapsed on a later turn', () => {
+  const history: ChatMessage[] = [asstCall('t1', 'read'), toolMsg('t1', big())];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['t1', reg({ on: { kind: 'turnEnd' }, response: 'pointer' }, { turn: 1 })],
+  ]);
+  const { events, on } = sink();
+
+  const sameTurn = applyCondensation(history, policies, ctx({ turn: 1 }), on);
+  assert.is(sameTurn[1].toolResult!.content, big(), 'full for the rest of the request');
+  assert.is(events.length, 0);
+
+  const laterTurn = applyCondensation(history, policies, ctx({ turn: 2 }), on);
+  assert.match(laterTurn[1].toolResult!.content, /turn ended/);
+  assert.is(events.length, 1);
+  assert.is(events[0].trigger, 'turnEnd');
+});
+
+// ---------------------------------------------------------------------------
+// agentEnd
+// ---------------------------------------------------------------------------
+
+suite('agentEnd: kept while the agent is active, collapsed once its activation ends', () => {
+  const history: ChatMessage[] = [asstCall('a1', 'load'), toolMsg('a1', big())];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['a1', reg({ on: { kind: 'agentEnd' }, response: 'pointer' }, { activation: 1 })],
+  ]);
+  const { events, on } = sink();
+
+  const active = applyCondensation(history, policies, ctx({ activationEnded: () => false }), on);
+  assert.is(active[1].toolResult!.content, big(), 'full while the agent flow is active');
+  assert.is(events.length, 0);
+
+  const ended = applyCondensation(history, policies, ctx({ activationEnded: (a) => a === 1 }), on);
+  assert.match(ended[1].toolResult!.content, /agent finished/);
+  assert.is(events.length, 1);
+  assert.is(events[0].trigger, 'agentEnd');
+});
+
+// ---------------------------------------------------------------------------
+// multi-trigger (OR / first-wins)
+// ---------------------------------------------------------------------------
+
+suite('multi-trigger: collapses when ANY listed trigger fires', () => {
+  // superseded OR turnEnd — only one call for key A (never superseded), but the turn ends.
+  const history: ChatMessage[] = [asstCall('m1', 'read', { path: 'A' }), toolMsg('m1', big())];
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    [
+      'm1',
+      reg(
+        { on: [{ kind: 'superseded', by: 'A' }, { kind: 'turnEnd' }], response: 'pointer' },
+        { turn: 1 },
+      ),
+    ],
+  ]);
+  const { events, on } = sink();
+
+  assert.is(
+    applyCondensation(history, policies, ctx({ turn: 1 }), on)[1].toolResult!.content,
+    big(),
+    'neither trigger has fired',
+  );
+  const later = applyCondensation(history, policies, ctx({ turn: 2 }), on);
+  assert.match(later[1].toolResult!.content, /turn ended/, 'turnEnd fired via the OR');
+  assert.is(events[0].trigger, 'turnEnd');
+});
+
+suite('multi-trigger first-wins: the earliest-listed firing trigger is the reason', () => {
+  // m1 is superseded by m2 AND its turn has ended; m2 is the latest (not superseded)
+  // but its turn has ended too. `superseded` is listed first.
+  const history: ChatMessage[] = [
+    asstCall('m1', 'read', { path: 'A' }),
+    toolMsg('m1', big()),
+    asstCall('m2', 'read', { path: 'A' }),
+    toolMsg('m2', big()),
+  ];
+  const on0: CondensePolicy = {
+    on: [{ kind: 'superseded', by: 'A' }, { kind: 'turnEnd' }],
+    response: 'pointer',
+  };
+  const policies = new Map<string, RegisteredCondensePolicy>([
+    ['m1', reg(on0, { turn: 1 })],
+    ['m2', reg(on0, { turn: 1 })],
+  ]);
+  const { events, on } = sink();
+  applyCondensation(history, policies, ctx({ turn: 2 }), on);
+
+  assert.is(
+    events.find((e) => e.toolCallId === 'm1')?.trigger,
+    'superseded:A',
+    'first-listed firing trigger wins as the reason',
+  );
+  assert.is(
+    events.find((e) => e.toolCallId === 'm2')?.trigger,
+    'turnEnd',
+    'the supersession survivor still collapses via the next trigger',
+  );
+});
+
+suite.run();