@aragon-agent/cli 0.6.2 → 0.6.3

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;
+}