@aragon-agent/cli 0.6.4 → 0.6.7

package/dist/compaction/compactor.js

@@ -17,7 +17,8 @@ import { attemptTailRelief, reliefSummary, tailBudgetTokens } from './tail-budge
 import { buildDigest, isPriorSummaryBlock } from './digest.js';
 import { buildAnchor, buildCompactedBlock, countProtectedPrefix, readGeneration, truncationBody, } from './summary-prompt.js';
 import { accumulateUsage, errorText, runSummarizeCall } from './summarize-call.js';
-import { computeEstimateOffset, computePressure, shouldCompactAt } from './pressure.js';
+import { computePressure, shouldCompactAt } from './pressure.js';
+import { ContextMeter } from './meter.js';
 export class Compactor {
     deps;
     log = getLogger().child('compaction');
@@ -44,18 +45,15 @@ export class Compactor {
     selfDisabledReason;
     pendingManual = null;
     generation = 0;
-    /** Calibration for every ESTIMATED figure (D-23). Recomputed on every turn_end. */
-    estimateOffset;
-    /** The last pressure computed, so the status bar and `/compact status` agree. */
-    lastPressure = null;
     /**
-     * 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`.
      */
-    measuredPrefixLength;
+    ownMeter = null;
     /**
      * The messages the last splice dropped, held ONLY until the wiring collects
      * them for the archive (W4 / RV-3).
@@ -87,28 +85,34 @@ export class Compactor {
         this.lastCompactionTurn = -Infinity;
     }
     /**
-     * `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).
+     * 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.
      */
-    onTurnEnd(usage, messages, systemPrompt) {
-        this.estimateOffset = computeEstimateOffset(usage, messages, systemPrompt);
-        // THE SAME ARRAY `computeEstimateOffset` JUST MEASURED, so the two numbers
-        // describe the same request by construction (hardening §3.2.3).
-        this.measuredPrefixLength = messages.length;
+    onTurnEnd(usage, _messages, _systemPrompt) {
+        this.meter().onTurnEnd(usage);
     }
-    /**
-     * Any host-side history mutation that is NOT an append (hardening §3.2.3).
+    /*
+     * `invalidateMeasurement()` IS GONE, DELIBERATELY (I-9 / RV-2 round two).
+     *
+     * It had exactly two production callers and their reset depths are now
+     * OPPOSITE: `CompactionWiring.onHistoryReplaced` (a `/clear`, `/reset` or
+     * `/resume`) must drop `estimateOffset`, while `settlePending`'s applied
+     * branch (a splice) must KEEP it - the toolset and the model are unchanged, so
+     * the calibration still holds and dropping it makes the gauge fall too far and
+     * climb back (I-5 / I-8). The two used to share a method only because the one
+     * field it cleared happened to be their intersection; that intersection no
+     * longer exists. Both call sites now name the depth they mean, on the meter.
      *
-     * `/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.
+     * Reinstating a forwarder here would hide "which caller gets which depth"
+     * behind a name that mentions neither, and BOTH wrong choices are silent.
      */
-    invalidateMeasurement() {
-        this.measuredPrefixLength = undefined;
-    }
     /**
      * The dropped messages, released as they are returned (W4 / RV-3).
      *
@@ -172,17 +176,13 @@ export class Compactor {
         const config = this.deps.getConfig().compaction;
         if (!config.enabled)
             return false;
-        // THE HISTORY IS PASSED IN, NEVER OMITTED (§3.4.2). Without it the estimate
-        // branch of `computePressure` measures an EMPTY array and reports 0 %, so a
-        // resumed 180 k-token session — where `lastUsage` is `undefined` by
-        // definition and this branch is the only one available — would never trigger.
-        // The measured branch reads `messages` only to estimate what was appended
-        // after the measurement (hardening §3.2.2); the slice is one turn wide.
-        const pressure = this.measure({
-            ...(probe.lastUsage ? { lastUsage: probe.lastUsage } : {}),
-            messages: this.deps.getMessages(),
-            systemPrompt: this.deps.getSystemPrompt(),
-        });
+        // THE METER READS THE LIVE HISTORY ITSELF (W1), so the estimate branch can no
+        // longer be handed an empty array by a caller that forgot - which used to be
+        // a 0 % reading on precisely the session that most needs a trigger, the
+        // resumed 180 k-token one where `lastUsage` is `undefined` by definition.
+        // The probe's own usage is still passed, because it is the authority for
+        // THIS checkpoint.
+        const pressure = this.meter().measureWith(probe.lastUsage);
         this.deps.onPressure?.(pressure);
         const manual = this.pendingManual !== null;
         // Guard 2 — the per-run cap. BOTH TRIGGERS, HARD. It is the bound that makes
@@ -568,12 +568,17 @@ export class Compactor {
     checkProgress(ctx, uiTrigger, after) {
         const config = this.deps.getConfig().compaction;
         const info = this.modelInfo();
+        // THE OFFSET NOW LIVES ON THE METER (W1), and it is read from the last
+        // PUBLISHED pressure rather than re-derived: `Pressure.estimateOffset` is
+        // carried on every measurement, so this is the same number the field used to
+        // hold, without the compactor owning a second copy of it.
+        const estimateOffset = this.meter().lastPublished()?.estimateOffset;
         const projected = computePressure({
             messages: after,
             systemPrompt: ctx.systemPrompt,
             contextWindow: info.contextWindow,
             windowKnown: true,
-            ...(this.estimateOffset !== undefined ? { estimateOffset: this.estimateOffset } : {}),
+            ...(estimateOffset !== undefined ? { estimateOffset } : {}),
         });
         const target = config.threshold - COMPACTION_LIMITS.minReclaimRatio;
         const madeProgress = projected.ratio < target;
@@ -619,7 +624,9 @@ export class Compactor {
     finish(args, outcome, applied, keepRecentTurnsUsed, announced) {
         const before = args.ctx.messages.length;
         const after = outcome.action === 'replace' ? outcome.messages.length : before;
-        const tokensBefore = this.lastPressure?.occupied ?? 0;
+        // THE OCCUPANCY BEFORE THE SPLICE (I-10). `lastMeasured()` is the pure cache
+        // read on purpose; anything that re-measures here reports 0 reclaimed.
+        const tokensBefore = this.lastMeasured()?.occupied ?? 0;
         // `'relieved'` IS A CLI-ONLY WORD (RV-5 / DH-20). The port reports
         // `'truncated'` for a relief-only compaction, which is accurate for the
         // engine's narrower question; the card's `summarized N messages with
@@ -690,32 +697,30 @@ export class Compactor {
     // Reporting helpers
     // =========================================================================
     /**
-     * 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) {
-        const info = this.modelInfo();
-        const pressure = computePressure({
-            ...(probe.lastUsage ? { lastUsage: probe.lastUsage } : {}),
-            messages: probe.messages ?? [],
-            systemPrompt: probe.systemPrompt ?? '',
-            contextWindow: info.contextWindow,
-            windowKnown: this.deps.isPricedModel({
-                providerId: this.mainRef().providerId,
-                modelId: this.mainRef().modelId,
-            }),
-            ...(this.estimateOffset !== undefined ? { estimateOffset: this.estimateOffset } : {}),
-            ...(this.measuredPrefixLength !== undefined
-                ? { measuredPrefixLength: this.measuredPrefixLength }
-                : {}),
-        });
-        this.lastPressure = pressure;
-        return pressure;
+        return this.meter().measureWith(probe.lastUsage);
     }
+    /**
+     * 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() {
-        return this.lastPressure;
+        return this.meter().lastPublished();
     }
     /** Written by the wiring once the engine has reported its verdict. */
     recordApplied(tokensBefore, tokensAfter) {
@@ -768,6 +773,29 @@ export class Compactor {
             return null;
         return { ref, fromFastTier: false };
     }
+    /**
+     * 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.
+     */
+    meter() {
+        if (this.deps.meter)
+            return this.deps.meter;
+        if (!this.ownMeter) {
+            this.ownMeter = new ContextMeter({
+                getMessages: () => this.deps.getMessages(),
+                getSystemPrompt: () => this.deps.getSystemPrompt(),
+                getModelInfo: () => this.modelInfo(),
+                isWindowKnown: () => this.deps.isPricedModel(this.mainRef()),
+                getWindowOverride: () => this.deps.getConfig().contextWindow,
+            });
+        }
+        return this.ownMeter;
+    }
     mainRef() {
         const config = this.deps.getConfig();
         return {

package/dist/compaction/context-command.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The `/context` slash command (context-usage-gauge-accuracy §3.7 / W6).
+ *
+ * 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` FOR THE REASON `/compact` DOES
+ * (C-16 / P1-12): `CLAUDE.md` caps a source file at 1000 lines and `builtins.ts`
+ * is already past it. `builtins.ts` gets the registration and nothing else.
+ *
+ * THIS IS THE GUARANTEED REPORTING SURFACE FOR OCCUPANCY. The status bar drops
+ * readouts on a narrow terminal, the gauge is a bar and a rounded percentage,
+ * and neither can say WHERE the denominator came from or WHAT the session total
+ * includes. Every question a user asks after distrusting the bar is answered
+ * here, at any width, in any mode - which is also why the honesty rules below
+ * are not decoration.
+ */
+import type { CommandContext } from '../commands/registry.js';
+/**
+ * `/context` - occupancy, denominator, freshness, compaction, session spend.
+ *
+ * THE OCCUPANCY COMES FROM `controller.getContextUsage()` AND NOWHERE ELSE
+ * (RV-8). The obvious alternative, `getCompactionSnapshot().pressure`, returns
+ * `offCompactionSnapshot()`'s HARDCODED ZERO pressure whenever compaction was
+ * never registered - so a report built on it would read `0%` for exactly the
+ * sessions this whole feature exists to fix. `/compact status` gets away with
+ * reading it only because it returns early on that branch and never prints an
+ * occupancy line at all.
+ */
+export declare function formatContextReport(ctx: CommandContext): string;
+/** `/context` takes no arguments; anything after it is ignored. */
+export declare function runContextCommand(ctx: CommandContext): void;

package/dist/compaction/context-command.js

@@ -0,0 +1,166 @@
+/**
+ * The `/context` slash command (context-usage-gauge-accuracy §3.7 / W6).
+ *
+ * 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` FOR THE REASON `/compact` DOES
+ * (C-16 / P1-12): `CLAUDE.md` caps a source file at 1000 lines and `builtins.ts`
+ * is already past it. `builtins.ts` gets the registration and nothing else.
+ *
+ * THIS IS THE GUARANTEED REPORTING SURFACE FOR OCCUPANCY. The status bar drops
+ * readouts on a narrow terminal, the gauge is a bar and a rounded percentage,
+ * and neither can say WHERE the denominator came from or WHAT the session total
+ * includes. Every question a user asks after distrusting the bar is answered
+ * here, at any width, in any mode - which is also why the honesty rules below
+ * are not decoration.
+ */
+import { formatCost, formatTokens, promptTokensOf } from '../agent/usage.js';
+/**
+ * `/context` - occupancy, denominator, freshness, compaction, session spend.
+ *
+ * THE OCCUPANCY COMES FROM `controller.getContextUsage()` AND NOWHERE ELSE
+ * (RV-8). The obvious alternative, `getCompactionSnapshot().pressure`, returns
+ * `offCompactionSnapshot()`'s HARDCODED ZERO pressure whenever compaction was
+ * never registered - so a report built on it would read `0%` for exactly the
+ * sessions this whole feature exists to fix. `/compact status` gets away with
+ * reading it only because it returns early on that branch and never prints an
+ * occupancy line at all.
+ */
+export function formatContextReport(ctx) {
+    const controller = ctx.controller;
+    const usage = controller.getContextUsage();
+    const lines = ['Context'];
+    lines.push(`  Occupancy      ${occupancyLine(usage)}`);
+    lines.push(`  Window         ${windowLine(usage)}`);
+    lines.push(`  Since measured ${freshnessLine(usage)}`);
+    lines.push(`  Compaction     ${compactionLine(ctx)}`);
+    lines.push(`  Session spend  ${spendLine(ctx)}`);
+    // THE SENTENCE THAT MAKES THE LINE ABOVE HONEST (D-7 / N-3). The session
+    // total folds in subagents, the fast tier and compaction's own summarization
+    // calls - three other models' tokens in a figure sitting next to the lead's
+    // occupancy. Splitting it into four counters would need four units of
+    // provenance argument for one line of output; SAYING what it contains costs
+    // one line and answers the same question.
+    lines.push('                 includes subagent, fast-tier and compaction spend,');
+    lines.push('                 not just this conversation');
+    return lines.join('\n');
+}
+/**
+ * `43%   86.2k of 200k   [measured 85.1k + 1.1k estimated]`
+ *
+ * THE BREAKDOWN IS THE POINT. "43%" alone cannot be checked by a user who thinks
+ * it is wrong; naming how much of it is a provider measurement and how much is
+ * our own guess about messages appended since tells them whether to distrust the
+ * number or the model.
+ */
+function occupancyLine(usage) {
+    const approximate = usage.source === 'estimate' || usage.deltaTokens > 0;
+    const pct = `${approximate || !usage.windowKnown ? '~' : ''}${usage.pct}%`;
+    const measured = Math.max(0, usage.occupied - usage.deltaTokens);
+    const breakdown = usage.source === 'estimate'
+        ? `[estimated ${formatTokens(usage.occupied)}]`
+        : usage.deltaTokens > 0
+            ? `[measured ${formatTokens(measured)} + ${formatTokens(usage.deltaTokens)} estimated]`
+            : `[measured ${formatTokens(measured)}]`;
+    return `${pct}   ${formatTokens(usage.occupied)} of ${formatTokens(usage.window)}   ${breakdown}`;
+}
+/**
+ * Where the denominator came from. THREE SOURCES, ALL NAMED.
+ *
+ * THE PLACEHOLDER BRANCH IS THE ONE THAT MATTERS. `buildRuntimeModel` returns a
+ * flat 128000 for any model the static table has never seen - a custom
+ * `baseUrl`, a self-hosted id, a model released last week - and before this
+ * command there was nothing that would admit the number was invented. A user
+ * reading `128000` next to their 1M-token model concludes the gauge is broken;
+ * they are right, and this line tells them which key fixes it.
+ */
+function windowLine(usage) {
+    if (usage.windowOverridden) {
+        return `${usage.window}   from contextWindow in config.json (overrides the model table)`;
+    }
+    if (!usage.windowKnown) {
+        return (`${usage.window}   PLACEHOLDER - this model is not in the table; ` +
+            'set contextWindow to correct it');
+    }
+    return `${usage.window}   from the model table`;
+}
+/**
+ * How stale the measured half is.
+ *
+ * `deltaTokens` IS A TOKEN COUNT, NOT A MESSAGE COUNT, and this line says so in
+ * tokens for that reason: the meter estimates the appended SLICE, and turning
+ * that back into "4 messages" would be a second derivation of something nobody
+ * recorded.
+ */
+function freshnessLine(usage) {
+    if (usage.source === 'estimate') {
+        return 'no provider-reported usage yet - the whole figure is an estimate';
+    }
+    if (usage.deltaTokens <= 0) {
+        return 'nothing appended since the last provider-reported usage';
+    }
+    return `${formatTokens(usage.deltaTokens)} estimated tokens appended since the last provider-reported usage`;
+}
+/**
+ * The compaction state, IN FIVE FORMS (RV-8).
+ *
+ * A SINGLE FORM WOULD BE A LIE FOUR TIMES OUT OF FIVE. The obvious version of
+ * this line - "on - triggers at 90% (amber at 75%)" - is printed unconditionally
+ * only if you forget that compaction has four other observable states, and the
+ * first of them is `aragon --no-compaction`, where that sentence promises a
+ * rescue that cannot come. A report that exists to be trusted does not get to
+ * have one branch.
+ *
+ * THE PREDICATES ARE THE ONES `formatCompactionStatus` ALREADY USES
+ * (`compaction/command.ts`), not a second set: two ladders over the same three
+ * booleans will eventually disagree, and the disagreement would be between two
+ * commands the user runs precisely because they already distrust something.
+ */
+function compactionLine(ctx) {
+    const controller = ctx.controller;
+    if (!controller.isCompactionRegistered()) {
+        return 'off - not registered for this session (started with --no-compaction)';
+    }
+    const snapshot = controller.getCompactionSnapshot();
+    if (snapshot.selfDisabled) {
+        const reason = snapshot.selfDisabledReason ?? 'no progress';
+        return `self-disabled (${reason}) - no compaction will run until /compact on`;
+    }
+    if (!controller.isCompactionEnabled()) {
+        return 'off for this session - /compact on re-enables it';
+    }
+    const config = controller.getCompactionConfig();
+    const thresholds = `triggers at ${Math.round(config.threshold * 100)}% ` +
+        `(amber at ${Math.round(config.warnThreshold * 100)}%)`;
+    if (!snapshot.live) {
+        return `on, but no summarizer model resolves - ${thresholds}`;
+    }
+    const count = snapshot.compactions;
+    return (`on - ${thresholds}, ${count} this session, ` +
+        `${formatTokens(snapshot.tokensReclaimed)} reclaimed`);
+}
+/**
+ * `1.24M in (incl. 940k cache read, 12k cache write) / 48.2k out, $3.21`
+ *
+ * THE CACHE PARENTHETICAL IS OMITTED WHEN BOTH TERMS ARE ZERO, which is every
+ * direct connection - this CLI never sends `cache_control`, so the terms are
+ * non-zero only behind a gateway that caches on the user's behalf. Those are
+ * exactly the users for whom the pre-feature `^` under-reported (P1-3), and the
+ * clause is how they can see that it no longer does.
+ */
+function spendLine(ctx) {
+    const total = ctx.state.usageTotal;
+    const cached = total.cacheReadTokens + total.cacheWriteTokens;
+    const parenthetical = cached > 0
+        ? ` (incl. ${formatTokens(total.cacheReadTokens)} cache read, ` +
+            `${formatTokens(total.cacheWriteTokens)} cache write)`
+        : '';
+    return (`${formatTokens(promptTokensOf(total))} in${parenthetical} / ` +
+        `${formatTokens(total.outputTokens)} out, ${formatCost(total.costUsd)}`);
+}
+/** `/context` takes no arguments; anything after it is ignored. */
+export function runContextCommand(ctx) {
+    ctx.notify('info', formatContextReport(ctx));
+}