@aragon-agent/cli 0.6.46 → 0.6.48

package/dist/compaction/meter.js

@@ -1,512 +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 { getLogger } from '../logging/logger.js';
-import { computeEstimateOffset, computePressure, isInputSideUnmeasured } from './pressure.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 const CONTEXT_METER_TICK_MS = 400;
-/**
- * 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 function toContextUsage(p) {
-    return {
-        occupied: p.occupied,
-        ...(p.windowSource ? { windowSource: p.windowSource } : {}),
-        window: p.contextWindow,
-        // FROM `ratio`, NOT FROM A SECOND DIVISION. `computePressure` already
-        // clamped it to [0, 1] and already decided what a zero window means.
-        pct: Math.max(0, Math.min(100, Math.round(p.ratio * 100))),
-        source: p.source,
-        deltaTokens: p.deltaTokens,
-        windowKnown: p.windowKnown,
-        windowOverridden: p.windowOverridden,
-        ...(p.windowOverrideOrigin !== undefined
-            ? { windowOverrideOrigin: p.windowOverrideOrigin }
-            : {}),
-    };
-}
-/** The reading a meter with nothing measured yet reports. */
-export function emptyContextUsage() {
-    return {
-        occupied: 0,
-        window: 0,
-        pct: 0,
-        source: 'estimate',
-        deltaTokens: 0,
-        windowKnown: false,
-        windowOverridden: false,
-    };
-}
-export class ContextMeter {
-    deps;
-    listeners = new Set();
-    unsubscribe = null;
-    timer = null;
-    disposed = false;
-    /**
-     * 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.
-     */
-    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`.
-     */
-    estimateOffset;
-    /** `messages.length` at the `turn_end` that produced `lastUsage`. */
-    measuredPrefixLength;
-    /** The last pressure PUBLISHED. Never re-derived on read - see `lastPublished`. */
-    last = null;
-    /** Whether the history has changed since the last measurement. */
-    dirty = true;
-    /** Whether the one-per-run empty-measurement warning has been spent. */
-    hasWarnedUnmeasuredInput = false;
-    prefixLast;
-    sampledPrompt;
-    sampledVersion;
-    publishedLength = -1;
-    publishedLast;
-    publishedPrompt;
-    publishedVersion;
-    constructor(deps) {
-        this.deps = deps;
-    }
-    // =========================================================================
-    // Reading
-    // =========================================================================
-    /**
-     * 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() {
-        // THE BELT (I-9), AND IT RUNS EVEN WHEN NOT DIRTY. The case it exists for is
-        // a splice that NOBODY announced, and in that case a missing `dirty` flag is
-        // precisely the symptom. `estimateAppendedTokens` bounds-checks too, but it
-        // only zeroes the DELTA and keeps the wrong measured base, so that belt does
-        // not cover this.
-        this.refreshValidity();
-        if (!this.dirty && this.last)
-            return this.last;
-        return this.measureAndPublish(this.lastUsage);
-    }
-    /**
-     * 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() {
-        return this.last;
-    }
-    /** The published projection, or a zeroed one before the first measurement. */
-    currentUsage() {
-        return toContextUsage(this.current());
-    }
-    // =========================================================================
-    // Writing
-    // =========================================================================
-    /** Compatibility reads cannot establish or resurrect a provider sample. */
-    measureWith(_lastUsage) {
-        return this.current();
-    }
-    /**
-     * `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) {
-        if (isInputSideUnmeasured(usage)) {
-            // A usage that discloses NOTHING on the input side is not a
-            // measurement of this history (context-usage-zero-input-tokens B):
-            // arming the measured branch with it collapses occupancy to the
-            // turn's own outputTokens and strips the `~` off the gauge. KEEP
-            // WHATEVER IS STILL TRUSTED - an earlier good measurement of a
-            // prefix that still exists (the history only grows between splices,
-            // so "old good base + appended estimate" stays self-consistent), and
-            // the estimate offset it calibrated - and re-measure NOW so the
-            // gauge degrades in this frame instead of after the next turn.
-            this.warnUnmeasuredInputOnce(usage);
-            this.dirty = true;
-            this.current();
-            return;
-        }
-        const messages = this.deps.getMessages();
-        const systemPrompt = this.readSystemPrompt();
-        this.lastUsage = usage;
-        this.estimateOffset = computeEstimateOffset(usage, messages, systemPrompt);
-        this.measuredPrefixLength = messages.length;
-        this.prefixLast = messages[messages.length - 1];
-        this.sampledPrompt = systemPrompt;
-        this.sampledVersion = this.deps.getRequestVersion?.() ?? 0;
-        this.measureAndPublish(usage);
-    }
-    /**
-     * 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() {
-        this.lastUsage = undefined;
-        this.measuredPrefixLength = undefined;
-        this.prefixLast = undefined;
-        if (this.dirty)
-            return;
-        this.dirty = true;
-        this.scheduleTick();
-    }
-    /**
-     * 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() {
-        this.lastUsage = undefined;
-        this.measuredPrefixLength = undefined;
-        this.prefixLast = undefined;
-        this.estimateOffset = undefined;
-        this.sampledPrompt = undefined;
-        this.sampledVersion = undefined;
-        this.dirty = true;
-        this.scheduleTick();
-    }
-    /**
-     * 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() {
-        this.dirty = true;
-        this.current();
-    }
-    /**
-     * Something was appended. Mark dirty, arrange a throttled publish, MEASURE
-     * NOTHING (I-3).
-     */
-    scheduleTick() {
-        this.dirty = true;
-        // NO SUBSCRIBERS, NO TIMER (I-11). `AgentController` is shared with
-        // `aragon exec`, where nothing reads this number; a headless run must not
-        // pay a timer per tool call, and a pending tick must never be able to hold
-        // the process open for an extra 400 ms. `current()` is unaffected - it
-        // measures on demand, so `wiring.snapshot()` and `/context` still work in a
-        // host with no UI.
-        if (this.listeners.size === 0)
-            return;
-        if (this.timer !== null || this.disposed)
-            return;
-        const handle = setTimeout(() => {
-            this.timer = null;
-            if (!this.dirty || this.disposed)
-                return;
-            this.current();
-        }, CONTEXT_METER_TICK_MS);
-        // The other half of I-11: an armed tick must not keep the event loop alive.
-        const unrefable = handle;
-        if (typeof unrefable.unref === 'function')
-            unrefable.unref();
-        this.timer = handle;
-    }
-    // =========================================================================
-    // Plumbing
-    // =========================================================================
-    /** Publish to this meter's own subscribers. Returns an unsubscribe function. */
-    subscribe(listener) {
-        this.listeners.add(listener);
-        return () => {
-            this.listeners.delete(listener);
-        };
-    }
-    /**
-     * 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) {
-        if (this.unsubscribe)
-            return;
-        this.unsubscribe = subscribe((event) => this.onAgentEvent(event));
-    }
-    dispose() {
-        this.disposed = true;
-        if (this.timer !== null) {
-            clearTimeout(this.timer);
-            this.timer = null;
-        }
-        this.unsubscribe?.();
-        this.unsubscribe = null;
-        this.listeners.clear();
-    }
-    // =========================================================================
-    // Internals
-    // =========================================================================
-    /**
-     * 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.
-     */
-    warnUnmeasuredInputOnce(usage) {
-        if (this.hasWarnedUnmeasuredInput)
-            return;
-        this.hasWarnedUnmeasuredInput = true;
-        getLogger().warn('compaction', 'context_input_tokens_unreported', { in: usage.inputTokens, out: usage.outputTokens });
-    }
-    onAgentEvent(event) {
-        switch (event.type) {
-            case 'turn_end':
-                this.onTurnEnd(event.usage);
-                return;
-            case 'tool_execution_end':
-                // DELAYED, NEVER SYNCHRONOUS. See `CONTEXT_METER_TICK_MS` (I-3).
-                this.scheduleTick();
-                return;
-            case 'compaction_end':
-                // The engine's verdict. `applied` means the history really was replaced.
-                if (event.applied)
-                    this.onHistorySpliced();
-                else
-                    this.scheduleTick();
-                return;
-            case 'agent_end':
-                this.scheduleTick();
-                return;
-            default:
-                // `message_update` is a STREAM event and is deliberately ignored (N-2):
-                // the output tokens of an in-flight reply are not knowable until `done`,
-                // and guessing them would add a third approximation to a number that
-                // already carries two.
-                return;
-        }
-    }
-    /**
-     * 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.
-     */
-    discardStalePrefix() {
-        if (this.measuredPrefixLength === undefined)
-            return false;
-        const messages = this.deps.getMessages();
-        if (messages.length >= this.measuredPrefixLength &&
-            messages[this.measuredPrefixLength - 1] === this.prefixLast)
-            return false;
-        this.lastUsage = undefined;
-        this.measuredPrefixLength = undefined;
-        this.prefixLast = undefined;
-        return true;
-    }
-    /**
-     * 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.
-     */
-    refreshValidity() {
-        const messages = this.deps.getMessages();
-        const prompt = this.readSystemPrompt();
-        const version = this.deps.getRequestVersion?.() ?? 0;
-        if (this.sampledPrompt !== undefined &&
-            (prompt !== this.sampledPrompt || version !== this.sampledVersion)) {
-            this.onHistoryReplaced();
-        }
-        if (this.discardStalePrefix())
-            this.dirty = true;
-        const window = this.resolveWindow();
-        const last = this.last;
-        if (messages.length !== this.publishedLength ||
-            messages[messages.length - 1] !== this.publishedLast ||
-            prompt !== this.publishedPrompt || version !== this.publishedVersion ||
-            window.contextWindow !== last?.contextWindow ||
-            window.windowKnown !== last?.windowKnown ||
-            window.windowOverridden !== last?.windowOverridden ||
-            // ORIGIN IS PART OF THE DIRTY CHECK: a save that keeps the same number
-            // but moves it from the legacy key to the bound profile would otherwise
-            // leave `/context` naming the old source until the next measurement.
-            window.windowOverrideOrigin !== last?.windowOverrideOrigin ||
-            this.deps.getModelInfo().contextWindowSource !== last?.windowSource)
-            this.dirty = true;
-    }
-    measureAndPublish(lastUsage) {
-        const pressure = this.compute(lastUsage);
-        const messages = this.deps.getMessages();
-        this.publishedLength = messages.length;
-        this.publishedLast = messages[messages.length - 1];
-        this.publishedPrompt = this.readSystemPrompt();
-        this.publishedVersion = this.deps.getRequestVersion?.() ?? 0;
-        this.last = pressure;
-        this.dirty = false;
-        this.publish(pressure);
-        return pressure;
-    }
-    compute(lastUsage) {
-        const window = this.resolveWindow();
-        return computePressure({
-            ...(lastUsage ? { lastUsage } : {}),
-            messages: this.deps.getMessages(),
-            systemPrompt: this.readSystemPrompt(),
-            contextWindow: window.contextWindow,
-            windowSource: this.deps.getModelInfo().contextWindowSource,
-            windowKnown: window.windowKnown,
-            windowOverridden: window.windowOverridden,
-            ...(window.windowOverrideOrigin !== undefined
-                ? { windowOverrideOrigin: window.windowOverrideOrigin }
-                : {}),
-            ...(this.estimateOffset !== undefined ? { estimateOffset: this.estimateOffset } : {}),
-            ...(this.measuredPrefixLength !== undefined
-                ? { measuredPrefixLength: this.measuredPrefixLength }
-                : {}),
-        });
-    }
-    /**
-     * 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.
-     */
-    resolveWindow() {
-        const override = this.deps.getWindowOverride();
-        if (override !== null && Number.isFinite(override) && override > 0) {
-            // ORIGIN ONLY RIDES THE OVERRIDE BRANCH: the AUTO branch names its own
-            // source through `getModelInfo().contextWindowSource`, and the two must
-            // never both claim the denominator (profile-context-window §6.1).
-            const origin = this.deps.getWindowOverrideOrigin?.();
-            return { contextWindow: override, windowKnown: true, windowOverridden: true,
-                ...(origin !== undefined ? { windowOverrideOrigin: origin } : {}) };
-        }
-        return {
-            contextWindow: this.deps.getModelInfo().contextWindow,
-            windowKnown: this.deps.isWindowKnown(),
-            windowOverridden: false,
-        };
-    }
-    readSystemPrompt() {
-        return this.deps.getSystemPrompt();
-    }
-    publish(pressure) {
-        if (this.listeners.size === 0)
-            return;
-        const usage = toContextUsage(pressure);
-        for (const listener of [...this.listeners]) {
-            try {
-                listener(usage);
-            }
-            catch {
-                // One bad subscriber must not take the run down with it - the rule
-                // `CompactionWiring.emit` and `TeamRuntime.emit` both already state.
-            }
-        }
-    }
-}

package/dist/compaction/pressure.d.ts

@@ -1,163 +0,0 @@
-/**
- * Context occupancy and the trigger (context-auto-compaction §3.4).
- *
- * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
- *
- * PURE. No clock, no config read, no I/O - every input arrives as an argument,
- * which is what lets the trigger and the status-bar gauge share one function and
- * be tested without a live session.
- */
-import { type Message, type TokenUsage } from '@aragon-agent/core';
-import type { Pressure } from './types.js';
-/**
- * How much of the window the conversation occupies, from ONE reported usage.
- *
- * THE CACHE TERMS ARE NOT DECORATION. Anthropic's `message_start` reports
- * `input_tokens` EXCLUDING cached tokens and puts them in
- * `cache_read_input_tokens` / `cache_creation_input_tokens`. This CLI never sends
- * `cache_control`, so on a direct connection they are absent and the sum is
- * unchanged - but any gateway or proxy that caches on the user's behalf makes
- * them non-zero, and the status bar's old formula
- * (`usage.inputTokens + usage.outputTokens`) silently UNDER-reports occupancy for
- * exactly those users. That is a live, pre-existing defect in the number this
- * feature triggers on.
- *
- * THIS SUM IS ONLY VALID FOR *ADDITIVE* CACHE FIELDS, AND THAT IS A PROVIDER-SIDE
- * INVARIANT RATHER THAN A PROPERTY OF `TokenUsage` (C-14 / P1-10). It holds today
- * because exactly one adapter writes those fields: `openai.ts` sets
- * `inputTokens = prompt_tokens` and `google.ts` sets it from `promptTokenCount`,
- * and NEITHER ever mentions `cacheReadTokens` / `cacheWriteTokens`. OpenAI's
- * `prompt_tokens` ALREADY INCLUDES cached tokens, so mapping
- * `prompt_tokens_details.cached_tokens` onto the existing field - a change that
- * reads as a pure improvement and would sail through review - turns this into a
- * double-count and fires compaction early on every OpenAI session, with the gauge
- * agreeing with it and nothing reporting a fault. A provider that reports an
- * INCLUSIVE total must add a DIFFERENTLY NAMED field. `compaction-pressure.test.ts`
- * scans the adapters so the trap fails loudly at the moment someone opens it.
- *
- * THE GAUGE AND THE TRIGGER MUST READ THIS SAME FUNCTION (R-11 / AC-3). If they
- * diverge, a user watching 78 % on the status bar sees compaction fire, concludes
- * the feature is broken, and turns it off.
- */
-export declare function occupiedTokens(usage: TokenUsage): number;
-/**
- * Whether a usage measured ANYTHING on the input side
- * (context-usage-zero-input-tokens B).
- *
- * THE EMPTY MEASUREMENT THIS EXISTS FOR. A turn that billed output tokens
- * while reporting inputTokens 0 AND no cache terms did not measure the
- * request - no real request is free of input. Anthropic-COMPATIBLE relays
- * emit exactly this shape (bigmodel on every turn, Kimi intermittently),
- * and the meter used to arm its measured branch with it: occupancy collapsed
- * to the turn's own outputTokens, the `~` honesty marker vanished with
- * `source: 'usage'`, and the trigger - which reads the same number - never
- * fired. The defense is to not trust such a usage as a measurement.
- *
- * THE CACHE TERMS ARE PART OF THE INPUT SIDE, DELIBERATELY. Anthropic's real
- * `input_tokens` EXCLUDES cached tokens, so a deeply cached turn reports a
- * tiny `input_tokens` next to a huge `cache_read_input_tokens`. That IS a
- * valid measurement (C-14), and judging on `inputTokens === 0` alone would
- * reject it and strand a correct gauge on the estimator.
- *
- * `outputTokens > 0` separates "the stream ran, billed output, and disclosed
- * no input" from a degenerate all-zero usage, which the reviewed predicate
- * deliberately does not speak for.
- *
- * SINGLE AUTHORITY. The meter consumes this, and any future observability
- * hint (fix C) must too: two inline copies of "did the gateway disclose
- * input" would drift apart exactly the way the gauge and the trigger once
- * could (R-11).
- */
-export declare function isInputSideUnmeasured(usage: TokenUsage): boolean;
-/**
- * The calibration offset for this turn (D-23 / P1-11).
- *
- * Clamped at 0: a NEGATIVE offset would mean the estimator over-counted, which
- * is possible for a tool-free session on a verbose model, and applying it would
- * make the fallback read LOWER than the raw estimate - moving the one number
- * that is already biased low further in the wrong direction.
- */
-export declare function computeEstimateOffset(usage: TokenUsage, messages: readonly Message[], systemPrompt: string): number;
-export interface PressureInput {
-    windowSource?: Pressure['windowSource'];
-    /** Authoritative usage of the last completed turn, or `undefined` (§3.4.2). */
-    lastUsage?: TokenUsage;
-    messages: readonly Message[];
-    systemPrompt: string;
-    contextWindow: number;
-    /** False when the window is `buildRuntimeModel`'s 128k placeholder. */
-    windowKnown: boolean;
-    /**
-     * Whether `contextWindow` came from the user's `contextWindow` override
-     * (context-usage-gauge-accuracy I-6). Defaults to `false`, so every existing
-     * construction site is unchanged and the arithmetic below is untouched.
-     */
-    windowOverridden?: boolean;
-    /**
-     * Which override surface supplied `contextWindow` (profile-context-window).
-     * PURE PASS-THROUGH like `windowOverridden` - the arithmetic below never
-     * reads it; it only travels with the number so `/context` can name the
-     * source honestly.
-     */
-    windowOverrideOrigin?: Pressure['windowOverrideOrigin'];
-    /** Carried from the last `turn_end`; applied to every ESTIMATED figure. */
-    estimateOffset?: number;
-    /**
-     * The history LENGTH the measurement in `lastUsage` covered - i.e.
-     * `messages.length` at the `turn_end` that produced it, BEFORE the assistant
-     * message was pushed.
-     *
-     * `undefined` DISABLES THE DELTA ENTIRELY and reproduces round 1's behaviour
-     * exactly, which is what makes a missed invalidation cost accuracy rather than
-     * correctness.
-     */
-    measuredPrefixLength?: number;
-}
-/**
- * Tokens appended to the history since the measurement that produced `lastUsage`
- * (context-auto-compaction-hardening §3.2.2 / W1).
- *
- * `+ 1` SKIPS THE ASSISTANT MESSAGE, and that is not an off-by-one to tidy away:
- * `turn_end` is emitted BEFORE the push (`agent-loop.ts:478` / `:497`, and
- * `Agent.emit` is synchronous), so the message at index `measuredPrefixLength` is
- * the assistant turn whose cost is ALREADY inside `usage.outputTokens`. Counting
- * it again double-charges every turn.
- *
- * NO `estimateOffset` IS APPLIED HERE. That offset is the systematic difference
- * between what `estimatePromptTokens` counts and what the provider bills for a
- * WHOLE REQUEST - chiefly the tool schemas, which are sent once per request and
- * are already inside the measured base. It is a per-request constant, not a
- * per-message rate; adding it to a slice would inflate occupancy by several
- * thousand tokens on every turn and fire compaction early on short
- * conversations.
- *
- * BOUNDS-CHECKED RATHER THAN TRUSTED. If the recorded prefix no longer indexes
- * this array - a `/clear`, a `/resume`, a splice whose invalidation call was
- * missed - the delta is 0 and the function degrades to round 1's number.
- */
-export declare function estimateAppendedTokens(messages: readonly Message[], measuredPrefixLength: number | undefined): number;
-/**
- * THE ONE RULE FOR "PART OF THIS NUMBER IS A GUESS" (§6.3).
- *
- * `Pressure.source` deliberately keeps two members: it answers "where did the
- * BASE come from", and a third member would force every existing consumer of the
- * union to be revisited for a distinction none of them acts on. The `~` question
- * is this function, and it has one test.
- */
-export declare function isApproximate(p: Pressure): boolean;
-/**
- * Occupancy right now, measured when there is a measurement and calibrated when
- * there is not.
- *
- * `source` is CARRIED, never re-derived, and it reaches the UI: the status bar
- * already renders a leading `~` when the window is unknown, and this widens that
- * to "the NUMBER is approximate too". Honesty about a guess is cheaper than a
- * support thread about a wrong percentage.
- */
-export declare function computePressure(input: PressureInput): Pressure;
-/** Only actual occupancy authorizes automatic compaction. */
-export declare function shouldCompactAt(p: Pressure, threshold: number): boolean;
-/** Capacity helper retained for the standalone tail-budget API, never a trigger. */
-export declare function requiredHeadroom(req: {
-    maxOutputTokens: number;
-}): number;