@aragon-agent/cli 0.6.14 → 0.6.15

package/dist/compaction/compactor.d.ts

@@ -1,20 +1,11 @@
-/**
- * `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.
- */
+/** Threshold-authorized compaction with host-owned, append-only task memory. */
 import type { ModelRole } from '../config/model-profiles.js';
 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 { resolveFastTier } from '../fast/resolve.js';
 import { ContextMeter } from './meter.js';
+import { type CompactionIdentity } from './memory-identity.js';
 import type { CompactionEvent, Pressure } from './types.js';
 export interface CompactorDeps {
     mainRole?: ModelRole;
@@ -102,242 +93,80 @@ export declare class Compactor implements ContextManager {
     private compactionsThisRun;
     private lastCompactionTurn;
     private compactions;
-    /**
-     * How many `compact()` calls returned WITHOUT announcing (quiet-noop D-9).
-     *
-     * A SESSION TOTAL, LIKE `compactions`, and reset by neither `onRunStart()` nor
-     * `clearSelfDisable()`: `/compact on` overrides a guard, it does not rewrite
-     * history. `/compact status` is its only reader, and it is the whole of what
-     * keeps a decline reportable once the transcript stops carrying one.
-     */
     private declined;
     private tokensReclaimed;
     private sessionUsage;
     private pricingUnknown;
-    private inFlight;
+    private costUsd;
     private consecutiveNoProgress;
     private selfDisabled;
     private selfDisabledReason;
     private pendingManual;
     private generation;
-    /**
-     * The fallback meter, built on first use when no host injected one (R-1).
-     *
-     * `estimateOffset`, `measuredPrefixLength` and `lastPressure` used to be
-     * FIELDS HERE. They moved to `ContextMeter` wholesale
-     * (context-usage-gauge-accuracy W1), because keeping them here is what put the
-     * only measurement in the process behind `compaction.enabled`.
-     */
     private ownMeter;
-    /**
-     * 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 active;
+    private historyEpoch;
+    private serial;
+    private identity;
+    private legacyFailureNotified;
     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).
-     *
-     * A THIN FORWARDER since context-usage-gauge-accuracy W1. The meter subscribes
-     * to `turn_end` itself, so BOTH PATHS MUST BE IDEMPOTENT: this one recomputes
-     * exactly what the other one did from the same inputs, which it is.
-     *
-     * `messages` / `systemPrompt` stay in the signature and are ignored: the meter
-     * reads them from its own lazy deps, and every existing caller and test keeps
-     * compiling.
-     */
+    onRunEnd(): void;
     onTurnEnd(usage: TokenUsage, _messages: readonly Message[], _systemPrompt: string): 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.
-     */
+    onHistoryReplaced(identity?: CompactionIdentity): void;
+    getIdentity(): CompactionIdentity | undefined;
     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>;
-    /**
-     * Open the card (quiet-noop §3.2).
-     *
-     * THE ONLY EMITTER OF `compaction_start`, AND THE ONLY PLACE `this.compactions`
-     * ADVANCES. A compaction that never reaches an announce point is a DECLINE: it
-     * changed nothing, called nothing and spent nothing, and it is deliberately
-     * indistinguishable - on every human surface except `/compact status`'s
-     * `declined` count (D-9) - from a turn at which `shouldCompact` returned false.
-     * `finish` is the other half of that rule.
-     *
-     * IT RETURNS THE ANNOUNCEMENT RATHER THAN STORING IT (P1-1), and the caller
-     * keeps it in a LOCAL for the lifetime of one `runCompaction` call - the same
-     * slot `index` occupied before this change. An instance field would have needed
-     * a no-re-entrancy argument, and the obvious one is WRONG: guard 1 lives in
-     * `shouldCompact`, while the idle `/compact` path calls `compact()` straight
-     * through `wiring.compactNow()` without consulting it. What actually keeps two
-     * compactions apart is that `command.ts` QUEUES instead of calling `compactNow`
-     * while the loop runs - a property of a different file, which is exactly why
-     * this one must not depend on it. A clobbered field would leave `finish` unable
-     * to settle the card it opened, and a card that never settles pins
-     * `Transcript`'s monotonic boundary for the rest of the session.
-     */
-    private announce;
-    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 prepareCandidate;
+    private selectInput;
+    private checkMinimumCandidate;
+    private digestFor;
+    private summarize;
     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 checkCandidate;
+    private isCurrent;
+    private announce;
+    private keep;
+    private finishRecord;
+    /** Commit only the engine/host verdict; candidates have no authority before this point. */
+    settleOperation(verdict: {
+        applied: boolean;
+        reason?: string;
+        tokensBefore?: number;
+        tokensAfter: number;
+    }): boolean;
     private noteNoProgress;
-    private finish;
-    /**
-     * The pressure the trigger and the gauge both read - MEASURED NOW.
-     *
-     * A FORWARDER since W1: the decision point supplies its own authoritative
-     * `lastUsage` (the probe's), and the meter owns everything else. `messages` /
-     * `systemPrompt` stay in the signature and are ignored, because the meter
-     * reads the LIVE history through its own deps - which is strictly better than
-     * a caller that could pass `[]` and get a 0 % reading (the old default here).
-     */
-    measure(probe: Pick<CompactionProbe, 'lastUsage'> & {
+    measure(_probe: Pick<CompactionProbe, 'lastUsage'> & {
         messages?: readonly Message[];
         systemPrompt?: string;
     }): Pressure;
-    /**
-     * The last pressure PUBLISHED. NEVER re-measured - `lastPublished`, not
-     * `current` (I-10 / RV-3).
-     *
-     * `finish()` below reads this for `tokensBefore`, which is the sole upstream of
-     * `tokensReclaimed`, the card's "reclaimed N tokens" and `/compact status`'s
-     * session total. All three want the occupancy BEFORE the splice. Point this at
-     * `meter.current()` and the moment the meter is dirty - which after a splice it
-     * always is - `tokensBefore` becomes the POST-compaction figure, `reclaimed`
-     * collapses to 0, and the card renders that with nothing logging a fault.
-     */
     lastMeasured(): Pressure | null;
-    /** Written by the wiring once the engine has reported its verdict. */
     recordApplied(tokensBefore: number, tokensAfter: number): void;
     sessionTotals(): {
+        selfDisabledReason?: string | undefined;
         compactions: number;
-        /** Checkpoints that declined before committing to any work (quiet-noop D-9). */
         declined: number;
         tokensReclaimed: number;
         usage: TokenUsage;
+        costUsd: number;
         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;
-    /**
-     * The meter this compactor reads, injected or private (R-1).
-     *
-     * MEMOIZED, because a fresh meter on every call would have no `estimateOffset`
-     * and no cached pressure - `lastMeasured()` would answer `null` forever and
-     * `tokensReclaimed` would sit at 0. The fallback exists so the ten existing
-     * `compaction-*.test.ts` construction sites compile unchanged; production
-     * injects, and `context-gauge-wiring.test.ts` asserts the single instance.
-     */
+    private mainChoice;
     private meter;
     private mainRef;
-    private modelInfo;
-    private effectiveMaxOutputTokens;
+    private settingsKey;
     private noteUsage;
 }