@aragon-agent/cli 0.6.3 → 0.6.7

package/dist/compaction/compactor.d.ts

@@ -12,6 +12,7 @@
 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 { ContextMeter } from './meter.js';
 import type { CompactionEvent, Pressure } from './types.js';
 export interface CompactorDeps {
     /** Read LIVE on every call — the controller replaces the object on mutation. */
@@ -42,6 +43,24 @@ export interface CompactorDeps {
     complete: (providerId: string, request: LLMRequest) => Promise<AssistantMessage>;
     emit: (event: CompactionEvent) => void;
     notify: (level: NoticeLevel, text: string) => void;
+    /**
+     * The ONE owner of occupancy measurement (context-usage-gauge-accuracy W1).
+     *
+     * THE COMPACTOR NO LONGER MEASURES. It used to hold `estimateOffset`,
+     * `measuredPrefixLength` and `lastPressure` itself, which locked the only
+     * measuring code in the process behind `compaction.enabled` - and a session
+     * that turned compaction OFF is exactly the one whose gauge then had a single
+     * sample per turn and nothing else. Reading a meter the controller owns makes
+     * "the trigger and the gauge read one number" a STRUCTURAL fact rather than a
+     * discipline (§3.3).
+     *
+     * OPTIONAL SO EVERY EXISTING CONSTRUCTION SITE COMPILES (R-1), and lazily
+     * replaced by a private one built from the deps already here. PRODUCTION MUST
+     * INJECT: `context-gauge-wiring.test.ts` asserts one instance per process
+     * (`controller.getContextMeter()` is the same object the wiring forwards), and
+     * two meters in one session means two answers to one question.
+     */
+    meter?: ContextMeter;
     /**
      * Publish the occupancy this checkpoint measured (hardening §3.2.4 / DH-15).
      *
@@ -78,6 +97,15 @@ 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;
@@ -87,18 +115,15 @@ export declare class Compactor implements ContextManager {
     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).
+     * The fallback meter, built on first use when no host injected one (R-1).
      *
-     * `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`.
+     * `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 measuredPrefixLength;
+    private ownMeter;
     /**
      * The messages the last splice dropped, held ONLY until the wiring collects
      * them for the archive (W4 / RV-3).
@@ -120,21 +145,17 @@ export declare class Compactor implements ContextManager {
     /** `agent_start` — the per-run cap resets, the session totals do not. */
     onRunStart(): void;
     /**
-     * `turn_end` — recompute the calibration offset (D-23).
+     * `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).
+     * 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.
      *
-     * `/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.
+     * `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.
      */
-    invalidateMeasurement(): void;
+    onTurnEnd(usage: TokenUsage, _messages: readonly Message[], _systemPrompt: string): void;
     /**
      * The dropped messages, released as they are returned (W4 / RV-3).
      *
@@ -175,6 +196,29 @@ export declare class Compactor implements ContextManager {
      */
     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;
@@ -223,20 +267,36 @@ export declare class Compactor implements ContextManager {
     private noteNoProgress;
     private finish;
     /**
-     * The pressure the trigger and the gauge both read.
+     * The pressure the trigger and the gauge both read - MEASURED NOW.
      *
-     * CACHED on every evaluation, so `/compact status` reports the same number the
-     * last decision used rather than recomputing one that has since moved.
+     * 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'> & {
         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(): {
         compactions: number;
+        /** Checkpoints that declined before committing to any work (quiet-noop D-9). */
+        declined: number;
         tokensReclaimed: number;
         usage: TokenUsage;
         pricingUnknown: boolean;
@@ -261,6 +321,16 @@ export declare class Compactor implements ContextManager {
      * 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 meter;
     private mainRef;
     private modelInfo;
     private effectiveMaxOutputTokens;