@aragon-agent/cli 0.6.1 → 0.6.3

package/dist/compaction/command.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The `/compact` slash command and its status report
+ * (context-auto-compaction §4.4).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope, and this
+ * text lands in a transcript `notice` — produced outside `src/ui/**`, where no
+ * terminal capabilities are available, so it must be safe on a legacy `cmd.exe`.
+ *
+ * IT LIVES HERE RATHER THAN IN `builtins.ts`, AND THAT IS A BUDGET DECISION
+ * RATHER THAN TASTE (C-16 / P1-12). `CLAUDE.md` caps a source file at 1000 lines,
+ * `builtins.ts` is already past it, and `/compact` has eight forms plus the
+ * longest status report in the package. `builtins.ts` gets the registration and nothing
+ * else — the same split `controller.ts` argues for `FastWiring`, one layer out.
+ */
+import type { CommandContext } from '../commands/registry.js';
+/**
+ * `/compact status` — THE GUARANTEED REPORTING SURFACE (§6.5 / AC-17).
+ *
+ * The chip drops on a narrow terminal, the activity row is suppressed under an
+ * overlay, and the card scrolls away. This command answers every question about
+ * the feature's state at any width, in any mode, including after the fact.
+ *
+ * IT READS THE SAME NUMBERS THE STATUS BAR DOES, through one `occupiedTokens`
+ * (§3.4.1 / R-11): a user watching 78 % on the bar who is told 91 % here would
+ * conclude one of the two is lying, and they would be right.
+ *
+ * `unknown (no price table for <model>)` RATHER THAN A CURRENCY AMOUNT when the
+ * static table has never seen the summarizer (the C-11 / RV-4 lesson from the
+ * fast tier). `$0.00` on a feature that is spending money is the same class of
+ * lie as pricing a Haiku child at Sonnet rates — and it matters MORE here,
+ * because the DEFAULT summarizer is the session's own frontier model.
+ */
+export declare function formatCompactionStatus(ctx: CommandContext): string;
+/**
+ * The `/compact` handler.
+ *
+ * `/compact <free text>` is the Claude Code affordance and is therefore the
+ * FALL-THROUGH rather than a subcommand: anything that is not one of the seven
+ * verbs is instructions for the summarizer.
+ */
+export declare function runCompactCommand(ctx: CommandContext): Promise<void>;

package/dist/compaction/command.js

@@ -0,0 +1,342 @@
+/**
+ * The `/compact` slash command and its status report
+ * (context-auto-compaction §4.4).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope, and this
+ * text lands in a transcript `notice` — produced outside `src/ui/**`, where no
+ * terminal capabilities are available, so it must be safe on a legacy `cmd.exe`.
+ *
+ * IT LIVES HERE RATHER THAN IN `builtins.ts`, AND THAT IS A BUDGET DECISION
+ * RATHER THAN TASTE (C-16 / P1-12). `CLAUDE.md` caps a source file at 1000 lines,
+ * `builtins.ts` is already past it, and `/compact` has eight forms plus the
+ * longest status report in the package. `builtins.ts` gets the registration and nothing
+ * else — the same split `controller.ts` argues for `FastWiring`, one layer out.
+ */
+import { parseThresholdInput } from '../config/schema.js';
+import { formatCost, formatTokens } from '../agent/usage.js';
+import { computeCost } from '../agent/usage.js';
+import { COMPACTION_LIMITS } from './limits.js';
+import { findArchive, listArchives } from './archive.js';
+/**
+ * `/compact status` — THE GUARANTEED REPORTING SURFACE (§6.5 / AC-17).
+ *
+ * The chip drops on a narrow terminal, the activity row is suppressed under an
+ * overlay, and the card scrolls away. This command answers every question about
+ * the feature's state at any width, in any mode, including after the fact.
+ *
+ * IT READS THE SAME NUMBERS THE STATUS BAR DOES, through one `occupiedTokens`
+ * (§3.4.1 / R-11): a user watching 78 % on the bar who is told 91 % here would
+ * conclude one of the two is lying, and they would be right.
+ *
+ * `unknown (no price table for <model>)` RATHER THAN A CURRENCY AMOUNT when the
+ * static table has never seen the summarizer (the C-11 / RV-4 lesson from the
+ * fast tier). `$0.00` on a feature that is spending money is the same class of
+ * lie as pricing a Haiku child at Sonnet rates — and it matters MORE here,
+ * because the DEFAULT summarizer is the session's own frontier model.
+ */
+export function formatCompactionStatus(ctx) {
+    const controller = ctx.controller;
+    const snapshot = controller.getCompactionSnapshot();
+    const config = controller.getCompactionConfig();
+    const lines = [];
+    if (!controller.isCompactionRegistered()) {
+        lines.push('Auto-compaction: not registered for this session (started with --no-compaction).');
+        lines.push(`  Saved setting: compaction.enabled = ${config.enabled}`);
+        lines.push('  A full context window will end the run, as it did before this feature existed.');
+        return lines.join('\n');
+    }
+    const state = snapshot.selfDisabled
+        ? `self-disabled (${snapshot.selfDisabledReason ?? 'no progress'})`
+        : controller.isCompactionEnabled()
+            ? snapshot.live
+                ? 'on'
+                : 'on, but no summarizer model resolves'
+            : 'off for this session';
+    lines.push(`Auto-compaction: ${state}`);
+    const p = snapshot.pressure;
+    const pct = Math.round(p.ratio * 100);
+    const approx = p.source === 'estimate' || !p.windowKnown ? '~' : '';
+    lines.push(`  Occupancy: ${approx}${pct}% (${formatTokens(p.occupied)} of ` +
+        `${formatTokens(p.contextWindow)}${p.windowKnown ? '' : ', window unknown'}) ` +
+        `[${p.source === 'usage' ? 'measured' : 'estimated'}]`);
+    lines.push(`  Triggers at: ${Math.round(config.threshold * 100)}% ` +
+        `(amber at ${Math.round(config.warnThreshold * 100)}%), ` +
+        `or when headroom drops below one full response`);
+    lines.push(`  Keeps: the original task + ${config.keepRecentTurns} recent turns, verbatim`);
+    lines.push(`  Summarizer: ${snapshot.model || '(none)'}` +
+        (config.useFastTier ? ' (fast tier preferred)' : ' (fast tier not used)'));
+    lines.push(`  On summarize failure: ${config.onFailure}`);
+    lines.push(`  This session: ${snapshot.compactions} ` +
+        `${snapshot.compactions === 1 ? 'compaction' : 'compactions'}` +
+        (snapshot.generation > 0 ? ` (generation ${snapshot.generation})` : '') +
+        `, ${formatTokens(snapshot.tokensReclaimed)} tokens reclaimed`);
+    const cost = snapshot.pricingUnknown
+        ? `unknown (no price table for ${snapshot.model || 'the summarizer'})`
+        : formatCost(compactionCost(ctx));
+    lines.push(`  Compaction spend: ${formatTokens(snapshot.usage.inputTokens)} in / ` +
+        `${formatTokens(snapshot.usage.outputTokens)} out, ${cost}`);
+    // TWO MORE LINES, AND ONLY WHEN THEY APPLY (hardening §4.4). A clip inside the
+    // retained turns is a real data loss and `/compact status` is the GUARANTEED
+    // reporting surface, so it has to be sayable here as well as on a card that
+    // may have scrolled away.
+    const relief = totalTailRelief(ctx);
+    if (relief) {
+        lines.push(`  Tail relief    ${relief.messages} tool ` +
+            `${relief.messages === 1 ? 'result' : 'results'} clipped ` +
+            `(${formatTokens(relief.charsRemoved)} chars) in ` +
+            `${relief.compactions} ${relief.compactions === 1 ? 'compaction' : 'compactions'}`);
+    }
+    const archives = archiveSummary(ctx);
+    if (archives)
+        lines.push(`  Archive        ${archives}`);
+    if (snapshot.inFlight)
+        lines.push('  A compaction is running right now.');
+    if (controller.isCompactionRegistered() && !controller.isCompactionEnabled()) {
+        lines.push('  Turn it back on with /compact on.');
+    }
+    return lines.join('\n');
+}
+/**
+ * The summarizer's own price, never the lead's.
+ *
+ * THE REF IS ASKED FOR, NOT RECONSTRUCTED. Deriving the provider from config
+ * (`fast.enabled ? fast.provider : provider`) is wrong exactly when
+ * `fast.enabled` is true and `compaction.useFastTier` is false: the summarizer is
+ * then the MAIN model looked up under the FAST provider, which the static table
+ * has never seen, so `getModelInfoFor` returns a runtime model costed at zero and
+ * this line reports `$0.00` for a priced model. `pricingUnknown` cannot catch it
+ * either — the compactor sets that flag from the ref it actually used, which IS
+ * priced. `getCompactionSummarizerRef()` carries the answer instead.
+ */
+function compactionCost(ctx) {
+    const snapshot = ctx.controller.getCompactionSnapshot();
+    const ref = ctx.controller.getCompactionSummarizerRef();
+    if (!ref)
+        return 0;
+    return computeCost(snapshot.usage, ctx.controller.getModelInfoFor(ref).cost);
+}
+/**
+ * The session's clipped-tool-result total, or `null` when relief never fired.
+ *
+ * READ FROM THE TRANSCRIPT ENTRIES rather than from a counter on the snapshot,
+ * because relief is rare enough that a session-total field would be a number
+ * carried on every snapshot for a line almost nobody sees. The entries are
+ * already in view state and already carry it.
+ */
+function totalTailRelief(ctx) {
+    let messages = 0;
+    let charsRemoved = 0;
+    let compactions = 0;
+    for (const entry of ctx.state.entries) {
+        if (entry.kind !== 'compaction' || !entry.tailRelief)
+            continue;
+        messages += entry.tailRelief.messages;
+        charsRemoved += entry.tailRelief.charsRemoved;
+        compactions += 1;
+    }
+    return compactions === 0 ? null : { messages, charsRemoved, compactions };
+}
+/** `N files in <dir>` for this run, or `null` when there are none. */
+function archiveSummary(ctx) {
+    const runId = ctx.controller.getCompactionRunId();
+    if (!runId)
+        return null;
+    if (!ctx.controller.getCompactionConfig().archive)
+        return null;
+    const listing = listArchives(runId);
+    if (listing.entries.length === 0)
+        return null;
+    return `${listing.entries.length} ${listing.entries.length === 1 ? 'file' : 'files'} in ${listing.dir}`;
+}
+/** One `/compact history` row. */
+function archiveRow(entry) {
+    const at = new Date(entry.createdAt);
+    const pad = (n) => String(n).padStart(2, '0');
+    const clock = `${pad(at.getHours())}:${pad(at.getMinutes())}:${pad(at.getSeconds())}`;
+    return (`  #${entry.index}  ${clock}   ${entry.trigger.padEnd(8)}  ` +
+        `${formatTokens(entry.tokensBefore)} -> ${formatTokens(entry.tokensAfter)}   ` +
+        `${entry.droppedCount} messages   ${entry.fileName}`);
+}
+/**
+ * `/compact history` - THIS RUN's archives, newest first.
+ *
+ * THE LISTING IS `runId`-SCOPED (RV-6). `<home>/compaction` is shared by every
+ * `aragon` on the machine, so an unscoped listing would present a neighbouring
+ * session's compactions as this one's and `#2` would be ambiguous the moment two
+ * runs both reached their second compaction. Other runs' files are COUNTED in one
+ * trailing line rather than listed, because the alternative is a user concluding
+ * their own compactions went missing.
+ */
+function formatCompactionHistory(ctx) {
+    const runId = ctx.controller.getCompactionRunId();
+    if (!runId) {
+        return 'Compaction is not registered for this session (started with --no-compaction).';
+    }
+    const listing = listArchives(runId);
+    if (listing.entries.length === 0) {
+        return ctx.controller.getCompactionConfig().archive
+            ? 'No compactions have been archived yet.'
+            : 'No compaction archives for this session. (compaction.archive is off)';
+    }
+    const lines = [
+        `compaction history (${listing.entries.length} ` +
+            `${listing.entries.length === 1 ? 'archive' : 'archives'}, ${listing.dir})`,
+        '',
+        ...listing.entries.map(archiveRow),
+    ];
+    if (listing.otherRuns > 0) {
+        lines.push('');
+        lines.push(`  (${listing.otherRuns} more ${listing.otherRuns === 1 ? 'archive' : 'archives'} ` +
+            'from earlier runs in this directory)');
+    }
+    return lines.join('\n');
+}
+/**
+ * `/compact show <n>` - metadata, the stored summary, and the path.
+ *
+ * `<n>` IS THE COMPACTION INDEX WITHIN THIS RUN - the `#n` `/compact history`
+ * printed, which is also the `index` field in the document. Those are the same
+ * number by construction: the listing is `runId`-scoped and `index` is unique
+ * within a run, so there is no second numbering to confuse it with.
+ *
+ * IT NEVER PRINTS MESSAGE BODIES (DH-9). A single archive can be megabytes and
+ * the transcript is not a pager; the path is the useful output.
+ */
+function formatCompactionShow(ctx, raw) {
+    const runId = ctx.controller.getCompactionRunId();
+    if (!runId) {
+        return 'Compaction is not registered for this session (started with --no-compaction).';
+    }
+    const n = Number.parseInt(raw.trim(), 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return 'Usage: /compact show <n>  (see /compact history)';
+    const entry = findArchive(runId, n);
+    if (!entry)
+        return `No archive #${n}. Try /compact history.`;
+    const lines = [
+        `compaction #${entry.index} (${entry.trigger}, ${entry.mode})`,
+        `  When:     ${new Date(entry.createdAt).toISOString()}`,
+        `  Tokens:   ${formatTokens(entry.tokensBefore)} -> ${formatTokens(entry.tokensAfter)}`,
+        `  Dropped:  ${entry.droppedCount} messages${entry.clipped ? ' (archive body clipped to fit)' : ''}`,
+        `  Model:    ${entry.model || '(none)'}`,
+    ];
+    if (entry.tailRelief) {
+        lines.push(`  Clipped:  ${entry.tailRelief.messages} tool results in the retained turns ` +
+            `(${formatTokens(entry.tailRelief.charsRemoved)} chars)`);
+    }
+    lines.push(`  File:     ${entry.path}`);
+    if (entry.summary) {
+        lines.push('');
+        lines.push(entry.summary);
+    }
+    return lines.join('\n');
+}
+const USAGE = 'Usage: /compact [status | on | off | threshold <n> | keep <n> | history | show <n> | <instructions>]';
+/**
+ * The `/compact` handler.
+ *
+ * `/compact <free text>` is the Claude Code affordance and is therefore the
+ * FALL-THROUGH rather than a subcommand: anything that is not one of the seven
+ * verbs is instructions for the summarizer.
+ */
+export async function runCompactCommand(ctx) {
+    const arg = ctx.args.trim();
+    const [rawVerb, value] = arg.split(/\s+/, 2);
+    const verb = (rawVerb ?? '').toLowerCase();
+    const controller = ctx.controller;
+    if (verb === 'status') {
+        ctx.notify('info', formatCompactionStatus(ctx));
+        return;
+    }
+    if (verb === 'on' || verb === 'off') {
+        const enabled = verb === 'on';
+        const applied = controller.setCompactionConfig({ enabled });
+        ctx.persistConfig({ compaction: { enabled } });
+        if (!controller.isCompactionRegistered()) {
+            // The honest branch, and the whole point of splitting by what was decided
+            // at construction. `enabled` decides whether the wiring EXISTS, and a
+            // session that started without one cannot be given one mid-flight: the
+            // `Agent` takes the port in its constructor and has no setter for it
+            // (§3.2). `/fast on` and `/team on` each record the same shape.
+            ctx.notify('info', enabled
+                ? 'Compaction is off for this session (started with --no-compaction). Saved for next launch.'
+                : 'Compaction is already off for this session. Saved for next launch.');
+            return;
+        }
+        controller.setCompactionEnabled(applied.enabled);
+        ctx.toast('success', `Auto-compaction ${enabled ? 'on' : 'off'}.`);
+        return;
+    }
+    if (verb === 'threshold') {
+        const raw = (value ?? '').trim();
+        const parsed = raw ? parseThresholdInput(raw) : null;
+        if (parsed === null) {
+            ctx.notify('warn', 'Usage: /compact threshold <0.5-0.95>  (also accepts 90%)');
+            return;
+        }
+        const applied = controller.setCompactionConfig({ threshold: parsed });
+        ctx.persistConfig({
+            compaction: { threshold: applied.threshold },
+        });
+        // The APPLIED value, not the requested one: `clampCompactionConfig` may have
+        // moved it, and reporting what was asked for would make the clamp invisible.
+        ctx.toast('success', `Compaction threshold set to ${Math.round(applied.threshold * 100)}%.`);
+        return;
+    }
+    if (verb === 'keep') {
+        const n = Number.parseInt((value ?? '').trim(), 10);
+        if (!Number.isFinite(n) || n <= 0) {
+            ctx.notify('warn', 'Usage: /compact keep <1-20>');
+            return;
+        }
+        const applied = controller.setCompactionConfig({ keepRecentTurns: n });
+        ctx.persistConfig({
+            compaction: { keepRecentTurns: applied.keepRecentTurns },
+        });
+        ctx.toast('success', `Keeping ${applied.keepRecentTurns} recent turns verbatim.`);
+        return;
+    }
+    // BEFORE THE FREE-TEXT FALL-THROUGH, so a user cannot accidentally summarize
+    // with the word "history".
+    if (verb === 'history') {
+        ctx.notify('info', formatCompactionHistory(ctx));
+        return;
+    }
+    if (verb === 'show') {
+        ctx.notify('info', formatCompactionShow(ctx, value ?? ''));
+        return;
+    }
+    if (verb === 'help' || verb === '?') {
+        ctx.notify('info', USAGE);
+        return;
+    }
+    // --- Compact now, with `arg` (possibly empty) as instructions -------------
+    if (!controller.isCompactionRegistered()) {
+        ctx.notify('info', 'Compaction is not registered for this session (started with --no-compaction).');
+        return;
+    }
+    if (!controller.isCompactionEnabled()) {
+        ctx.notify('warn', 'Auto-compaction is off. Turn it on with /compact on, then try again.');
+        return;
+    }
+    const instructions = arg.length > 0 ? arg.slice(0, COMPACTION_LIMITS.summaryMaxChars) : undefined;
+    if (ctx.state.status === 'running') {
+        // QUEUED, NOT RACED (D-17). Replacing `messages` under a live loop is a race;
+        // a flag `shouldCompact` honours at the next turn boundary is not, because
+        // the boundary is the one moment the engine is single-threaded with respect
+        // to the history, by construction.
+        controller.queueCompaction(instructions);
+        ctx.toast('info', 'Will compact before the next turn.');
+        return;
+    }
+    ctx.toast('info', 'Compacting context...');
+    const outcome = await controller.compactNow(instructions);
+    if (outcome.ok) {
+        ctx.toast('success', 'Context compacted.');
+        return;
+    }
+    // THE SAME `invalid_history: <reason>` VOCABULARY THE ENGINE PRODUCES (D-25 /
+    // P1-7), so the card, the log and `/compact status` cannot tell the idle path
+    // apart from the in-loop one.
+    ctx.notify('warn', `Compaction did not run: ${outcome.reason ?? 'unknown'}`);
+}

package/dist/compaction/compactor.d.ts

@@ -0,0 +1,268 @@
+/**
+ * `Compactor` — the `ContextManager` implementation (context-auto-compaction
+ * §3.4 / §3.6 / §3.7 / §3.8).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
+ *
+ * THIS IS THE POLICY HALF OF THE FEATURE. The engine owns exactly one thing -
+ * structural validity - and every other decision is here: when to fire, what to
+ * keep, which model summarizes, what the prompt asks for, what happens when the
+ * call fails, and when to stop spending.
+ */
+import { type Message, type ModelInfo, type ModelRef, type TokenUsage, type AssistantMessage, type CompactionContext, type CompactionOutcome, type CompactionProbe, type ContextManager, type LLMRequest } from '@aragon-agent/core';
+import type { CliConfig } from '../config/schema.js';
+import type { NoticeLevel } from '../agent/reducer.js';
+import type { CompactionEvent, Pressure } from './types.js';
+export interface CompactorDeps {
+    /** Read LIVE on every call — the controller replaces the object on mutation. */
+    getConfig: () => CliConfig;
+    hasKey: (providerId: string) => boolean;
+    getApiKey: (providerId: string) => string | undefined;
+    /**
+     * The engine's live history and system prompt.
+     *
+     * `shouldCompact` NEEDS THEM, and that is the whole reason they are here.
+     * `CompactionProbe` carries `messageCount` but not the messages — the port is
+     * synchronous and cheap by design (D-3) — so the ESTIMATE fallback (§3.4.2)
+     * has nothing to measure unless the host supplies it. Estimating over an empty
+     * array yields 0 %, which is exactly the naive answer §3.4.2 exists to reject:
+     * the first request of a resumed 180 k-token session is the most dangerous
+     * moment in this feature's life, `lastUsage` is `undefined` there by
+     * definition, and a trigger that reads 0 % never fires.
+     *
+     * LAZY, and they must be: the wiring is constructed BEFORE the `Agent` (C-12),
+     * so a closure that touches it is only valid from inside a call the loop makes.
+     */
+    getMessages: () => readonly Message[];
+    getSystemPrompt: () => string;
+    /** `ModelInfo` for ANY model, so the summarizer's own window and price resolve. */
+    getModelInfoFor: (ref: Pick<ModelRef, 'providerId' | 'modelId'>) => ModelInfo;
+    isPricedModel: (ref: Pick<ModelRef, 'providerId' | 'modelId'>) => boolean;
+    /** The compactor's OWN fail-fast transport (D-10). Supplied by the wiring. */
+    complete: (providerId: string, request: LLMRequest) => Promise<AssistantMessage>;
+    emit: (event: CompactionEvent) => void;
+    notify: (level: NoticeLevel, text: string) => void;
+    /**
+     * Publish the occupancy this checkpoint measured (hardening §3.2.4 / DH-15).
+     *
+     * REPORTING IS NOT A SIDE EFFECT OF DECIDING; it is the other half of R-11.
+     * `shouldCompact` measures ONCE, ABOVE the guards, and calls this
+     * unconditionally on every enabled checkpoint - so the gauge and the trigger
+     * keep reading one number even on the turns a guard declines to compact.
+     * Optional, so a `Compactor` built without a UI (the child manager, W3) passes
+     * nothing and the call is one `?.` per turn.
+     */
+    onPressure?: (pressure: Pressure) => void;
+}
+/** Per-instance bounds a child manager tightens (hardening §3.4.2 mechanism B). */
+export interface CompactorOptions {
+    /**
+     * Guard 2's ceiling for THIS compactor.
+     *
+     * A FIELD RATHER THAN A DIRECT `COMPACTION_LIMITS` READ, because a child gets a
+     * tighter one (W3 / DH-6) and `maxPerRun` is STRUCTURAL, not policy - there is
+     * no config path to it by design (`limits.ts` header). Defaults to the lead's
+     * value, so every existing construction site is unchanged.
+     */
+    maxPerRun?: number;
+}
+/** The summarizer the next compaction would use. */
+export interface SummarizerChoice {
+    ref: ModelRef;
+    /** Whether the fast tier supplied it, for `/compact status` and the card. */
+    fromFastTier: boolean;
+}
+export declare class Compactor implements ContextManager {
+    private readonly deps;
+    private readonly log;
+    private compactionsThisRun;
+    private lastCompactionTurn;
+    private compactions;
+    private tokensReclaimed;
+    private sessionUsage;
+    private pricingUnknown;
+    private inFlight;
+    private consecutiveNoProgress;
+    private selfDisabled;
+    private selfDisabledReason;
+    private pendingManual;
+    private generation;
+    /** Calibration for every ESTIMATED figure (D-23). Recomputed on every turn_end. */
+    private estimateOffset;
+    /** The last pressure computed, so the status bar and `/compact status` agree. */
+    private lastPressure;
+    /**
+     * The history LENGTH the measurement in `lastUsage` covered (hardening W1).
+     *
+     * `undefined` DISABLES THE DELTA and reproduces round 1's arithmetic exactly.
+     * Every host-side mutation that is not an append must clear it - see
+     * `invalidateMeasurement`.
+     */
+    private measuredPrefixLength;
+    /**
+     * The messages the last splice dropped, held ONLY until the wiring collects
+     * them for the archive (W4 / RV-3).
+     *
+     * NOT ON `CompactionRecord`: that record is dispatched into the reducer and
+     * retained in view state for the card's lifetime, so putting a megabyte of
+     * history on it would park the dropped conversation in React state - precisely
+     * the memory this compaction just reclaimed.
+     *
+     * SET ONLY WHEN ARCHIVING IS ON, so with the key off the slice is never
+     * retained and W4 costs nothing.
+     */
+    private lastDropped;
+    private callAbort;
+    private callAbortReason;
+    /** Guard 2's ceiling for this instance (hardening §3.4.2 mechanism B / DH-16). */
+    private readonly maxPerRun;
+    constructor(deps: CompactorDeps, opts?: CompactorOptions);
+    /** `agent_start` — the per-run cap resets, the session totals do not. */
+    onRunStart(): void;
+    /**
+     * `turn_end` — recompute the calibration offset (D-23).
+     *
+     * RE-MEASURED EVERY TURN, not once, so it tracks a toolset that changed
+     * mid-session (`/tools`, a skill that registers one).
+     */
+    onTurnEnd(usage: TokenUsage, messages: readonly Message[], systemPrompt: string): void;
+    /**
+     * Any host-side history mutation that is NOT an append (hardening §3.2.3).
+     *
+     * `/clear`, `/resume`, and the splice itself: after any of them a recorded
+     * index means nothing, and the delta would be measured against the wrong
+     * array. `estimateAppendedTokens` bounds-checks as well, so a MISSED call here
+     * costs accuracy - the number degrades to round 1's - and never correctness.
+     */
+    invalidateMeasurement(): void;
+    /**
+     * The dropped messages, released as they are returned (W4 / RV-3).
+     *
+     * `take` RATHER THAN `get`: the reference is dropped on read, so a wiring that
+     * declines to archive (key off, or `applied: false`) cannot pin it and a second
+     * read cannot double-write. `settlePending` calls this on EVERY verdict and
+     * discards on the ones that do not archive, which is what guarantees the array
+     * cannot outlive one compaction regardless of which branch was taken.
+     */
+    takeLastDropped(): Message[] | null;
+    /** Cancel an in-flight summarization (Esc, `dispose`). */
+    abort(): void;
+    /**
+     * Ask for a compaction at the next turn boundary.
+     *
+     * THE BOUNDARY IS THE ONLY MOMENT THE ENGINE IS SINGLE-THREADED WITH RESPECT
+     * TO THE HISTORY, by construction. Replacing `messages` under a live loop is a
+     * race; a flag `shouldCompact` honours there is not.
+     */
+    queueManual(instructions?: string): void;
+    hasPendingManual(): boolean;
+    clearPendingManual(): void;
+    /**
+     * SYNCHRONOUS AND CHEAP. Two deliberate effects: the pressure cache, and
+     * `deps.onPressure` (hardening DH-15).
+     *
+     * THE MEASUREMENT IS TAKEN ONCE, ABOVE THE GUARDS, AND REPORTED
+     * UNCONDITIONALLY. Below them it is skipped on five paths — the per-run cap,
+     * the cooldown, manual, overflow and guard 4 — and TWO OF THOSE NEVER CLEAR
+     * WITHIN A RUN. A gauge fed from the measurement would therefore go dark
+     * exactly when compaction is exhausted and the window is still filling, which
+     * is the one state where the corrected number is the user's only warning. It
+     * would silently revert to the measured base — the very figure W1 exists
+     * because it under-reports.
+     *
+     * `!config.enabled` STAYS THE FIRST STATEMENT, so a session that turned the
+     * feature off pays nothing at all and AC-1's byte-identity claim is untouched.
+     */
+    shouldCompact(probe: CompactionProbe): boolean;
+    compact(ctx: CompactionContext): Promise<CompactionOutcome>;
+    private runCompaction;
+    /** Tail relief against this session's window (hardening §3.3.3 / W2). */
+    private relieveInPlace;
+    /**
+     * The failure ladder (§3.7).
+     *
+     * Rung 1 is the fast tier (or the main model); rung 2 is ONE retry on the MAIN
+     * model when rung 1 used the fast tier, because "a fast model that cannot
+     * summarize" is the most likely single failure. Rungs 3 and 4 are the caller's,
+     * because they depend on `onFailure`.
+     */
+    private runLadder;
+    private callOnce;
+    /**
+     * Guard 3 — the progress requirement (§3.8).
+     *
+     * ADVISORY ON OVERFLOW, NEVER A VETO (D-24 / P1-13). The arithmetic that makes
+     * this guard sensible for the proactive trigger INVERTS on the reactive one: a
+     * pressure compaction that reclaims little has spent money to buy two turns and
+     * should stop, while an overflow compaction that reclaims little is the
+     * difference between a continuing run and a dead one, because the provider has
+     * already refused the request.
+     *
+     * The projection is ESTIMATED — no usage exists for a history that has not been
+     * sent yet — and is therefore CALIBRATED with `estimateOffset` (D-23).
+     *
+     * IT TAKES THE *UI* TRIGGER, not `ctx.trigger`. A queued `/compact` reaches the
+     * loop as an ordinary `pressure` checkpoint (that is what the queue IS), so
+     * charging its result to guard 4's counter would let a user who types
+     * `/compact` twice on a short conversation self-disable the proactive trigger
+     * for the rest of the session — and be told, wrongly, that their recent turns
+     * exceed the threshold. `uiTrigger` is the only value that knows the difference.
+     */
+    private checkProgress;
+    /**
+     * Guard 4 — stuck detection (§3.8).
+     *
+     * PRESSURE ONLY, AND `pressure` HERE MEANS THE *UI* TRIGGER. A session that
+     * self-disables still survives an overflow rather than dying at the next
+     * request, and if the tail really is too large the overflow attempt is the one
+     * that can do something about it (D-24). A `manual` compaction is excluded for
+     * a different reason: this guard exists to stop UNREQUESTED spend, and
+     * `/compact` on a conversation with nothing worth dropping is a user who asked
+     * — twice — not a runaway loop.
+     */
+    private noteNoProgress;
+    private finish;
+    /**
+     * The pressure the trigger and the gauge both read.
+     *
+     * CACHED on every evaluation, so `/compact status` reports the same number the
+     * last decision used rather than recomputing one that has since moved.
+     */
+    measure(probe: Pick<CompactionProbe, 'lastUsage'> & {
+        messages?: readonly Message[];
+        systemPrompt?: string;
+    }): Pressure;
+    lastMeasured(): Pressure | null;
+    /** Written by the wiring once the engine has reported its verdict. */
+    recordApplied(tokensBefore: number, tokensAfter: number): void;
+    sessionTotals(): {
+        compactions: number;
+        tokensReclaimed: number;
+        usage: TokenUsage;
+        pricingUnknown: boolean;
+        inFlight: boolean;
+        selfDisabled: boolean;
+        selfDisabledReason?: string;
+        generation: number;
+    };
+    /** `/compact on` after a self-disable — the user overriding the guard. */
+    clearSelfDisable(): void;
+    isSelfDisabled(): boolean;
+    /**
+     * Which model summarizes (§3.6.4).
+     *
+     * SAY THE DEFAULT OUT LOUD (P2-8): FOR ALMOST EVERYONE THIS IS THE MAIN MODEL.
+     * `resolveFastTier` returns `{ok: false, reason: 'disabled'}` on
+     * `fast.enabled !== true` alone, and `fast.enabled` defaults to `false` — so
+     * `useFastTier: true` describes a PREFERENCE, not the common path, and the
+     * out-of-the-box first compaction is a ~30 k-token call on the session's own
+     * model. Three things make that the right trade rather than a hidden cost: it
+     * happens at most `maxPerRun` times per run, the alternative is losing the
+     * entire run, and the spend is on the card with the summarizer's own price.
+     */
+    resolveSummarizer(): SummarizerChoice | null;
+    private mainRef;
+    private modelInfo;
+    private effectiveMaxOutputTokens;
+    private noteUsage;
+}