@aragon-agent/cli 0.6.2 → 0.6.4

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';
@@ -20,8 +20,14 @@ import { TeamHumanQueue } from '../team/human-queue.js';
 import { createTaskTool } from '../team/task-tool.js';
 import { buildTeamBlock } from '../team/prompt.js';
 import { buildFastBlock } from '../fast/prompt.js';
+import { ProcSupervisor } from '../proc/supervisor.js';
+import { buildBackgroundServicesBlock } from '../proc/prompt.js';
+import { PROC_LIMITS } from '../proc/limits.js';
+import { makeBashKill, makeBashOutput } from '../tools/proc-tools.js';
+import { addSignalHook } from '../logging/install.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';
@@ -32,6 +38,15 @@ import { createNodeSkillHost } from '../skills/node-host.js';
 import { SkillService } from '../skills/service.js';
 import { createSkillTools } from '../skills/tools.js';
 import { buildSystemPrompt } from './system-prompt.js';
+/**
+ * Extra budget, on top of `PROC_LIMITS.killGraceMs`, that `prompt()` allows a
+ * force-stopped engine to unwind in before it starts a new run anyway (I-8).
+ *
+ * `bash`'s own kill grace is what a wedged foreground command costs; this covers
+ * the loop's own unwinding on top of it. Waiting FOREVER is not an option - a
+ * tool that never settles is exactly why rung two exists.
+ */
+const ENGINE_UNWIND_GRACE_MS = 3000;
 /** Approval gate used whenever there is provably no human to ask (headless). */
 export const DENY_ALL_APPROVAL = {
     canPrompt: () => false,
@@ -153,6 +168,66 @@ 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;
+    // -----------------------------------------------------------------------
+    // Background services (background-service-supervision §3.3 / §3.6)
+    //
+    // CONSTRUCTED UNCONDITIONALLY, and that is the one thing about this field that
+    // is easy to get wrong (P1-6 / D-9). `cfg.bash.background` gates the SERVICE
+    // half - the `background` tool param, `bash_output`/`bash_kill`, the prompt
+    // block, the status chip - and NEVER the foreground half, because G2 ("bash
+    // always settles") and G3 ("Esc, Esc always works, and the session stays
+    // usable") are promised unconditionally. Gating the whole supervisor on the
+    // flag would make rung two of the Esc ladder a silent no-op for every user who
+    // turned background services off.
+    //
+    // With the flag off it holds foreground pids, nothing else, and allocates no
+    // timers.
+    // -----------------------------------------------------------------------
+    procs;
+    /**
+     * The host's notice channel, kept so `prompt()`'s totality has somewhere to
+     * report to (I-8). Every other consumer reads `deps.notify` through a closure
+     * built in the constructor; this one is called from a method, which is why it
+     * needs a field.
+     */
+    notifyHostFn;
+    /** Whether the SERVICE half is on: tools, prompt block, `background` param. */
+    bashBackgroundRegistered;
+    /** Release the exit reaper. Called by `dispose()`. */
+    releaseSignalHook;
+    /**
+     * Bumped by `forceStop()`; captured by `App` when it subscribes to a run.
+     *
+     * THE VIEW AND THE ENGINE DELIBERATELY DISAGREE AFTER A FORCE-STOP (D-10 /
+     * I-7). Rung two dispatches `runEnd` locally so the composer is usable
+     * immediately, but the engine keeps unwinding and keeps EMITTING -
+     * `turn_start`, `tool_call_start`, `turn_end`, `agent_end` - and
+     * `runStart`/`turnStart` would set `status: 'running'` again, bouncing the
+     * view straight back out of the `idle` the user was just given and appending
+     * entries to a transcript they believe is finished. `App` drops every event
+     * whose generation is stale, which is the same shape as `abortRequested`
+     * above and exists for the same reason: the loop legitimately emits after an
+     * abort lands.
+     */
+    runGen = 0;
     /**
      * Set SYNCHRONOUSLY by `abort()` before `agent.abort()` (§3.5.4a guard 1).
      * Cleared at the next `agent_start`.
@@ -217,6 +292,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
@@ -266,6 +346,19 @@ export class AgentController {
         // reason the field's own comment gives: the binding below is spread
         // conditionally on it (§3.1.3 / P1-6).
         this.toolOutputs = config.liveToolOutput ? createToolOutputStore() : null;
+        // ALSO ABOVE `createBuiltinTools`, and UNCONDITIONAL - see the field's own
+        // comment. `readyTimeoutMs` is read through a closure rather than captured,
+        // so a live config change reaches the next service rather than the next
+        // launch of the CLI.
+        this.procs = new ProcSupervisor({ readyTimeoutMs: () => this.config.bash.readyTimeoutMs });
+        this.notifyHostFn = deps.notify;
+        this.bashBackgroundRegistered = config.bash.background;
+        // THE EXIT REAPER (G5 / P1-2 / R-10). An APPEND-ONLY hook rather than a
+        // second `setSignalTerminator`: that is a single slot `cli.tsx` already owns
+        // for the alternate-screen restore, and replacing it is the documented bug
+        // that leaves the user staring at a blank alternate screen. `reapSync` is
+        // the only entry point it calls, and it is synchronous end to end (I-9).
+        this.releaseSignalHook = addSignalHook(() => this.procs.reapSync());
         this.tools = createBuiltinTools({
             getCwd: () => this.cwd,
             // OWNED HERE, NOT IN `cli.tsx` (D-18): `createBuiltinTools` is called from
@@ -282,6 +375,28 @@ export class AgentController {
             ...(this.toolOutputs
                 ? { recordOutput: (id, chunk) => this.emitToolOutput('lead', id, chunk) }
                 : {}),
+            // THE SERVICE HALF, AND ONLY THE SERVICE HALF (P1-6 / I-2). With
+            // `bash.background: false` the options bag has no `procs` key at all, so
+            // `createBuiltinTools` adds no property to `deps`, `bash` gets its default
+            // `{}` second argument, and the tool is the pre-feature one: no
+            // `background` in its schema, the pre-feature description string, no
+            // supervisor call. The FOREGROUND half of `this.procs` is still live, and
+            // `forceStop()` still reaches it.
+            ...(this.bashBackgroundRegistered
+                ? {
+                    procs: this.procs,
+                    // Read LIVE for the reason every other closure in this bag is:
+                    // `aragon config set bash.autoBackground false` must take effect in
+                    // the running session.
+                    autoBackground: () => this.config.bash.autoBackground,
+                    startupSettleMs: () => this.config.bash.startupSettleMs,
+                    // D-15 / P1-8. `planInteractive` is the SAME signal `planTools`
+                    // already uses to decide that no overlay can be rendered, which is
+                    // exactly the question being asked here: can a card be drawn, and is
+                    // there a user who could keep a service alive?
+                    interactive: this.planInteractive,
+                }
+                : {}),
             confirmTools: config.confirmTools,
             // Routed through the same watchdog pause as the plan tools. This is a
             // pre-existing bug being fixed in passing: a `--confirm` user who took
@@ -321,6 +436,12 @@ export class AgentController {
                     }),
                 ]
                 : [],
+            // THROUGH THE FACTORY for the reason `teamTools` records below (P0-2), and
+            // empty when background services were off at construction - which leaves
+            // the array byte-identical to the pre-feature build (I-2).
+            procTools: this.bashBackgroundRegistered
+                ? [makeBashOutput({ supervisor: this.procs }), makeBashKill({ supervisor: this.procs })]
+                : [],
             // THROUGH THE FACTORY, NEVER APPENDED AFTERWARDS (D-15 / P0-1).
             // `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals what
             // `createBuiltinTools` produces, so appending `task` here would turn that
@@ -379,6 +500,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 +529,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 +555,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
@@ -550,6 +709,12 @@ export class AgentController {
                     review: this.config.fast.review,
                 })
                 : '',
+            // ONE FLAG, unlike team/todo's two: there is no live on/off switch for
+            // background services - `bash.background` is read once at construction,
+            // and the tools it registers cannot be unregistered (the `team.enabled` /
+            // `todo.enabled` rule). So the block is present exactly when the tools are,
+            // and can never advertise a capability the model does not have.
+            backgroundBlock: this.bashBackgroundRegistered ? buildBackgroundServicesBlock() : '',
             // Read from the FIELD on every rebuild, for the reason the field's own
             // comment gives. Empty everywhere but `aragon exec`, and `buildSystemPrompt`
             // splices it conditionally, so every existing prompt is byte-identical.
@@ -638,7 +803,64 @@ export class AgentController {
      * underlying promise so headless mode can await completion. `agent.prompt()`
      * never rejects, so callers must not treat resolution as success.
      */
-    prompt(text) {
+    async prompt(text) {
+        // I-8 - THIS METHOD NEVER REJECTS, AND THAT HAS TO BE A PROPERTY OF THE
+        // METHOD RATHER THAN A COMMENT ABOVE IT (P0-1).
+        //
+        // `App` calls this as `void controller.prompt(...)`, and
+        // `logging/install.ts` routes an `unhandledRejection` into `handleFatal`,
+        // which EXITS THE PROCESS. `Agent.prompt()` throws SYNCHRONOUSLY while
+        // `Agent.running` is true - so before the force-stop ladder existed this was
+        // merely nearly-true (the view was only ever idle when the engine was), and
+        // rung two makes the view idle while the engine is still unwinding. Without
+        // the wait and the guard below, "Esc, Esc, then type" would kill the CLI on
+        // the very screen this feature exists to rescue.
+        //
+        // TWO PARTS, BOTH REQUIRED. First WAIT the engine out, bounded, so the
+        // common case (the engine unwinds in a few hundred ms) starts a real run
+        // rather than reporting a failure. Then swallow anything that still escapes
+        // and surface it through the existing notify channel, because a message that
+        // cannot be started must produce a visible sentence - never a crash, and
+        // never silence.
+        if (this.agent.state.isRunning) {
+            this.abort();
+            await this.waitForEngineIdle();
+        }
+        try {
+            await this.startPrompt(text);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            getLogger().warn('agent', 'prompt_failed', { reason });
+            this.notifyHostFn?.('error', `Could not start the run: ${reason}`);
+        }
+    }
+    /**
+     * Wait for the engine to unwind, bounded.
+     *
+     * BOUNDED BECAUSE THE UNBOUNDED CASE IS THE ONE THIS FEATURE IS ABOUT: a tool
+     * that never settles is exactly why rung two exists, and `Agent.waitForIdle()`
+     * alone would hang here for as long as it hangs there. The budget is the two
+     * graces a wedged `bash` can legitimately spend, plus the executor's own.
+     */
+    waitForEngineIdle() {
+        const budget = PROC_LIMITS.killGraceMs + ENGINE_UNWIND_GRACE_MS;
+        return new Promise((resolve) => {
+            let done = false;
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                resolve();
+            };
+            const timer = setTimeout(finish, budget);
+            timer.unref?.();
+            void this.agent.waitForIdle().then(finish, finish);
+        });
+    }
+    /** The pre-round body of `prompt`, unchanged apart from being private. */
+    startPrompt(text) {
         // A new user message is a new intent, so the previous turn's tool ceiling
         // expires here and anything a slash command queued is promoted (D-G1 / D-G2).
         // This and `steer()` below are the ONLY two places a user message enters the
@@ -670,6 +892,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
@@ -679,6 +906,115 @@ export class AgentController {
         // `App.tsx` records for `cancelPendingHuman()` on `agent_end`.
         this.teamRuntime?.abortAll();
     }
+    /**
+     * Rung two of the Esc ladder: stop the AGENT, whatever it is blocked on
+     * (§3.6 / G3).
+     *
+     * FOUR STEPS, AND THE FOURTH IS AN ABSENCE.
+     *
+     *   1. `abort()` - everything it does today, unchanged.
+     *   2. `killForeground('force')` - hard-kill every tracked foreground `bash`
+     *      child. THIS is what actually unblocks a wedged `await tool.execute`;
+     *      an abort signal a tool ignores is advisory, and rung two exists for
+     *      precisely the tools that ignore it.
+     *   3. `runGen += 1` - so `App` can drop the events the engine will keep
+     *      emitting while it unwinds (I-7). Without it the view bounces straight
+     *      back out of the `idle` the user was just given.
+     *   4. IT DOES NOT TOUCH BACKGROUND SERVICES. `Esc` interrupts the AGENT;
+     *      `Ctrl+C` stops the SERVICES. That asymmetry is the user's own two
+     *      sentences and it is exactly the kind of thing a later reader will
+     *      "fix" by making this kill everything - which would mean a user who
+     *      pressed Esc twice to stop a runaway turn also lost the dev server they
+     *      had been working against for an hour. It is invariant I-4.
+     *
+     * UNCONDITIONAL ON `bash.background` (P1-6 / D-9). The supervisor is always
+     * constructed; with services off its foreground registry is all there is, and
+     * that is the half this method uses.
+     */
+    forceStop() {
+        this.abort();
+        const killed = this.procs.killForeground('force');
+        this.runGen += 1;
+        getLogger().info('agent', 'force_stop', { generation: this.runGen, killed });
+    }
+    /**
+     * The current run generation (I-7).
+     *
+     * `App` captures it when it subscribes to a run and drops every engine event
+     * whose generation is stale. Same shape as the `abortRequested` guard the fast
+     * reviewer already uses, and for the same reason: the loop legitimately emits
+     * after an abort lands.
+     */
+    get runGeneration() {
+        return this.runGen;
+    }
+    // -----------------------------------------------------------------------
+    // Background services (background-service-supervision §3.5 / §3.6)
+    // -----------------------------------------------------------------------
+    /** Whether `bash_output` / `bash_kill` are in `this.tools`. Fixed at construction. */
+    isBackgroundRegistered() {
+        return this.bashBackgroundRegistered;
+    }
+    /**
+     * Subscribe to the CLI-local `ProcEvent` stream.
+     *
+     * Returns a live unsubscribe even when services are off, because the
+     * supervisor exists either way - the contract `subscribeTeam` /
+     * `subscribeTodos` / `subscribeFast` / `subscribeToolOutput` already set. With
+     * services off nothing is ever emitted, so an unconditional subscription in
+     * `App` costs one `Set` entry.
+     */
+    subscribeProc(listener) {
+        return this.procs.subscribe(listener);
+    }
+    getServiceSnapshot(id) {
+        return this.procs.get(id);
+    }
+    listServices() {
+        return this.procs.list();
+    }
+    /** `starting | ready | running`. Drives the status chip and the Ctrl+C rung. */
+    liveServiceCount() {
+        return this.procs.liveCount();
+    }
+    readServiceLog(id, since) {
+        return this.procs.read(id, since);
+    }
+    /**
+     * Stop one service, or every service when `id` is `'all'`.
+     *
+     * The GRACEFUL ladder (`SIGTERM` -> `SIGKILL` after `stopGraceMs`), because
+     * this path has a live event loop to run it on. `reapServicesSync` is the
+     * other one, and it is the only one an exit path may use.
+     */
+    stopService(id) {
+        return this.procs.stop(id);
+    }
+    /**
+     * Rung one of `Ctrl+C`: stop every live service (§3.6 / G4).
+     *
+     * `force: true` means `reapSync()` SEMANTICS - immediate `SIGKILL`, no
+     * `stopGraceMs` - and is what `doExit` uses, because `doExit` awaits nothing
+     * and must not start (§3.6 step 3). The graceful ladder belongs to `Ctrl+C`,
+     * `bash_kill` and `/bg stop`.
+     */
+    stopAllServices(opts = {}) {
+        if (opts.force) {
+            this.procs.reapSync();
+            return Promise.resolve(this.procs.list());
+        }
+        return this.procs.stop('all');
+    }
+    /**
+     * The synchronous reaper (I-9).
+     *
+     * Exposed so `doExit` can call it without awaiting anything. It is also what
+     * the signal hook registered in the constructor calls, and it is idempotent -
+     * which it has to be, since a normal quit reaches it twice.
+     */
+    reapServicesSync() {
+        this.procs.reapSync();
+    }
     steer(text) {
         // Mid-run interjection: promote the queue, keep what is already in force
         // (D-G3). Clearing here would make "ask a follow-up" the way around the
@@ -870,6 +1206,12 @@ export class AgentController {
     dispose() {
         this.teamRuntime?.dispose();
         this.fast?.dispose();
+        this.compaction?.dispose();
+        // REAP BEFORE RELEASING THE HOOK, in that order: disposal is a teardown, and
+        // a service that outlives it has nothing left that could ever stop it.
+        this.procs.reapSync();
+        this.releaseSignalHook();
+        this.procs.dispose();
     }
     // -----------------------------------------------------------------------
     // Todo planning (todo-plan-execution §3.6a)
@@ -991,6 +1333,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 +1356,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 +1432,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 +1452,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 +1549,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 +1571,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