@aragon-agent/cli 0.6.47 → 0.6.48

package/dist/compaction/pressure.js

@@ -1,199 +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 { CONTEXT_SAFETY_MARGIN_TOKENS, THINKING_HEADROOM_TOKENS, estimatePromptTokens, } from '@aragon-agent/core';
-/**
- * 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 function occupiedTokens(usage) {
-    return (usage.inputTokens +
-        (usage.cacheReadTokens ?? 0) +
-        (usage.cacheWriteTokens ?? 0) +
-        usage.outputTokens);
-}
-/**
- * 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 function isInputSideUnmeasured(usage) {
-    const inputSide = usage.inputTokens + (usage.cacheReadTokens ?? 0) + (usage.cacheWriteTokens ?? 0);
-    return inputSide === 0 && usage.outputTokens > 0;
-}
-/**
- * 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 function computeEstimateOffset(usage, messages, systemPrompt) {
-    const measured = occupiedTokens(usage);
-    const estimated = estimatePromptTokens(messages, systemPrompt);
-    return Math.max(0, measured - estimated);
-}
-/**
- * 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 function estimateAppendedTokens(messages, measuredPrefixLength) {
-    if (measuredPrefixLength === undefined)
-        return 0;
-    const start = measuredPrefixLength + 1;
-    if (start < 0 || start >= messages.length)
-        return 0;
-    return estimatePromptTokens(messages.slice(start));
-}
-/**
- * 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 function isApproximate(p) {
-    return p.source === 'estimate' || p.deltaTokens > 0;
-}
-/**
- * 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 function computePressure(input) {
-    const window = input.contextWindow > 0 ? input.contextWindow : 0;
-    let occupied;
-    let source;
-    let deltaTokens = 0;
-    if (input.lastUsage) {
-        // THE MEASURED FIGURE STAYS AUTHORITATIVE FOR WHAT IT COVERS, and only the
-        // messages appended since are estimated (W1 / DH-1). Mixing two units is the
-        // trap D-23 warned about; this does not mix them, it adds a second term for
-        // a range the first one demonstrably does not describe.
-        const base = occupiedTokens(input.lastUsage);
-        deltaTokens = estimateAppendedTokens(input.messages, input.measuredPrefixLength);
-        occupied = base + deltaTokens;
-        source = 'usage';
-    }
-    else {
-        // Before the first turn_end there is no calibration. Keep the estimate
-        // explicit: output reservations never authorize automatic compaction.
-        const raw = estimatePromptTokens(input.messages, input.systemPrompt);
-        occupied = raw + (input.estimateOffset ?? 0);
-        source = 'estimate';
-    }
-    const ratio = window > 0 ? Math.max(0, Math.min(1, occupied / window)) : 0;
-    return {
-        occupied,
-        ...(input.windowSource ? { windowSource: input.windowSource } : {}),
-        contextWindow: window,
-        ratio,
-        headroom: Math.max(0, window - occupied),
-        source,
-        windowKnown: input.windowKnown,
-        // PURE PASS-THROUGH. This function's arithmetic is unchanged by
-        // context-usage-gauge-accuracy; the flag only travels with the number so
-        // `/context` can name the denominator's source (I-6).
-        windowOverridden: input.windowOverridden ?? false,
-        // CONDITIONAL SPREAD: with no origin there is no KEY, keeping a
-        // feature-off Pressure byte-identical to the pre-feature one (I-6).
-        ...(input.windowOverrideOrigin !== undefined
-            ? { windowOverrideOrigin: input.windowOverrideOrigin }
-            : {}),
-        ...(input.estimateOffset !== undefined ? { estimateOffset: input.estimateOffset } : {}),
-        deltaTokens,
-    };
-}
-/** Only actual occupancy authorizes automatic compaction. */
-export function shouldCompactAt(p, threshold) {
-    if (!Number.isFinite(p.occupied) || p.occupied < 0)
-        return false;
-    if (!Number.isFinite(p.contextWindow) || p.contextWindow <= 0)
-        return false;
-    if (!Number.isFinite(threshold) || threshold < 0.5 || threshold > 0.95)
-        return false;
-    return p.occupied / p.contextWindow >= threshold;
-}
-/** Capacity helper retained for the standalone tail-budget API, never a trigger. */
-export function requiredHeadroom(req) {
-    return req.maxOutputTokens + THINKING_HEADROOM_TOKENS + CONTEXT_SAFETY_MARGIN_TOKENS;
-}

package/dist/compaction/reason-text.d.ts

@@ -1,36 +0,0 @@
-/**
- * Human wording for compaction outcomes (context-compaction-never-fires C).
- *
- * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope
- * (`glyphs.test.ts::inScope`), so every glyph the card draws comes from
- * `pickGlyphs` and nothing here may carry a non-ASCII byte.
- *
- * WHY THIS MODULE EXISTS AT ALL. The card used to print the raw rejection code
- * (`context not compacted #4: digest_budget_exceeded: $.digest`), which names the
- * internal gate and tells the user nothing they can act on. A decline is a
- * QUESTION ("why, and what do I do now"), so each code gets one phrase and - for
- * the ones a user can act on - one remedy.
- *
- * IT IS ALSO THE SELF-DISABLE NOTICE'S SOURCE. The one line that says
- * auto-compaction has paused reads the same phrase, so the card and the toast
- * cannot describe one failure two ways.
- */
-import type { CompactionPhase } from './types.js';
-/** One phrase plus, where it helps, the thing the user can do about it. */
-export interface ReasonText {
-    /** What happened, in one clause. Never contains the raw code. */
-    text: string;
-    /** The remedy, or `undefined` when there is nothing to offer. */
-    action?: string;
-}
-/**
- * A phrase for a rejection code, falling back to the code itself.
- *
- * THE FALLBACK IS THE RAW CODE, deliberately: a new gate nobody wrote wording for
- * must still say SOMETHING specific on the card, and an invented sentence would
- * be worse than a code the next reviewer can grep.
- */
-export declare function describeCompactionReason(reason: string): ReasonText;
-/** The card's one-line reason, with the remedy appended when there is one. */
-export declare function compactionReasonLine(reason: string): string;
-export declare function compactionPhaseLabel(phase: CompactionPhase): string;

package/dist/compaction/reason-text.js

@@ -1,78 +0,0 @@
-const REASONS = {
-    nothing_to_drop: {
-        text: 'no safe cut - this run has too few user turns to keep',
-        action: 'keep talking, or lower /compact keep',
-    },
-    digest_budget_exceeded: {
-        text: 'the summary input was too large for one call',
-        action: 'retry - the middle is elided now',
-    },
-    summarizer_window_exceeded: {
-        text: 'the summary request does not fit the summarizer window',
-        action: 'pick a summarizer with a larger window',
-    },
-    protected_memory_too_large: {
-        text: 'the task memory does not fit its protection budget',
-        action: 'start a fresh conversation',
-    },
-    invalid_memory_delta: {
-        text: 'the summarizer returned an unusable memory delta',
-        action: 'retry',
-    },
-    empty_memory_delta: {
-        text: 'the summarizer returned an empty memory delta',
-        action: 'retry',
-    },
-    no_token_reclaim: {
-        text: 'the summary would not have reclaimed any tokens',
-    },
-    timeout: { text: 'the summarizer timed out', action: 'retry' },
-    no_summarizer_model: {
-        text: 'no summarizer model resolves',
-        action: 'set a model or add a provider key',
-    },
-    no_api_key: { text: 'the summarizer provider has no API key' },
-    already_running: { text: 'another compaction is already running' },
-    invalid_prior_memory: {
-        text: 'the existing task memory does not match this history',
-        action: 'start a fresh conversation',
-    },
-    invalid_history: { text: 'this history cannot be split safely' },
-    protected_multimodal_tail: {
-        text: 'an image in the middle of this history would have to be dropped',
-    },
-    insufficient_reclaim: {
-        text: 'the splice freed too little to stay below the threshold',
-    },
-    disabled: { text: 'auto-compaction is off for this session', action: '/compact on' },
-    cancelled: { text: 'cancelled' },
-    aborted: { text: 'cancelled' },
-    stale_history: { text: 'the history changed while the summary was running' },
-    adoption_failed: { text: 'the compacted history could not be adopted' },
-};
-/**
- * A phrase for a rejection code, falling back to the code itself.
- *
- * THE FALLBACK IS THE RAW CODE, deliberately: a new gate nobody wrote wording for
- * must still say SOMETHING specific on the card, and an invented sentence would
- * be worse than a code the next reviewer can grep.
- */
-export function describeCompactionReason(reason) {
-    const code = reason.split(':', 1)[0].trim();
-    return REASONS[code] ?? { text: reason };
-}
-/** The card's one-line reason, with the remedy appended when there is one. */
-export function compactionReasonLine(reason) {
-    const { text, action } = describeCompactionReason(reason);
-    return action ? `${text} (${action})` : text;
-}
-const PHASES = {
-    planning: 'planning the cut',
-    digesting: 'building the digest',
-    summarizing: 'summarizing',
-    validating: 'validating the summary',
-    applying: 'applying',
-};
-export function compactionPhaseLabel(phase) {
-    return PHASES[phase];
-}

package/dist/compaction/types.d.ts

@@ -1,360 +0,0 @@
-/**
- * CLI-local compaction shapes (context-auto-compaction §5.2 / §3.4.2).
- *
- * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
- *
- * A CLI-LOCAL EVENT STREAM, like `FastEvent` / `TeamEvent` / `TodoEvent`, for
- * the reason each of those records: core's `AgentEvent` union is a public
- * contract and must not learn host shapes.
- *
- * NOTE THE ASYMMETRY WITH CORE. Core emits the two ENGINE events because the
- * engine is what performs the splice and decides `applied`; the CLI emits the
- * richer ones because only the CLI knows the model name, the price and the
- * session totals.
- *
- * THIS STREAM IS THE SOLE SOURCE OF REDUCER ACTIONS (D-20 / P1-6), and
- * `reduceEvent` gains NO cases for `compaction_start` / `compaction_end`. One
- * compaction arriving through two channels is two transcript cards and a doubled
- * `tokensReclaimed`; `reduceEvent`'s `default: return []` is already exactly
- * right for the two core events, which makes "one authority" also the smallest
- * possible change.
- */
-import type { ModelRef, TokenUsage } from '@aragon-agent/core';
-import type { ContextWindowOrigin } from '../config/schema.js';
-/** Billing belongs to the actual call, including fallback and late responses. */
-export interface CompactionBilling {
-    modelRef?: ModelRef;
-    costUsd?: number;
-    pricingUnknown?: boolean;
-}
-/**
- * `relieved` MEANS THE TAIL WAS CLIPPED AND NOTHING WAS DROPPED (hardening
- * RV-5) — the `plan === null` recovery of §3.3.3.
- *
- * IT EXISTS ONLY HERE. The port still reports `'truncated'` for it (DH-5),
- * because the engine's question is narrower: "was this history reduced without a
- * summary", and the answer is yes.
- *
- * WITHOUT IT THE CARD LIES. `detailLine` renders
- * `summarized ${before - after} messages with ${model}` for `'summarized'`, and
- * relief drops NO messages — so a compaction in which no model was called would
- * render "summarized 0 messages with claude-haiku-4-5", in the rare and alarming
- * case the user most needs to read correctly.
- *
- * ANY NEW `switch` ON THIS UNION MUST PAIR ITS BRANCHES. TypeScript finds the
- * exhaustive switches; it does not find an `else` that meant `'summarized'`.
- */
-export type CompactionMode = 'summarized' | 'truncated' | 'relieved' | 'none';
-/**
- * `manual` exists ONLY here, never in core.
- *
- * The engine's `CompactionTrigger` is `pressure | overflow`, because those are
- * the two the LOOP can originate. A `/compact` while running is queued and then
- * arrives at the loop as an ordinary `pressure` checkpoint, so the distinction
- * is a host-side fact about WHY the flag was set - which is exactly the kind of
- * thing a CLI-local type is for.
- */
-export type CompactionUiTrigger = 'pressure' | 'overflow' | 'manual';
-/**
- * Where one attempt currently is, so "compacting context" can also say WHAT it is
- * doing for the forty-five seconds it is on screen.
- *
- * IT EXISTS BECAUSE THE GATES WERE INVISIBLE (context-compaction-never-fires
- * RC-3). Planning and digesting both run BEFORE any model call, and both used to
- * be able to reject while the only surface said `Context 95%` and nothing else.
- * A phase is the CLI's answer to "is this stuck, or merely slow", and it is
- * CLI-LOCAL for the reason the whole stream is: the engine has no phases, only a
- * splice.
- *
- * THERE IS NO `settled` MEMBER, deliberately: the settle is already the
- * `compaction_end` record. A phase restating it would give the card two ways to
- * learn one fact, and the extra phase would race the record whenever the engine's
- * verdict comes back first.
- */
-export type CompactionPhase = 'planning' | 'digesting' | 'summarizing' | 'validating' | 'applying';
-/** Whether a figure was measured by the provider or estimated by us. */
-export type PressureSource = 'usage' | 'estimate';
-/** The exact occupancy evidence at the compaction checkpoint. */
-export interface CompactionDecision {
-    occupied: number;
-    contextWindow: number;
-    threshold: number;
-    source: PressureSource;
-    deltaTokens: number;
-}
-export interface Pressure {
-    /**
-     * `user` means the CLI's model-windows.json supplied the denominator - a
-     * hand-typed window for a model no table knows. It outranks `api` and
-     * `catalog` in `getModelInfoFor` precisely because the user asserted it.
-     */
-    windowSource?: 'api' | 'catalog' | 'fallback' | 'user';
-    occupied: number;
-    contextWindow: number;
-    /** `occupied / contextWindow`, clamped to [0, 1]. */
-    ratio: number;
-    /** `contextWindow - occupied`, floored at 0. */
-    headroom: number;
-    source: PressureSource;
-    /** False when the window came from `buildRuntimeModel`'s 128k placeholder. */
-    windowKnown: boolean;
-    /**
-     * Whether the denominator came from the user's `contextWindow` override
-     * (context-usage-gauge-accuracy I-6).
-     *
-     * SEPARATE FROM `windowKnown` RATHER THAN FOLDED INTO IT. An override makes
-     * the window KNOWN - the user asserted it, so the `~` has no business staying
-     * on the percentage - but `/context` still has to be able to say WHO supplied
-     * the number. Collapsing the two into one boolean makes "found in the model
-     * table" and "typed by hand" indistinguishable in the report, and the second
-     * one being wrong is exactly the case that most needs to be visible.
-     */
-    windowOverridden: boolean;
-    /**
-     * WHICH override surface supplied the denominator (profile-context-window
-     * §5.2): env / legacy top-level key / the profile bound as Main. Optional
-     * and PURE PASS-THROUGH - present only when `windowOverridden` is true, and
-     * `undefined` there means "config", the pre-feature answer. The arithmetic
-     * never reads it; only `/context`'s window line does.
-     */
-    windowOverrideOrigin?: ContextWindowOrigin;
-    /**
-     * `occupiedTokens(lastUsage) - estimateOf(the history that produced it)`,
-     * clamped to `>= 0`, or `undefined` before the first `turn_end`.
-     *
-     * THE SYSTEMATIC PART OF THE ESTIMATOR'S ERROR (D-23 / P1-11), chiefly the
-     * TOOL SCHEMAS. `estimatePromptTokens` counts the system prompt and the message
-     * bodies and NOTHING ELSE, while the loop also sends `tools: toolDefs` and the
-     * provider's `input_tokens` includes them - several thousand tokens for this
-     * CLI's toolset. So the estimate is biased LOW, always, in the one direction
-     * that hurts: the resumed 180k-token session is exactly where the estimate is
-     * used, and it reads lower than the truth.
-     *
-     * One shared FUNCTION is not the same as one shared UNIT. Everywhere an
-     * estimated figure is compared against a threshold or shown to a user it is
-     * `estimate + (estimateOffset ?? 0)`.
-     */
-    estimateOffset?: number;
-    /**
-     * Tokens estimated for messages APPENDED AFTER the measurement in `lastUsage`
-     * (hardening §3.2 / W1). `0` on the estimate branch, and `0` whenever the
-     * recorded prefix is unusable.
-     *
-     * ALWAYS PRESENT, never optional, so `isApproximate` is a total function and a
-     * consumer cannot forget the `?? 0`. `> 0` is what makes the measured branch
-     * approximate: the base is the provider's own number for a request that really
-     * happened, and this is a guess about messages no request has yet carried.
-     */
-    deltaTokens: number;
-}
-/**
- * The ONE occupancy projection the status bar and `/context` read
- * (context-usage-gauge-accuracy §4.1).
- *
- * DELIBERATELY CARRIES NO TIMESTAMP. Its only consumer is the reducer's identity
- * short-circuit (§5.2), and a field that changes on every tick would make that
- * short-circuit never hold - turning a permanently visible row into a 2.5 Hz
- * re-render source and pushing the render governor up its ladder for nothing.
- *
- * `Pressure` is the compaction subsystem's shape and carries a headroom and a
- * ratio the UI does not want; this is the projection of it that crosses into
- * view state, and `toContextUsage` in `meter.ts` is the ONLY converter.
- */
-export interface ContextUsageSnapshot {
-    windowSource?: Pressure['windowSource'];
-    /** Occupied tokens (measured, plus an estimate of anything appended since). */
-    occupied: number;
-    /** The denominator actually used. */
-    window: number;
-    /** `occupied / window` as a percentage, clamped to [0, 100] and rounded. */
-    pct: number;
-    /** Where the BASE came from. */
-    source: PressureSource;
-    /** How much of `occupied` is an estimate of appended messages; `> 0` means approximate. */
-    deltaTokens: number;
-    /** Whether the denominator is trustworthy (in the model table, or overridden). */
-    windowKnown: boolean;
-    /** Whether the denominator came from the user's `contextWindow` (I-6). */
-    windowOverridden: boolean;
-    /** Which override surface named the denominator; see `Pressure` (pass-through). */
-    windowOverrideOrigin?: ContextWindowOrigin;
-}
-/** One compaction, in whatever state it reached. Rendered by `CompactionCard`. */
-export interface CompactionRecord {
-    decision?: CompactionDecision;
-    memoryVersion?: 2;
-    /** 1-based within the session, so the card can name itself. */
-    index: number;
-    trigger: CompactionUiTrigger;
-    mode: CompactionMode;
-    applied: boolean;
-    reason?: string;
-    messagesBefore: number;
-    messagesAfter: number;
-    tokensBefore: number;
-    tokensAfter: number;
-    summary?: string;
-    model: string;
-    durationMs: number;
-    /** What the summarization call itself spent. */
-    usage?: TokenUsage;
-    /** Set when an overflow attempt halved `keepRecentTurns` for itself (D-24). */
-    keepRecentTurnsUsed?: number;
-    /**
-     * Set when `planCompaction` had to relax `keepRecentTurns` to find a cut
-     * (context-compaction-never-fires B).
-     *
-     * DISCLOSED ON THE CARD, never silent: the relaxation trades "the last N turns
-     * are verbatim" for "compaction happens at all", and a user who is not told
-     * which side they got cannot tell a lossless compaction from a lossy one.
-     * `retainedTurns` and `retainedMessages` are what actually survived, so the card
-     * can state all three numbers instead of implying one.
-     */
-    keepRelaxed?: boolean;
-    retainedTurns?: number;
-    /**
-     * How many MESSAGES the relaxed cut left verbatim.
-     *
-     * `retainedTurns` COUNTS USER TURNS, and in the sessions this fix exists for - one
-     * prompt followed by a hundred tool calls - that number is zero even though forty
-     * messages survived word for word. A card reading "kept 0 recent turns" at that
-     * moment says the opposite of what happened, so both numbers are recorded.
-     */
-    retainedMessages?: number;
-    /**
-     * Messages left OUT of the digest text and therefore not quotable by the
-     * summarizer (context-compaction-never-fires A1).
-     *
-     * The elision is LOUD in three places: the digest text itself carries an
-     * `[elided ...]` marker, this field puts the count on the card, and the elided
-     * ids never enter the source map, so a delta citing one is rejected.
-     */
-    elidedMessages?: number;
-    /**
-     * Present ONLY when tail relief fired (hardening §3.3.4 / W2).
-     *
-     * A bounded, ANNOUNCED data loss inside the turns the run is about to continue
-     * from, so it is disclosed on the card, in `/compact status`, on the JSON
-     * stream and in the archive — the honesty rule `truncated` already follows.
-     */
-    tailRelief?: {
-        messages: number;
-        charsRemoved: number;
-    };
-    /**
-     * The archive file this compaction was written to, for `/compact show`
-     * (hardening §3.5 / W4). Absent when `compaction.archive` is off, and absent
-     * when the write failed — a best-effort artefact never claims to exist.
-     */
-    archivePath?: string;
-}
-/**
- * WHAT DELIBERATELY DOES NOT LIVE ON `CompactionRecord` (hardening RV-3): the
- * dropped `Message[]`.
- *
- * This record is dispatched into the reducer (`App.tsx`'s `compaction_end` case)
- * and retained in view state for the transcript card's lifetime. Hanging a
- * megabyte-scale array off it would park the compacted history in React state
- * and drag it through every subsequent render — an archive feature that creates
- * the leak it audits. The messages travel on `Compactor.takeLastDropped()`
- * instead, which never enters the event stream.
- */
-/** Everything `/compact status`, the chip and the settings row read. */
-export interface CompactionSnapshot {
-    /** Sum of known per-call costs; never reprice accumulated usage with a new model. */
-    costUsd?: number;
-    /** Registered AND enabled AND a summarizer model resolves. */
-    live: boolean;
-    /** The summarizer's model id, or `''`. */
-    model: string;
-    /**
-     * How many compactions ANNOUNCED themselves, i.e. how many cards the user saw.
-     *
-     * IT COUNTS ATTEMPTS, NOT SPLICES (context-compaction-never-fires C). Before
-     * this change only attempts that committed to work announced, so this was
-     * "compactions that ran"; now every attempt opens a card - including the ones
-     * that decline at the planner or the digest - because a silent decline is
-     * indistinguishable from a dead feature, which is the bug this feature shipped
-     * with. `applied` below is the other half, and `/compact status` prints both.
-     */
-    compactions: number;
-    /**
-     * How many of those attempts actually replaced the history.
-     *
-     * OPTIONAL SO EVERY EXISTING CONSTRUCTION SITE STAYS UNTOUCHED. Absent means
-     * "not reported", which `/compact status` renders exactly as the pre-change
-     * wording did.
-     */
-    applied?: number;
-    /**
-     * How many `pressure` checkpoints declined BEFORE committing to any work
-     * (quiet-noop D-9 / P1-2).
-     *
-     * OPTIONAL SO EVERY EXISTING CONSTRUCTION SITE STAYS UNTOUCHED, and rendered
-     * by `/compact status` only when non-zero — a healthy session must not read
-     * `(0 checkpoints declined)`. This is the one human surface that still speaks
-     * about a decline after the transcript went quiet, which is what keeps
-     * `context-auto-compaction` §6.5's "guaranteed reporting surface" promise true.
-     */
-    declined?: number;
-    /** Sum of `(tokensBefore - tokensAfter)` over applied compactions. */
-    tokensReclaimed: number;
-    /** What compaction itself has spent this session. */
-    usage: TokenUsage;
-    /**
-     * CARRIED, NEVER RE-DERIVED (the C-11 / RV-4 lesson from `fast-model-tier`).
-     * An unknown model priced at `$0.00` would make the feature look free while it
-     * spends money - and here the DEFAULT summarizer is the session's own model.
-     */
-    pricingUnknown: boolean;
-    inFlight: boolean;
-    selfDisabled: boolean;
-    selfDisabledReason?: string;
-    /** How many times this history has been compacted, from the block's `generation`. */
-    generation: number;
-    pressure: Pressure;
-}
-/**
- * THE COMPACTION EVENT STREAM.
- *
- * EVERY ATTEMPT ANNOUNCES ITSELF (context-compaction-never-fires C, which
- * REVERSES quiet-noop §3.1). A `pressure` compaction used to reach
- * `compaction_start` only after it committed to paid work, so an attempt that
- * declined at the planner (`nothing_to_drop`) or at the digest budget produced
- * no card at all - and a user sitting at 95 % with a dead auto-compaction had no
- * way to learn that the feature was trying and failing 96 times. The card is now
- * opened at the entry of `compact()` and ALWAYS settled, so `#N` counts attempts
- * and the transcript carries one line per attempt, applied or not.
- *
- * WHY THE OLD DESIGN WAS DEFENSIBLE AND IS STILL WRONG. Its stated worry was a
- * red `context not compacted` card every two turns flooding the transcript. The
- * guards bound that to `stuckLimit` declines per run (`limits.ts`), and after
- * them the auto path self-disables and says so once - so the flood never
- * happens, while the silence happened every time.
- *
- * The pair is still BALANCED: every `compaction_start` is followed by exactly
- * one `compaction_end` (a `finally` in the engine guarantees the verdict, and
- * `settlePending` synthesizes a skeleton record when the compactor's own has not
- * arrived). `phase` events land BETWEEN them, in order, and only for the live
- * card.
- */
-export type CompactionEvent = {
-    type: 'compaction_start';
-    index: number;
-    trigger: CompactionUiTrigger;
-    model: string;
-} | {
-    type: 'compaction_end';
-    record: CompactionRecord;
-} | {
-    type: 'phase';
-    index: number;
-    phase: CompactionPhase;
-} | ({
-    type: 'usage';
-    usage: TokenUsage;
-} & CompactionBilling) | {
-    type: 'snapshot';
-    snapshot: CompactionSnapshot;
-};
-export type CompactionEventListener = (event: CompactionEvent) => void;