@aragon-agent/cli 0.6.3 → 0.6.7

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

package/dist/compaction/meter.d.ts

@@ -0,0 +1,251 @@
+/**
+ * `ContextMeter` - the ONE owner of "how full is the context right now"
+ * (context-usage-gauge-accuracy §3.2 / W1).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`). If this module is ever moved to a new tree, the
+ * scanner's hardcoded directory list must be widened IN THE SAME COMMIT - a
+ * scanner that silently stops scanning is worse than no scanner, and this
+ * package has paid for that edit eleven times (I-7).
+ *
+ * IT LIVES HERE BUT IT IS NOT PART OF COMPACTION, and that is deliberate. The
+ * whole point of this class is that occupancy is measurable when compaction is
+ * OFF: `AgentController` builds a `CompactionWiring` only when
+ * `compaction.enabled` is true, so a measurement owned by the compactor is
+ * unreachable for exactly the sessions that most need a working gauge. It sits
+ * in this directory because `pressure.ts` - the arithmetic it drives - already
+ * does, and because moving it would cost a scanner edit for no gain (R-10).
+ *
+ * THE STATE MACHINE IN ONE PARAGRAPH. Every mutation of the history marks the
+ * meter DIRTY; every read that finds it dirty re-measures SYNCHRONOUSLY. That
+ * ordering is what removes the subscription-order dependency in the APPEND
+ * direction: it does not matter whether this class or the compaction wiring
+ * hears `tool_execution_end` first, because whoever reads gets a number that
+ * includes the appended message either way (I-2). It does NOT remove the
+ * dependency in the REPLACE direction - a splice does not announce itself to a
+ * listener that has not run yet - which is why the splice marks this dirty from
+ * `CompactionWiring.settlePending`'s own synchronous code (I-9), and why
+ * `current()` carries a structural belt for a missed invalidation site.
+ */
+import type { AgentEvent, Message, ModelInfo, TokenUsage } from '@aragon-agent/core';
+import type { ContextUsageSnapshot, Pressure } from './types.js';
+/**
+ * How long a scheduled publish waits.
+ *
+ * IT MUST BE A DELAY, NOT ZERO, AND NOT A SYNCHRONOUS MEASUREMENT (I-3). The
+ * loop emits `tool_execution_end` BEFORE it pushes the `tool_result` message, so
+ * anything that measures inside that event measures a history missing the single
+ * largest message of the turn - silently, and every turn. A `setTimeout` is
+ * necessarily later than that synchronous push.
+ *
+ * 400 ms also caps the publish rate at 2.5 Hz, which together with the reducer's
+ * identity short-circuit keeps a permanently visible row from becoming a
+ * re-render source (R-3).
+ */
+export declare const CONTEXT_METER_TICK_MS = 400;
+export interface ContextMeterDeps {
+    /**
+     * The engine's live history and system prompt.
+     *
+     * LAZY, and they must be: the controller constructs this before the `Agent`
+     * exists, so a closure that touches `this.agent` is only valid from inside a
+     * call made later.
+     */
+    getMessages(): readonly Message[];
+    getSystemPrompt(): string;
+    /** `ModelInfo` for the MAIN model. Re-read on every measurement - `/model` exists. */
+    getModelInfo(): ModelInfo;
+    /** Whether the STATIC model table knows this model, i.e. the window is real. */
+    isWindowKnown(): boolean;
+    /**
+     * The user's `contextWindow` override, or `null` for AUTO. Re-read on every
+     * measurement, so a live settings edit moves the denominator without a relaunch.
+     */
+    getWindowOverride(): number | null;
+}
+export type ContextUsageListener = (usage: ContextUsageSnapshot) => void;
+/**
+ * The projection `ViewState` and `/context` read (§4.1).
+ *
+ * THE ONLY CONVERTER between `Pressure` and `ContextUsageSnapshot`. Two of them
+ * would eventually round the percentage differently, and "the status bar says 43
+ * and `/context` says 44" is the exact class of disagreement this whole feature
+ * exists to remove.
+ */
+export declare function toContextUsage(p: Pressure): ContextUsageSnapshot;
+/** The reading a meter with nothing measured yet reports. */
+export declare function emptyContextUsage(): ContextUsageSnapshot;
+export declare class ContextMeter {
+    private readonly deps;
+    private readonly listeners;
+    private unsubscribe;
+    private timer;
+    private disposed;
+    /**
+     * The authoritative usage of the last completed turn.
+     *
+     * Its presence is what selects `computePressure`'s MEASURED branch, so
+     * dropping it is how every reset degrades to an estimate rather than to a
+     * number describing a history that no longer exists.
+     */
+    private lastUsage;
+    /**
+     * The systematic difference between what `estimatePromptTokens` counts and
+     * what the provider bills (D-23) - chiefly the tool schemas.
+     *
+     * SURVIVES A SPLICE AND NOT A SESSION CHANGE (I-8). See `onHistorySpliced`.
+     */
+    private estimateOffset;
+    /** `messages.length` at the `turn_end` that produced `lastUsage`. */
+    private measuredPrefixLength;
+    /** The last pressure PUBLISHED. Never re-derived on read - see `lastPublished`. */
+    private last;
+    /** Whether the history has changed since the last measurement. */
+    private dirty;
+    constructor(deps: ContextMeterDeps);
+    /**
+     * Occupancy right now. FOR THE SCREEN.
+     *
+     * Re-measures synchronously when dirty (I-2), and publishes when it does - the
+     * gauge has to fall in the SAME FRAME as the compaction that caused it (AC-1),
+     * and the caller that triggers this re-measurement is `CompactionWiring`'s own
+     * synchronous `snapshot()` inside `settlePending`. Leaving the publish to the
+     * scheduled tick instead would be worse than slow: the tick fires only when
+     * `dirty`, and this call is what clears it.
+     *
+     * NEVER THROWS. A meter that can throw is a status bar that can take the
+     * process down.
+     */
+    current(): Pressure;
+    /**
+     * The last pressure this meter PUBLISHED. FOR THE BOOKS. Never re-measures.
+     *
+     * `Compactor.lastMeasured()` forwards here and not to `current()`, and the
+     * distinction is load-bearing (I-10): `compactor.ts`'s `tokensBefore` is the
+     * sole upstream of `tokensReclaimed`, the card's "reclaimed N tokens" line and
+     * `/compact status`'s session total. It wants the occupancy BEFORE the splice.
+     * Wired to `current()` it would re-measure the already-spliced history, report
+     * `reclaimed 0`, and render that number without a single log line about it.
+     */
+    lastPublished(): Pressure | null;
+    /** The published projection, or a zeroed one before the first measurement. */
+    currentUsage(): ContextUsageSnapshot;
+    /**
+     * Measure with the caller's own authoritative usage. FOR A DECISION POINT.
+     *
+     * `Compactor.shouldCompact` has a `CompactionProbe.lastUsage` the meter may
+     * not have seen yet, so it supplies it rather than trusting the field here.
+     */
+    measureWith(lastUsage: TokenUsage | undefined): Pressure;
+    /**
+     * `turn_end` - the one moment in the whole flow that is FULLY measured.
+     *
+     * The loop emits it BEFORE pushing the assistant message, so the history right
+     * now is exactly the history the reported `usage` was billed for: the offset
+     * and the prefix length describe the same array by construction, and
+     * `deltaTokens` is 0. Published immediately for that reason - there is no
+     * better number to wait for.
+     */
+    onTurnEnd(usage: TokenUsage): void;
+    /**
+     * A compaction spliced the history (I-8, the SHALLOW reset).
+     *
+     * `estimateOffset` IS KEPT, and that is the whole reason this method is not
+     * `onHistoryReplaced`. The offset describes "what this toolset costs on this
+     * model above what the estimator counts"; a splice changes neither the toolset
+     * nor the model, so it is still valid - and it is the only calibration the
+     * estimate branch has until the next `turn_end`. Dropping it makes the gauge
+     * fall several thousand tokens too far and then visibly climb back on the next
+     * turn, for no reason the user can see (I-5).
+     *
+     * IDEMPOTENT. Both `settlePending` (the authority, I-9) and this meter's own
+     * `compaction_end` handler reach it, and the second one must cost nothing.
+     */
+    onHistorySpliced(): void;
+    /**
+     * The history came from somewhere else entirely (I-8, the DEEP reset):
+     * `/clear`, `/reset`, `/resume`.
+     *
+     * `estimateOffset` GOES TOO, unlike the shallow reset above. `/resume` can
+     * change the model in the same breath (`builtins.ts`'s restore path does), and
+     * an offset carried across that is a calibration constant applied to something
+     * it never calibrated. The first reading afterwards is therefore a bare
+     * estimate - biased LOW, and corrected by the very next `turn_end`. Biased low
+     * and self-correcting beats biased high and permanent.
+     */
+    onHistoryReplaced(): void;
+    /**
+     * Only the DENOMINATOR moved (`/model`, a `contextWindow` edit).
+     *
+     * DELIBERATELY NOT A RESET. The measured base is still a true statement about
+     * the history, so throwing it away would trade a correct numerator for a whole
+     * history estimate and produce a visible jump on a common operation. The
+     * numerator's calibration is one turn stale until the next `turn_end`
+     * refreshes it, which is the trade this method names (RV-13).
+     */
+    onWindowChanged(): void;
+    /**
+     * Something was appended. Mark dirty, arrange a throttled publish, MEASURE
+     * NOTHING (I-3).
+     */
+    scheduleTick(): void;
+    /** Publish to this meter's own subscribers. Returns an unsubscribe function. */
+    subscribe(listener: ContextUsageListener): () => void;
+    /**
+     * Subscribe to the lead agent's stream. IDEMPOTENT.
+     *
+     * THIS TABLE IS NOT THE SOURCE OF COMPACTION CORRECTNESS (I-9). The splice is
+     * marked dirty by `CompactionWiring.settlePending` inside its own synchronous
+     * code, BEFORE it emits either event, so a reader is correct regardless of
+     * which listener the emitter reaches first. The `compaction_end` row below is
+     * a second, idempotent path that serves the manual `/compact` route and any
+     * future splicer.
+     */
+    attach(subscribe: (listener: (event: AgentEvent) => void) => () => void): void;
+    dispose(): void;
+    private onAgentEvent;
+    /**
+     * The structural belt for a missed invalidation site (I-9).
+     *
+     * A recorded prefix that is LONGER than the history it indexes describes an
+     * array that no longer exists. Rather than merely zeroing the delta - which is
+     * what `estimateAppendedTokens` does, keeping the wrong measured base - this
+     * drops the base too and forces the estimate branch.
+     *
+     * THE COMPARISON IS STRICT, AND THAT BOUNDARY IS LOAD-BEARING (IF-1). The
+     * design document wrote `length <= measuredPrefixLength`, which is off by one:
+     * `turn_end` is emitted BEFORE the assistant message is pushed, so the instant
+     * `onTurnEnd` records the prefix the history is EXACTLY that long. An
+     * inclusive test therefore discards a measurement one statement after taking
+     * it - but only when this meter's listener runs before the compaction wiring's,
+     * because the wiring's `snapshot()` is what reads in that window. That is a
+     * silent, subscription-order-dependent fallback to the estimate branch on
+     * every single turn, which is the exact class of bug this feature exists to
+     * remove. A measurement taken at length N describes every history of length
+     * >= N; only a SHORTER one is impossible.
+     *
+     * Returns whether anything was discarded.
+     */
+    private discardStalePrefix;
+    /**
+     * Measure, cache, clear the dirty flag, publish. The ONE write path.
+     *
+     * Every public mutator funnels through here so "what was published" and "what
+     * is cached" cannot drift, which is what makes `lastPublished()` a meaningful
+     * answer rather than a stale one.
+     */
+    private measureAndPublish;
+    private compute;
+    /**
+     * Where the denominator comes from, and whether it can be trusted.
+     *
+     * AN OVERRIDE MAKES THE WINDOW KNOWN (I-6): the user asserted it, so the `~`
+     * that means "this denominator is a guess" has no business staying on the
+     * percentage. `windowOverridden` travels separately so `/context` can still
+     * name the source - a hand-typed window that is wrong is exactly the case that
+     * most needs to be visible.
+     */
+    private resolveWindow;
+    private readSystemPrompt;
+    private publish;
+}