@aragon-agent/cli 0.6.1 → 0.6.3

package/dist/agent/controller.d.ts

@@ -9,7 +9,7 @@
  * from the event stream by the reducer (TUI) and the headless writer.
  */
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
-import type { CliConfig, FastConfig, RetryConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
+import type { CliConfig, CompactionConfig, FastConfig, RetryConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
 import { type ConfirmRequest } from '../tools/index.js';
 import type { ToolPermission } from '../exec/permission.js';
 import { type ToolOutputListener } from '../tools/tool-output-store.js';
@@ -17,6 +17,7 @@ import type { FilePatch } from '../tools/patch.js';
 import type { TeamEvent, TeamSnapshot } from '../team/types.js';
 import { type FastStatus } from '../fast/wiring.js';
 import type { FastEventListener } from '../fast/types.js';
+import type { CompactionEventListener, CompactionSnapshot } from '../compaction/types.js';
 import type { TodoEventListener, TodoSnapshot } from '../todo/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
@@ -174,6 +175,7 @@ export declare class AgentController {
     private readonly toolOutputs;
     private readonly outputListeners;
     private readonly fast;
+    private readonly compaction;
     /**
      * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
      * Cleared at the next `agent_start`.
@@ -491,6 +493,77 @@ export declare class AgentController {
      * `subscribeTodos` already set.
      */
     subscribeFast(listener: FastEventListener): () => void;
+    /** Whether a `ContextManager` exists at all. Fixed at construction. */
+    isCompactionRegistered(): boolean;
+    /** Whether it will actually fire. Flipped live by `/compact on|off`. */
+    isCompactionEnabled(): boolean;
+    /**
+     * Flip the live switch.
+     *
+     * A NO-OP WHEN NOTHING IS REGISTERED, and `/compact` reports that honestly by
+     * checking `isCompactionRegistered()` first — the `/fast on` and `/team on`
+     * shape. `enabled` decides whether the wiring EXISTS, which happens once at
+     * construction and cannot be undone: a session that started with no manager
+     * would have to be given one mid-flight, and the `Agent` has no setter for it
+     * on purpose (§3.2).
+     */
+    setCompactionEnabled(enabled: boolean): void;
+    getCompactionConfig(): CompactionConfig;
+    /**
+     * Adopt a new compaction config for this session.
+     *
+     * THE `onConfigChanged` CALL IS NOT OPTIONAL, for the reason `setFastConfig`
+     * records: a persist without it reports success and changes nothing visible
+     * until relaunch, because the chip and `/compact status` read a snapshot.
+     */
+    setCompactionConfig(patch: Partial<CompactionConfig>): CompactionConfig;
+    /** Everything `/compact status`, the settings row and the chip read. */
+    getCompactionSnapshot(): CompactionSnapshot;
+    /**
+     * The `ModelRef` the next compaction would summarize with, or `null`.
+     *
+     * IT IS CARRIED, NEVER RE-DERIVED, and that is the whole reason it exists. The
+     * summarizer is the fast tier when `useFastTier` is on AND the tier resolves,
+     * and the session's own model otherwise — a combination no caller can
+     * reconstruct from `CliConfig` without re-implementing `resolveFastTier`, and
+     * one that a plausible guess (`fast.enabled ? fast.provider : provider`) gets
+     * WRONG whenever `fast.enabled` is true and `compaction.useFastTier` is false.
+     * Pricing the spend against the wrong provider looks up a model the static
+     * table has never seen, which prices it at `$0.00` — the C-11 / RV-4 lie, on
+     * the one feature that spends money without being asked (AC-15).
+     */
+    getCompactionSummarizerRef(): ModelRef | null;
+    /**
+     * This run's archive key, or `null` when compaction is unregistered
+     * (context-auto-compaction-hardening §3.5 / W4).
+     *
+     * `/compact history` and `/compact show` scope themselves to it, so a second
+     * `aragon` in another terminal is invisible here rather than interleaved with
+     * this one's compactions.
+     */
+    getCompactionRunId(): string | null;
+    /** Ask for a compaction at the next turn boundary (§4.4 / D-17). */
+    queueCompaction(instructions?: string): void;
+    /**
+     * The IDLE `/compact` path (§4.4 / D-25).
+     *
+     * IT VALIDATES BEFORE IT SPLICES. `CompactionWiring.compactNow` runs
+     * `validateHistory` itself and refuses on failure, because with no loop running
+     * the engine's own gate is unreachable and D-4 declares that gate
+     * unbypassable. `replaceMessages` validates NOTHING.
+     */
+    compactNow(instructions?: string): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    /**
+     * Subscribe to the CLI-local compaction event stream.
+     *
+     * Returns a no-op unsubscribe when compaction was off at construction, so
+     * every caller can subscribe unconditionally — the contract `subscribeTeam`,
+     * `subscribeTodos` and `subscribeFast` already set.
+     */
+    subscribeCompaction(listener: CompactionEventListener): () => void;
     /** List usable tools (name + description) for the /tools command. */
     listTools(): AgentTool[];
 }

package/dist/agent/controller.js

@@ -9,7 +9,7 @@
  * from the event stream by the reducer (TUI) and the headless writer.
  */
 import { Agent, initProviders, ModelRegistry, } from '@aragon-agent/core';
-import { clampFastConfig, clampRetryConfig, clampTeamConfig, clampTodoConfig, isAdapterProvider, toRetryPolicy, } from '../config/schema.js';
+import { clampCompactionConfig, clampFastConfig, clampRetryConfig, clampTeamConfig, clampTodoConfig, isAdapterProvider, toRetryPolicy, } from '../config/schema.js';
 import { makeGetApiKey } from '../config/load.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { createBuiltinTools } from '../tools/index.js';
@@ -22,6 +22,7 @@ import { buildTeamBlock } from '../team/prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
 import { describeFastTierProblem, fastProviderOf, resolveFastTier } from '../fast/resolve.js';
 import { FastWiring, offFastStatus } from '../fast/wiring.js';
+import { CompactionWiring, offCompactionSnapshot } from '../compaction/wiring.js';
 import { TodoStore } from '../todo/store.js';
 import { createTodoTool } from '../todo/todo-tool.js';
 import { buildTodoBlock } from '../todo/prompt.js';
@@ -153,6 +154,24 @@ export class AgentController {
     // property, and `<fast_tier>` is never spliced (I-2).
     // -----------------------------------------------------------------------
     fast;
+    // -----------------------------------------------------------------------
+    // Context compaction (context-auto-compaction §3.2.1)
+    //
+    // ONE FIELD AND THIN FORWARDERS, the `fast` shape one feature later, and for
+    // the same budget reason (C-16): every piece of state — the guards, the
+    // ladder, the manual queue, the session totals — lives in
+    // `compaction/wiring.ts` and `compaction/compactor.ts`.
+    //
+    // `null` when `compaction.enabled` was false at construction, which is the
+    // byte-identity branch: no manager is passed to `new Agent({...})`, nothing is
+    // subscribed, no registry is allocated, and the engine loop's checkpoint is one
+    // `if` against a field that is genuinely absent (AC-1).
+    //
+    // CONSTRUCTED ABOVE `new Agent({...})` AND ATTACHED BELOW IT (C-12 / P0-2).
+    // The port has to be inside the Agent's constructor argument and the wiring has
+    // to subscribe to the Agent, and this class cannot do both in one step.
+    // -----------------------------------------------------------------------
+    compaction;
     /**
      * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
      * Cleared at the next `agent_start`.
@@ -217,6 +236,11 @@ export class AgentController {
         this.teamRuntime = this.teamRegistered
             ? new TeamRuntime({
                 getConfig: () => this.config,
+                // Read LIVE through the wiring, exactly as `resolveTier` below is: the
+                // closure is only ever called from inside a dispatch, and
+                // `childFactory()` re-reads `compaction.subagents` on every call so a
+                // settings-screen edit reaches the next dispatch.
+                contextManagerFor: (req) => this.compaction?.childFactory()?.(req),
                 // Read LIVE through the wiring, which does not exist yet — the closure
                 // is only ever called from inside a dispatch, long after construction.
                 resolveTier: (tier) => this.fast
@@ -379,6 +403,25 @@ export class AgentController {
             modelId: config.model,
             ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
         };
+        // --- Context compaction, part 1: BEFORE the Agent ----------------------
+        //
+        // It needs no agent reference to EXIST — only live config, the key
+        // resolvers, the model-info lookup and a notifier — which is exactly what
+        // makes the C-12 split work. `getMessages` / `getSystemPrompt` are LAZY for
+        // the same reason: `this.agent` is assigned on the very next statement, and
+        // they are only ever called from inside an event handler.
+        this.compaction = config.compaction.enabled
+            ? new CompactionWiring({
+                getConfig: () => this.config,
+                hasKey: (id) => this.hasApiKey(id),
+                getApiKey: (id) => this.resolveKey(id),
+                getModelInfoFor: (ref) => this.getModelInfoFor(ref),
+                isPricedModel: (ref) => this.isPricedModel(ref),
+                getMessages: () => this.agent.state.messages,
+                getSystemPrompt: () => this.agent.state.systemPrompt,
+                notify: (level, text) => deps.notify?.(level, text),
+            })
+            : null;
         this.agent = new Agent({
             systemPrompt: this.composeSystemPrompt(),
             model,
@@ -389,6 +432,13 @@ export class AgentController {
             // without rebuilding the Agent — the closure reads the current config.
             getApiKey: (id) => this.resolveKey(id),
             maxTokens: config.maxTokens,
+            // SPREAD CONDITIONALLY, never `contextManager: this.compaction?.manager()`.
+            // With the feature off the options bag has no such key, so the loop's gate
+            // tests a field that is genuinely `undefined` rather than a property
+            // holding `undefined` — which is what makes AC-1's byte-identity claim
+            // provable by construction rather than by inspection. `createBuiltinTools`
+            // above spreads `permission` for the identical reason (P1-2 / AC-28).
+            ...(this.compaction ? { contextManager: this.compaction.manager() } : {}),
             timeouts: {
                 // Timeout invariant (R1): idle ≥ tool so long tool runs are not killed.
                 toolTimeout: config.toolTimeoutMs,
@@ -408,6 +458,18 @@ export class AgentController {
                 },
             },
         });
+        // --- Context compaction, part 2: AFTER the Agent exists -----------------
+        //
+        // `attach` is what lets the wiring see `compaction_end` — the ENGINE's
+        // `applied` verdict, which the compactor cannot know because validation
+        // happens after `compact()` returns — and `agent_start`, which resets the
+        // per-run cap. It is idempotent, and `dispose()` unsubscribes.
+        //
+        // A SEPARATE CALL RATHER THAN A `subscribe` DEP LIKE `FastWiring`'s, and that
+        // is the constraint that makes the whole split work: a constructor that
+        // subscribed could not run before `new Agent(...)`, and the port has to be
+        // inside its constructor argument (C-12 / P0-2).
+        this.compaction?.attach((listener) => this.agent.subscribe(listener));
         // --- Fast tier, part 2: after the Agent exists --------------------------
         //
         // `FastWiring` subscribes to the lead's event stream, so it cannot be built
@@ -670,6 +732,11 @@ export class AgentController {
         // nothing ever clears (RV-1).
         this.abortRequested = true;
         this.fast?.abort();
+        // The engine also races `ctx.signal` inside `runCompaction`, so this is the
+        // same DELIBERATE REDUNDANCY the `teamRuntime` line below records: it makes
+        // "Esc cancels an in-flight summarization" a property of this class rather
+        // than a consequence of the compactor honouring a signal three modules away.
+        this.compaction?.abort();
         this.agent.abort();
         // DELIBERATE REDUNDANCY (§3.8). Aborting the lead already aborts the
         // in-flight `task` call's `ctx.signal`, which the runtime listens to — that
@@ -870,6 +937,7 @@ export class AgentController {
     dispose() {
         this.teamRuntime?.dispose();
         this.fast?.dispose();
+        this.compaction?.dispose();
     }
     // -----------------------------------------------------------------------
     // Todo planning (todo-plan-execution §3.6a)
@@ -991,6 +1059,10 @@ export class AgentController {
         // another vendor's gateway — and `<fast_tier>` would go on naming the model
         // it used to resolve to.
         this.fast?.onConfigChanged();
+        // The summarizer resolves from LIVE config too — it may BE the fast tier —
+        // so the snapshot the chip and `/compact status` read has to be refreshed
+        // for the same reason and at the same moments (the RV-3 lesson).
+        this.compaction?.onConfigChanged();
     }
     setThinkingLevel(level) {
         this.config = { ...this.config, thinkingLevel: level };
@@ -1010,6 +1082,10 @@ export class AgentController {
         // Rule 5 of §3.2 reads `apiKeys`, so a key edit is a tier event: this is the
         // path that turns `no_key` back into a working tier without a relaunch.
         this.fast?.onConfigChanged();
+        // The summarizer resolves from LIVE config too — it may BE the fast tier —
+        // so the snapshot the chip and `/compact status` read has to be refreshed
+        // for the same reason and at the same moments (the RV-3 lesson).
+        this.compaction?.onConfigChanged();
     }
     setCwd(cwd) {
         this.cwd = cwd;
@@ -1082,6 +1158,10 @@ export class AgentController {
     }
     clearMessages() {
         this.agent.clearMessages();
+        // INVALIDATION SITE 3 (context-auto-compaction-hardening §3.2.3). The history
+        // was CLEARED, not appended to, so the prefix length the last measurement
+        // covered indexes an array that no longer exists.
+        this.compaction?.onHistoryReplaced();
         // A new conversation has no loaded skills, so the "already loaded earlier
         // in this conversation" hint would otherwise start lying (P2-9).
         this.skills.getRegistry().clearActive();
@@ -1098,6 +1178,10 @@ export class AgentController {
     }
     replaceMessages(messages) {
         this.agent.replaceMessages(messages);
+        // INVALIDATION SITE 4 (§3.2.3) - `/resume`, and any future host-side rewrite.
+        // `estimateAppendedTokens` bounds-checks as well, so a MISSED site costs
+        // accuracy and never correctness; that belt does not make this call optional.
+        this.compaction?.onHistoryReplaced();
     }
     getMessages() {
         return this.agent.state.messages;
@@ -1191,6 +1275,10 @@ export class AgentController {
         // was never registered) nothing has to be rebuilt, because no block is
         // spliced either way.
         this.fast?.onConfigChanged();
+        // The summarizer resolves from LIVE config too — it may BE the fast tier —
+        // so the snapshot the chip and `/compact status` read has to be refreshed
+        // for the same reason and at the same moments (the RV-3 lesson).
+        this.compaction?.onConfigChanged();
         return fast;
     }
     /** Everything `/fast status`, the settings line and the chip read. */
@@ -1209,6 +1297,117 @@ export class AgentController {
             return () => { };
         return this.fast.subscribe(listener);
     }
+    // -----------------------------------------------------------------------
+    // Context compaction (context-auto-compaction §3.2.1) — THIN FORWARDERS
+    // -----------------------------------------------------------------------
+    /** Whether a `ContextManager` exists at all. Fixed at construction. */
+    isCompactionRegistered() {
+        return this.compaction !== null;
+    }
+    /** Whether it will actually fire. Flipped live by `/compact on|off`. */
+    isCompactionEnabled() {
+        return this.compaction?.isEnabled() === true;
+    }
+    /**
+     * Flip the live switch.
+     *
+     * A NO-OP WHEN NOTHING IS REGISTERED, and `/compact` reports that honestly by
+     * checking `isCompactionRegistered()` first — the `/fast on` and `/team on`
+     * shape. `enabled` decides whether the wiring EXISTS, which happens once at
+     * construction and cannot be undone: a session that started with no manager
+     * would have to be given one mid-flight, and the `Agent` has no setter for it
+     * on purpose (§3.2).
+     */
+    setCompactionEnabled(enabled) {
+        this.compaction?.setEnabled(enabled);
+    }
+    getCompactionConfig() {
+        return this.config.compaction;
+    }
+    /**
+     * Adopt a new compaction config for this session.
+     *
+     * THE `onConfigChanged` CALL IS NOT OPTIONAL, for the reason `setFastConfig`
+     * records: a persist without it reports success and changes nothing visible
+     * until relaunch, because the chip and `/compact status` read a snapshot.
+     */
+    setCompactionConfig(patch) {
+        const compaction = clampCompactionConfig({ ...this.config.compaction, ...patch });
+        this.config = { ...this.config, compaction };
+        this.compaction?.onConfigChanged();
+        return compaction;
+    }
+    /** Everything `/compact status`, the settings row and the chip read. */
+    getCompactionSnapshot() {
+        return this.compaction ? this.compaction.snapshot() : offCompactionSnapshot();
+    }
+    /**
+     * The `ModelRef` the next compaction would summarize with, or `null`.
+     *
+     * IT IS CARRIED, NEVER RE-DERIVED, and that is the whole reason it exists. The
+     * summarizer is the fast tier when `useFastTier` is on AND the tier resolves,
+     * and the session's own model otherwise — a combination no caller can
+     * reconstruct from `CliConfig` without re-implementing `resolveFastTier`, and
+     * one that a plausible guess (`fast.enabled ? fast.provider : provider`) gets
+     * WRONG whenever `fast.enabled` is true and `compaction.useFastTier` is false.
+     * Pricing the spend against the wrong provider looks up a model the static
+     * table has never seen, which prices it at `$0.00` — the C-11 / RV-4 lie, on
+     * the one feature that spends money without being asked (AC-15).
+     */
+    getCompactionSummarizerRef() {
+        return this.compaction?.summarizerRef() ?? null;
+    }
+    /**
+     * This run's archive key, or `null` when compaction is unregistered
+     * (context-auto-compaction-hardening §3.5 / W4).
+     *
+     * `/compact history` and `/compact show` scope themselves to it, so a second
+     * `aragon` in another terminal is invisible here rather than interleaved with
+     * this one's compactions.
+     */
+    getCompactionRunId() {
+        return this.compaction?.archiveRunId() ?? null;
+    }
+    /** Ask for a compaction at the next turn boundary (§4.4 / D-17). */
+    queueCompaction(instructions) {
+        this.compaction?.queueManual(instructions);
+    }
+    /**
+     * The IDLE `/compact` path (§4.4 / D-25).
+     *
+     * IT VALIDATES BEFORE IT SPLICES. `CompactionWiring.compactNow` runs
+     * `validateHistory` itself and refuses on failure, because with no loop running
+     * the engine's own gate is unreachable and D-4 declares that gate
+     * unbypassable. `replaceMessages` validates NOTHING.
+     */
+    async compactNow(instructions) {
+        if (!this.compaction)
+            return { ok: false, reason: 'not_registered' };
+        const controller = new AbortController();
+        const outcome = await this.compaction.compactNow({
+            messages: this.agent.state.messages,
+            systemPrompt: this.agent.state.systemPrompt,
+            model: this.agent.state.model,
+            signal: controller.signal,
+            ...(instructions ? { instructions } : {}),
+        });
+        if (!outcome.ok)
+            return { ok: false, reason: outcome.reason };
+        this.agent.replaceMessages(outcome.messages);
+        return { ok: true };
+    }
+    /**
+     * Subscribe to the CLI-local compaction event stream.
+     *
+     * Returns a no-op unsubscribe when compaction was off at construction, so
+     * every caller can subscribe unconditionally — the contract `subscribeTeam`,
+     * `subscribeTodos` and `subscribeFast` already set.
+     */
+    subscribeCompaction(listener) {
+        if (!this.compaction)
+            return () => { };
+        return this.compaction.subscribe(listener);
+    }
     /** List usable tools (name + description) for the /tools command. */
     listTools() {
         return this.tools;

package/dist/agent/headless.d.ts

@@ -9,6 +9,7 @@ import type { PreflightResult } from './controller.js';
 import type { TeamEvent } from '../team/types.js';
 import type { TodoEvent, TodoSnapshot } from '../todo/types.js';
 import type { FastEvent } from '../fast/types.js';
+import type { CompactionEvent } from '../compaction/types.js';
 import { type FollowThroughMode } from '../todo/follow-through.js';
 /** The minimal controller surface headless mode needs (real or stubbed). */
 export interface HeadlessController {
@@ -43,6 +44,13 @@ export interface HeadlessController {
      * byte-identical to today's.
      */
     subscribeFast?(listener: (event: FastEvent) => void): () => void;
+    /**
+     * The CLI-local compaction stream — OPTIONAL, for the identical reason the
+     * three above are (context-auto-compaction §4.7). A controller with no
+     * `ContextManager` has no compaction events, and `runHeadless` calls it with
+     * `?.`, which keeps a `--no-compaction` headless run byte-identical to today's.
+     */
+    subscribeCompaction?(listener: (event: CompactionEvent) => void): () => void;
     /**
      * The current plan — OPTIONAL, for the identical reason the two subscriptions
      * above are (todo-plan-followthrough §3.6 rule 2). ABSENT MEANS THE

package/dist/agent/headless.js

@@ -167,6 +167,52 @@ export async function runHeadless(controller, prompt, options = {}) {
         total.inputTokens += event.usage.inputTokens;
         total.outputTokens += event.usage.outputTokens;
     });
+    // Context compaction (context-auto-compaction §4.7).
+    //
+    // TWO STDERR LINES, AND UNLIKE THE FAST TIER THEY ARE WRITTEN (D-12's
+    // reasoning does not carry over). A review is an unrequested second opinion
+    // that changes nothing; a compaction PERMANENTLY DROPS MESSAGES from the
+    // conversation, and a `-p` run whose middle third vanished with no line
+    // anywhere saying so is not a compact run, it is an unexplained one — the same
+    // argument the retry lines above make for a three-minute pause.
+    //
+    // stderr, never stdout: stdout is the machine-readable answer and has to stay
+    // parseable by `aragon -p | jq`. Not `--quiet`-gated, for the reason the retry
+    // line is not.
+    //
+    // The summary text is NOT written (D-18): it can be tens of thousands of
+    // characters, and no consumer of `-p` asked for it.
+    const unsubscribeCompaction = controller.subscribeCompaction?.((event) => {
+        if (event.type === 'usage') {
+            total.inputTokens += event.usage.inputTokens;
+            total.outputTokens += event.usage.outputTokens;
+            return;
+        }
+        if (event.type !== 'compaction_end')
+            return;
+        const r = event.record;
+        if (!r.applied) {
+            err.write(`\n[compaction] skipped: ${r.reason ?? 'unknown'}\n`);
+            return;
+        }
+        const secs = (r.durationMs / 1000).toFixed(1);
+        const how = r.mode === 'truncated'
+            ? ' WITHOUT a summary (summarize failed)'
+            : r.mode === 'relieved'
+                ? ' by clipping the retained turns (nothing could be dropped)'
+                : '';
+        err.write(`\n[compaction] ${formatTokens(r.tokensBefore)} -> ${formatTokens(r.tokensAfter)} tokens, ` +
+            `${r.messagesBefore} -> ${r.messagesAfter} messages${how} (${secs}s)\n`);
+        // ONE MORE LINE, AND ONLY WHEN RELIEF FIRED (§4.5). A clip inside the turns
+        // the run is about to continue from is a real data loss, and a `-p` run whose
+        // recent tool output was silently shortened is an unexplained run - the same
+        // argument the compaction lines above make for a vanished middle third.
+        if (r.tailRelief) {
+            err.write(`[compaction] clipped ${r.tailRelief.messages} tool ` +
+                `${r.tailRelief.messages === 1 ? 'result' : 'results'} in the retained turns ` +
+                `(${formatTokens(r.tailRelief.charsRemoved)} chars)\n`);
+        }
+    });
     // --- The bounded continuation loop (todo-plan-followthrough §3.6). --------
     //
     // THE THREE `unsubscribe` CALLS STAY OUTSIDE IT (rule 4). The loop wraps the
@@ -227,6 +273,7 @@ export async function runHeadless(controller, prompt, options = {}) {
         unsubscribeTeam?.();
         unsubscribeTodos?.();
         unsubscribeFast?.();
+        unsubscribeCompaction?.();
     }
     // Ensure a trailing newline so piped output is well-formed.
     if (wroteText)

package/dist/agent/reducer.d.ts

@@ -14,6 +14,7 @@ import type { AgentEvent, ModelCost, ToolResult, TokenUsage } from '@aragon-agen
 import type { AgentMode } from './agent-mode.js';
 import type { DispatchOutcome, SubagentRun, SubagentSpec, TeamSnapshot } from '../team/types.js';
 import type { FastReview, FastSnapshot } from '../fast/types.js';
+import type { CompactionMode, CompactionRecord, CompactionSnapshot, CompactionUiTrigger } from '../compaction/types.js';
 import type { TodoItem, TodoSnapshot } from '../todo/types.js';
 import type { RetryPhase } from './retry-view.js';
 import type { FilePatch } from '../tools/patch.js';
@@ -222,6 +223,57 @@ export type Entry = {
     turn: number;
     durationMs?: number;
     live: boolean;
+}
+/**
+ * One context compaction (context-auto-compaction §5.5). ONE CARD PER
+ * COMPACTION, rewritten once when the call returns — like the fast card, and
+ * unlike the todo card's per-turn checklist.
+ *
+ * JSON-SERIALIZABLE by construction, so `/save` and `/resume` need no format
+ * change.
+ *
+ * `live: true` is normalized away ON LOAD, in `session/persist.ts`, next to
+ * `team.active`, `todo.live`, the retry card's phase and `fast.live`, and for
+ * the identical reason (C-8): `Transcript`'s settled boundary is MONOTONIC, so
+ * an entry that never settles never reaches `<Static>` and is re-rendered on
+ * every frame for the rest of the session.
+ *
+ * EVERY STRING ON THIS CARD DESCRIBES THE HISTORY, NEVER THE SCREEN (P2-9).
+ * `/clear` empties the transcript view but not `messages`, so a compaction can
+ * legitimately fire against a visually empty transcript and report
+ * "112 -> 9 messages" with nine visible rows.
+ */
+ | {
+    id: string;
+    kind: 'compaction';
+    /** 1-based within the session, so the card can name itself. */
+    index: number;
+    trigger: CompactionUiTrigger;
+    mode: CompactionMode;
+    applied: boolean;
+    reason?: string;
+    messagesBefore: number;
+    messagesAfter: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    summary?: string;
+    model: string;
+    durationMs?: number;
+    /**
+     * When the live card opened, so the elapsed counter has an origin
+     * (context-auto-compaction-hardening §3.6 / W5).
+     *
+     * JSON-SERIALIZABLE like every other field here, and harmless on reload:
+     * `session/persist.ts` normalizes `live` to false, and a settled card
+     * renders `durationMs` rather than an elapsed figure.
+     */
+    startedAt?: number;
+    /** Set when tail relief clipped the retained turns (W2). */
+    tailRelief?: {
+        messages: number;
+        charsRemoved: number;
+    };
+    live: boolean;
 };
 export interface UsageTotal {
     inputTokens: number;
@@ -296,6 +348,25 @@ export interface ViewState {
      * what leaves an ordinary session's status bar byte-identical (AC-4).
      */
     fast: FastSnapshot | null;
+    /**
+     * The live compaction projection, or `null` when the feature is off for this
+     * session (context-auto-compaction §5.5).
+     *
+     * NEVER PERSISTED — `entries` is the history and the settled cards are the
+     * record. It drives the status chip, the gauge's marks and `/compact status`'s
+     * totals. `null` is what leaves an ordinary session's status bar unchanged.
+     */
+    compaction: CompactionSnapshot | null;
+    /**
+     * Whether `contextTokens` is currently a DERIVED figure rather than a measured
+     * one (§6.2 / P1-11).
+     *
+     * Set by `compactionEnd`, cleared by the next `turnEnd`. The status bar widens
+     * its leading `~` to cover it: today `~` means "the window is a guess", and
+     * this makes it also mean "the occupancy is a guess". Honesty about a guess is
+     * cheaper than a support thread about a wrong percentage.
+     */
+    contextTokensEstimated: boolean;
     seq: number;
     /** The `kind: 'team'` entry the live dispatch is writing into. */
     teamEntryId?: string;
@@ -305,6 +376,8 @@ export interface ViewState {
     retryEntryId?: string;
     /** The `kind: 'fast'` entry the in-flight review is writing into. */
     fastEntryId?: string;
+    /** The `kind: 'compaction'` entry the in-flight compaction is writing into. */
+    compactionEntryId?: string;
     streamingId?: string;
     turnProduced: boolean;
     errorNoticed: boolean;
@@ -497,6 +570,42 @@ export type ViewAction = {
 } | {
     type: 'fastTier';
     snapshot: FastSnapshot;
+} | {
+    type: 'compactionStart';
+    index: number;
+    trigger: CompactionUiTrigger;
+    model: string;
+} | {
+    type: 'compactionEnd';
+    record: CompactionRecord;
+}
+/**
+ * Compaction spend.
+ *
+ * `costDelta` IS PRECOMPUTED BY THE CALLER, exactly as `teamUsage`'s and
+ * `fastUsage`'s are: the reducer stays pure and cost-table-free. It matters
+ * MORE here than for either of those, because the summarizer may be a
+ * different model from the lead AND from the fast tier, so a reducer that
+ * computed its own would have to know about three price tables.
+ */
+ | {
+    type: 'compactionUsage';
+    usage: TokenUsage;
+    costDelta: number;
+} | {
+    type: 'compactionSnapshot';
+    snapshot: CompactionSnapshot;
+}
+/**
+ * Overwrite the gauge with a DERIVED occupancy (§6.2).
+ *
+ * Separate from `compactionEnd` because the value is not always available at
+ * the same instant, and because the flag it sets — `contextTokensEstimated` —
+ * has to be clearable by the next `turnEnd` independently.
+ */
+ | {
+    type: 'contextTokensEstimated';
+    tokens: number;
 };
 export declare const STORED_PREVIEW_CHARS = 8000;
 export declare const STORED_PREVIEW_LINES = 200;
@@ -532,6 +641,17 @@ export interface PatchSource {
  * it — every existing test, and headless mode — produces byte-identical actions.
  */
 export declare function reduceEvent(event: AgentEvent, cost?: ModelCost, patches?: PatchSource): ViewAction[];
+/**
+ * The opening words of the `context_overflow` banner.
+ *
+ * A SHARED CONSTANT RATHER THAN TWO LITERALS, because `compactionStart` matches
+ * on it to rewrite the notice a successful reactive recovery would otherwise
+ * leave behind (P1-4). Two spellings that must agree, with nothing checking that
+ * they do, is how that rewrite silently stops matching — at which point the red
+ * "start over" banner comes back and only on the recovery path, which is the one
+ * place nobody re-tests.
+ */
+export declare const CONTEXT_OVERFLOW_NOTICE_PREFIX = "Context length exceeded";
 /** Turn a provider error into a friendly banner, mapping LLMError.errorType. */
 export declare function formatStreamError(error: Error): string;
 export declare function viewReducer(state: ViewState, action: ViewAction): ViewState;