@genesislcap/ai-assistant 14.467.2 → 14.468.0

package/dist/esm/components/chat-driver/chat-driver.test.js

@@ -14,15 +14,20 @@ const scriptedProvider = (responses) => {
     const advertisedPerCall = [];
     const toolChoicePerCall = [];
     const temperaturePerCall = [];
+    const historyPerCall = [];
     return {
         advertisedPerCall,
         toolChoicePerCall,
         temperaturePerCall,
-        chat: (_history, _userMessage, options) => __awaiter(void 0, void 0, void 0, function* () {
+        historyPerCall,
+        chat: (history, _userMessage, options) => __awaiter(void 0, void 0, void 0, function* () {
             var _a, _b;
             advertisedPerCall.push(((_a = options === null || options === void 0 ? void 0 : options.tools) !== null && _a !== void 0 ? _a : []).map((t) => t.name));
             toolChoicePerCall.push(options === null || options === void 0 ? void 0 : options.toolChoice);
             temperaturePerCall.push(options === null || options === void 0 ? void 0 : options.temperature);
+            // Snapshot the slice (condensation produces fresh objects per call and never
+            // mutates stored history, so a shallow array copy is a stable per-call view).
+            historyPerCall.push([...history]);
             // Once the script is exhausted, end the turn with a plain text reply.
             return (_b = queue.shift()) !== null && _b !== void 0 ? _b : { role: 'assistant', content: 'done' };
         }),
@@ -1192,3 +1197,193 @@ modelAttr('omits the model key entirely when the provider reports no status', ()
     driver.dispose();
 }));
 modelAttr.run();
+// ---------------------------------------------------------------------------
+// condenseWhen — tool-declared context condensation (wiring through the loop)
+// ---------------------------------------------------------------------------
+const condense = createLogicSuite('ChatDriver condenseWhen');
+condense.after(() => {
+    agenticActivityBus.close();
+});
+const bigBody = 'A'.repeat(2000);
+/** An assistant turn calling `read` with a path arg (so `by: args.path` resolves). */
+const readsPath = (id, path) => ({
+    role: 'assistant',
+    content: '',
+    toolCalls: [{ id, name: 'read', args: { path } }],
+});
+condense('collapses a superseded result in the model slice but keeps stored history full', () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a, _b;
+    const sessionKey = 'condense-supersede';
+    clearMetaEventRegistry();
+    const provider = scriptedProvider([
+        readsPath('r1', 'A'),
+        readsPath('r2', 'A'), // re-read of the same path supersedes r1
+    ]);
+    const config = agent({
+        name: 'reader',
+        systemPrompt: 'read files',
+        toolDefinitions: [def('read')],
+        toolHandlers: {
+            read: (args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+                ctx.condenseWhen({
+                    on: { kind: 'superseded', by: String(args.path) },
+                    response: 'pointer',
+                });
+                return bigBody;
+            }),
+        },
+    });
+    const driver = makeDriver(config, provider, sessionKey);
+    const result = yield driver.sendMessage('go');
+    assert.is(result.reason, 'done');
+    // The 3rd provider call (index 2) ran after both reads: r1 is superseded, r2 is latest.
+    const slice = provider.historyPerCall[2];
+    const r1 = slice.find((m) => { var _a; return ((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.toolCallId) === 'r1'; });
+    const r2 = slice.find((m) => { var _a; return ((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.toolCallId) === 'r2'; });
+    assert.match(r1.toolResult.content, /re-call to restore/, 'earlier read collapsed for the model');
+    assert.is(r2.toolResult.content, bigBody, 'latest read still full');
+    // Stored history is untouched — both reads remain full for the UI / debug export.
+    assert.is(toolResultContents(driver).filter((c) => c === bigBody).length, 2, 'stored history retains both full reads');
+    // One context.condensed meta-event, for r1's response, recorded once.
+    const events = getMetaEvents(sessionKey).filter((e) => e.type === 'context.condensed');
+    assert.is(events.length, 1, 'the full→stub transition is reported exactly once');
+    assert.is((_a = events[0].detail) === null || _a === void 0 ? void 0 : _a.toolCallId, 'r1');
+    assert.is((_b = events[0].detail) === null || _b === void 0 ? void 0 : _b.target, 'response');
+}));
+condense('first-wins: a second condenseWhen for the same tool call is ignored', () => __awaiter(void 0, void 0, void 0, function* () {
+    const sessionKey = 'condense-first-wins';
+    clearMetaEventRegistry();
+    const provider = scriptedProvider([readsPath('r1', 'A'), readsPath('r2', 'A')]);
+    const config = agent({
+        name: 'reader',
+        systemPrompt: 'read files',
+        toolDefinitions: [def('read')],
+        toolHandlers: {
+            read: (args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+                // First declaration wins; the second (a different mode) is dropped.
+                ctx.condenseWhen({
+                    on: { kind: 'superseded', by: String(args.path) },
+                    response: 'pointer',
+                });
+                ctx.condenseWhen({
+                    on: { kind: 'superseded', by: String(args.path) },
+                    response: { replaceWith: 'SECOND' },
+                });
+                return bigBody;
+            }),
+        },
+    });
+    const driver = makeDriver(config, provider, sessionKey);
+    yield driver.sendMessage('go');
+    const collapsed = provider.historyPerCall[2].find((m) => { var _a; return ((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.toolCallId) === 'r1'; });
+    assert.match(collapsed.toolResult.content, /re-call to restore/, 'the first (pointer) policy applied');
+    assert.is.not(collapsed.toolResult.content, 'SECOND', 'the later policy was ignored');
+}));
+condense('age clock is monotonic across turns — collapses on a later, separate turn', () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    // Regression guard for the per-turn-reset bug: the age clock is the local loop
+    // counter that resets every `sendMessage`, so an `age` payload from turn 1
+    // would never collapse across short turns. The driver now uses a monotonic
+    // model-call counter, so it does.
+    const sessionKey = 'condense-age-cross-turn';
+    clearMetaEventRegistry();
+    const provider = scriptedProvider([
+        { role: 'assistant', content: '', toolCalls: [{ id: 'n1', name: 'notes', args: {} }] }, // turn 1, call 1
+        { role: 'assistant', content: 'noted' }, // turn 1, call 2 — model sees n1 once (full), turn ends
+        { role: 'assistant', content: 'ok' }, // turn 2, call 1 — a short follow-up, no tools
+    ]);
+    const config = agent({
+        name: 'note-taker',
+        systemPrompt: 'take notes',
+        toolDefinitions: [def('notes')],
+        toolHandlers: {
+            notes: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+                ctx.condenseWhen({ on: { kind: 'age', turns: 1 }, response: 'pointer' });
+                return bigBody;
+            }),
+        },
+    });
+    const driver = makeDriver(config, provider, sessionKey);
+    yield driver.sendMessage('first'); // turn 1
+    yield driver.sendMessage('second'); // turn 2 — a separate, short sendMessage
+    // Turn 1's consume call (provider call #1) saw n1 in full — its one allowed look.
+    const turn1Consume = provider.historyPerCall[1].find((m) => { var _a; return ((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.toolCallId) === 'n1'; });
+    assert.is(turn1Consume.toolResult.content, bigBody, 'full on its one allowed turn');
+    // Turn 2's first call (#2) is a SEPARATE sendMessage — the local loop counter has
+    // reset to 0, but the monotonic clock kept counting, so n1 is now collapsed.
+    // Under the old per-turn counter it would still be full here.
+    const turn2 = provider.historyPerCall[2].find((m) => { var _a; return ((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.toolCallId) === 'n1'; });
+    assert.match(turn2.toolResult.content, /re-call to restore/, 'collapsed on the next turn');
+    assert.ok(toolResultContents(driver).includes(bigBody), 'stored history retains the full note');
+    const events = getMetaEvents(sessionKey).filter((e) => e.type === 'context.condensed');
+    assert.is(events.length, 1);
+    assert.is((_a = events[0].detail) === null || _a === void 0 ? void 0 : _a.trigger, 'age:1');
+}));
+condense('turnEnd: full during its request, collapsed on the next user turn', () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const sessionKey = 'condense-turn-end';
+    clearMetaEventRegistry();
+    const provider = scriptedProvider([
+        { role: 'assistant', content: '', toolCalls: [{ id: 'n1', name: 'notes', args: {} }] }, // turn 1, call 1
+        { role: 'assistant', content: 'noted' }, // turn 1, call 2 — n1 still full this turn
+        { role: 'assistant', content: 'ok' }, // turn 2 — a separate request
+    ]);
+    const config = agent({
+        name: 'note-taker',
+        systemPrompt: 'take notes',
+        toolDefinitions: [def('notes')],
+        toolHandlers: {
+            notes: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+                ctx.condenseWhen({ on: { kind: 'turnEnd' }, response: 'pointer' });
+                return bigBody;
+            }),
+        },
+    });
+    const driver = makeDriver(config, provider, sessionKey);
+    yield driver.sendMessage('first'); // turn 1
+    yield driver.sendMessage('second'); // turn 2
+    const inTurn1 = provider.historyPerCall[1].find((m) => { var _a; return ((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.toolCallId) === 'n1'; });
+    assert.is(inTurn1.toolResult.content, bigBody, 'full for the rest of the request it served');
+    const inTurn2 = provider.historyPerCall[2].find((m) => { var _a; return ((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.toolCallId) === 'n1'; });
+    assert.match(inTurn2.toolResult.content, /re-call to restore/, 'collapsed once the turn ended');
+    const events = getMetaEvents(sessionKey).filter((e) => e.type === 'context.condensed');
+    assert.is(events.length, 1);
+    assert.is((_a = events[0].detail) === null || _a === void 0 ? void 0 : _a.trigger, 'turnEnd');
+}));
+condense('agentEnd: collapses once the agent releases (flow complete)', () => __awaiter(void 0, void 0, void 0, function* () {
+    var _a;
+    const sessionKey = 'condense-agent-end';
+    clearMetaEventRegistry();
+    const provider = scriptedProvider([
+        { role: 'assistant', content: '', toolCalls: [{ id: 's1', name: 'load', args: {} }] }, // call 1
+        { role: 'assistant', content: '', toolCalls: [{ id: 'f1', name: 'finish', args: {} }] }, // call 2 — releases
+        { role: 'assistant', content: 'wrapped up' }, // call 3 — flow done
+    ]);
+    const config = agent({
+        name: 'wizard',
+        systemPrompt: 'a flow',
+        toolDefinitions: [def('load'), def('finish')],
+        toolHandlers: {
+            load: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+                ctx.condenseWhen({ on: { kind: 'agentEnd' }, response: 'pointer' });
+                return bigBody;
+            }),
+            finish: (_args, ctx) => __awaiter(void 0, void 0, void 0, function* () {
+                ctx.releaseAgent();
+                return 'flow complete';
+            }),
+        },
+    });
+    const driver = makeDriver(config, provider, sessionKey);
+    yield driver.sendMessage('run the flow');
+    // call #2 (index 1) ran before `finish` released — schema still full.
+    const beforeRelease = provider.historyPerCall[1].find((m) => { var _a; return ((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.toolCallId) === 's1'; });
+    assert.is(beforeRelease.toolResult.content, bigBody, 'full while the flow is active');
+    // call #3 (index 2) ran after release — schema collapsed.
+    const afterRelease = provider.historyPerCall[2].find((m) => { var _a; return ((_a = m.toolResult) === null || _a === void 0 ? void 0 : _a.toolCallId) === 's1'; });
+    assert.match(afterRelease.toolResult.content, /re-call to restore/, 'collapsed once released');
+    const events = getMetaEvents(sessionKey).filter((e) => e.type === 'context.condensed');
+    assert.is(events.length, 1);
+    assert.is((_a = events[0].detail) === null || _a === void 0 ? void 0 : _a.trigger, 'agentEnd');
+}));
+condense.run();

package/dist/esm/state/debug-event-log.js

@@ -61,6 +61,7 @@ export const META_EVENT_IMPORTANCE = {
     'driver.wired': 'low',
     'driver.unwired': 'low',
     'context.updated': 'low',
+    'context.condensed': 'low',
     'panel.toggled': 'low',
     'attachment.added': 'low',
 };
@@ -188,8 +189,8 @@ export const DEBUG_LOG_README = [
     "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/dist/esm/utils/condense-history.js

@@ -0,0 +1,218 @@
+/**
+ * Tool-context condensation: collapse stale tool payloads out of the history
+ * sent to the model, while leaving stored history untouched.
+ *
+ * The driver owns the registry (tool handlers populate it via `condenseWhen`)
+ * and the cadence (this runs before every provider call). This module owns the
+ * pure application: given the registry + the current loop iteration, produce a
+ * rewritten copy of the history with stale args/results replaced by stubs. Kept
+ * pure (no driver/session state, no logging) so it unit-tests in isolation —
+ * the one-time `context.condensed` signal is delivered via an `onCondensed`
+ * callback rather than reaching into the debug-event log directly.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Below this serialized size a tool payload isn't worth condensing — the stub
+ * would save little and cost a breadcrumb. A driver-level floor so the public
+ * `condenseWhen` API needs no per-policy threshold field.
+ */
+export const CONDENSE_MIN_CHARS = 1000;
+/** Key the collapsed args are stored under — a tool-call's args must stay a Record. */
+export const CONDENSED_ARGS_KEY = 'condensed';
+/**
+ * Rough chars-per-token divisor for the `tokensSaved` estimate. No tokenizer is
+ * available in this stack; ~4 chars/token is the usual English approximation.
+ */
+const APPROX_CHARS_PER_TOKEN = 4;
+/** Short human-readable reason for the stub text, per fired trigger. */
+function triggerReason(trigger) {
+    switch (trigger.kind) {
+        case 'age':
+            return 'aged out';
+        case 'turnEnd':
+            return 'turn ended';
+        case 'agentEnd':
+            return 'agent finished';
+        default:
+            return 'superseded';
+    }
+}
+/** Framework-generated `pointer` stub — advertises that re-calling restores the content. */
+function condenseStub(target, tool, trigger, origLen) {
+    const what = target === 'args' ? 'args' : 'result';
+    const key = trigger.kind === 'superseded' ? ` ${trigger.by}` : '';
+    return `[${tool}${key} — ${what} elided, ~${origLen} chars (${triggerReason(trigger)}); re-call to restore]`;
+}
+/** Stable label for the `context.condensed` meta-event's `trigger` field. */
+function triggerLabel(trigger) {
+    switch (trigger.kind) {
+        case 'age':
+            return `age:${trigger.turns}`;
+        case 'superseded':
+            return `superseded:${trigger.by}`;
+        default:
+            return trigger.kind; // 'turnEnd' | 'agentEnd'
+    }
+}
+function estimateTokensSaved(origLen, stubLen) {
+    return Math.max(0, Math.ceil((origLen - stubLen) / APPROX_CHARS_PER_TOKEN));
+}
+/**
+ * Collapse stale tool payloads (declared via `condenseWhen`) out of the
+ * model-bound history. Pure over the `history` array — it emits new message
+ * objects and never mutates the input messages (mirroring the agent-masking
+ * transform). It DOES, however, flip the `reported*` flag on the matching
+ * `policies` entry the first time a payload collapses — the report-once gate that
+ * keeps `onCondensed` firing once per (tool call, payload) even though the
+ * collapse itself re-runs before every provider call.
+ *
+ * Triggers (a policy may list several via `on: Trigger[]` — the FIRST to fire
+ * collapses the payload; all are monotonic, so the collapse never reverts):
+ * - `superseded` — among all registered calls sharing a `by` key, the LAST in
+ *   history order survives; every earlier one's targeted payload collapses. A
+ *   re-call with the same key becomes the new survivor and re-arms the rest.
+ * - `age` — the result is first visible one model-call after the call, so `turns`
+ *   is how many model-calls may see the full result before it collapses
+ *   (fires when `modelCall − callModelCall > turns`): `turns: 1` is seen once,
+ *   then collapses. The clock is monotonic across turns.
+ * - `turnEnd` — collapses once the turn (`sendMessage`) that made the call has
+ *   ended (fires when `turn > callTurn`): full for the rest of that request,
+ *   gone on every later one.
+ * - `agentEnd` — collapses once the agent activation that made the call has ended
+ *   (a swap to another agent, or `releaseAgent`/`completeSubAgent`): kept across
+ *   all of the agent's turns, dropped when its flow finishes.
+ *
+ * The tool-call/result envelope is never removed (providers reject orphaned
+ * calls/results) — only the args object or the result content is replaced.
+ *
+ * @param history - The to-model history copy to rewrite (not mutated).
+ * @param policies - The driver's registry, keyed by tool-call id. Its entries'
+ *   `reported*` flags are flipped as payloads first collapse.
+ * @param ctx - The driver's live clocks (model-call / turn / agent-activation).
+ * @param onCondensed - Invoked once per payload at its full→stub transition.
+ */
+export function applyCondensation(history, policies, ctx, onCondensed) {
+    var _a;
+    if (policies.size === 0)
+        return history;
+    const triggersOf = (entry) => Array.isArray(entry.policy.on) ? entry.policy.on : [entry.policy.on];
+    // One pass: resolve supersession survivors and a toolCallId → tool-name
+    // 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.
+    const latestByKey = new Map();
+    const nameById = new Map();
+    for (const msg of history) {
+        if (!((_a = msg.toolCalls) === null || _a === void 0 ? void 0 : _a.length))
+            continue;
+        for (const tc of msg.toolCalls) {
+            nameById.set(tc.id, tc.name);
+            const entry = policies.get(tc.id);
+            if (!entry)
+                continue;
+            for (const t of triggersOf(entry)) {
+                if (t.kind === 'superseded')
+                    latestByKey.set(t.by, tc.id);
+            }
+        }
+    }
+    const triggerFires = (toolCallId, entry, trig) => {
+        switch (trig.kind) {
+            // Result first visible one model-call after the call, so collapse one call
+            // 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;
+            case 'turnEnd':
+                return ctx.turn > entry.turn;
+            case 'agentEnd':
+                return ctx.activationEnded(entry.activation);
+            default:
+                return latestByKey.get(trig.by) !== toolCallId; // superseded by a newer call
+        }
+    };
+    // The first listed trigger that fires — drives the collapse, the stub reason,
+    // and the event label. `undefined` means the payload stays full.
+    const firstFired = (toolCallId, entry) => triggersOf(entry).find((t) => triggerFires(toolCallId, entry, t));
+    return history.map((msg) => {
+        var _a, _b, _c, _d;
+        // Tool-call ARGS live on the assistant message.
+        if ((_a = msg.toolCalls) === null || _a === void 0 ? void 0 : _a.length) {
+            let changed = false;
+            const toolCalls = msg.toolCalls.map((tc) => {
+                var _a;
+                const entry = policies.get(tc.id);
+                if (!(entry === null || entry === void 0 ? void 0 : entry.policy.args))
+                    return tc;
+                const fired = firstFired(tc.id, entry);
+                if (!fired)
+                    return tc;
+                const origLen = JSON.stringify((_a = tc.args) !== null && _a !== void 0 ? _a : {}).length;
+                if (origLen < CONDENSE_MIN_CHARS)
+                    return tc;
+                changed = true;
+                const result = entry.policy.args;
+                // Args must stay a Record; `drop` is an empty object, otherwise stash the
+                // stub under a single key. Spread `tc` so providerMetadata (e.g. the
+                // Gemini reasoning signature that must round-trip) and UI fields survive.
+                const args = result === 'drop'
+                    ? {}
+                    : {
+                        [CONDENSED_ARGS_KEY]: result === 'pointer'
+                            ? condenseStub('args', tc.name, fired, origLen)
+                            : result.replaceWith,
+                    };
+                if (!entry.reportedArgs) {
+                    entry.reportedArgs = true;
+                    const stubLen = JSON.stringify(args).length;
+                    onCondensed({
+                        turn: entry.iteration,
+                        toolCallId: tc.id,
+                        tool: tc.name,
+                        target: 'args',
+                        trigger: triggerLabel(fired),
+                        stubLen,
+                        tokensSaved: estimateTokensSaved(origLen, stubLen),
+                    });
+                }
+                return Object.assign(Object.assign({}, tc), { args });
+            });
+            return changed ? Object.assign(Object.assign({}, msg), { toolCalls }) : msg;
+        }
+        // The tool RESULT lives on the tool message.
+        if (msg.toolResult) {
+            const entry = policies.get(msg.toolResult.toolCallId);
+            // Defensive `?? 0` for restored/malformed history — `content` is typed
+            // `string`, but a 0-length payload is simply below the floor and skipped.
+            const origLen = (_c = (_b = msg.toolResult.content) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0;
+            const fired = (entry === null || entry === void 0 ? void 0 : entry.policy.response)
+                ? firstFired(msg.toolResult.toolCallId, entry)
+                : undefined;
+            if (entry && fired && origLen >= CONDENSE_MIN_CHARS) {
+                const tool = (_d = nameById.get(msg.toolResult.toolCallId)) !== null && _d !== void 0 ? _d : msg.toolResult.toolCallId;
+                const result = entry.policy.response; // `fired` is only set when response is declared
+                // Kept non-empty — Anthropic rejects empty tool_result content.
+                const content = result === 'drop'
+                    ? '[elided]'
+                    : result === 'pointer'
+                        ? condenseStub('response', tool, fired, origLen)
+                        : result.replaceWith;
+                if (!entry.reportedResponse) {
+                    entry.reportedResponse = true;
+                    onCondensed({
+                        turn: entry.iteration,
+                        toolCallId: msg.toolResult.toolCallId,
+                        tool,
+                        target: 'response',
+                        trigger: triggerLabel(fired),
+                        stubLen: content.length,
+                        tokensSaved: estimateTokensSaved(origLen, content.length),
+                    });
+                }
+                return Object.assign(Object.assign({}, msg), { toolResult: Object.assign(Object.assign({}, msg.toolResult), { content }) });
+            }
+        }
+        return msg;
+    });
+}