@aragon-agent/cli 0.6.46 → 0.6.48

package/dist/compaction/meter.d.ts

@@ -1,276 +0,0 @@
-/**
- * `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 { ContextWindowOrigin } from '../config/schema.js';
-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;
-    /**
-     * WHERE the override above came from, read live beside it
-     * (profile-context-window §6.1). Optional so every existing construction
-     * site stays untouched: a meter built without it reports an overridden
-     * window with origin `undefined`, and `/context` falls back to its
-     * pre-feature "from contextWindow configuration" wording byte-for-byte.
-     */
-    getWindowOverrideOrigin?(): ContextWindowOrigin | undefined;
-    getRequestVersion?(): number;
-}
-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;
-    /** Whether the one-per-run empty-measurement warning has been spent. */
-    private hasWarnedUnmeasuredInput;
-    private prefixLast;
-    private sampledPrompt;
-    private sampledVersion;
-    private publishedLength;
-    private publishedLast;
-    private publishedPrompt;
-    private publishedVersion;
-    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;
-    /** Compatibility reads cannot establish or resurrect a provider sample. */
-    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 (window override or model metadata refresh).
-     *
-     * 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
-     * Changing the model connection or request environment requires the deep
-     * invalidation path instead; its measurement is no longer transferable.
-     */
-    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;
-    /**
-     * ONE warn per run (context-usage-zero-input-tokens B). A single day of
-     * real usage logged 1,973 zero-input turns; a per-turn warning is a flood
-     * that teaches whoever reads the file to ignore it.
-     *
-     * The logger is resolved LAZILY rather than captured at construction:
-     * hosts build this class before `installLogging()`, and a child captured
-     * then would stay bound to the silent pre-install logger forever.
-     */
-    private warnUnmeasuredInputOnce;
-    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 refreshValidity;
-    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;
-}