@aragon-agent/cli 0.6.2 → 0.6.4

package/dist/compaction/summary-prompt.js

@@ -0,0 +1,197 @@
+/**
+ * The summarizer's system prompt and the `<compacted_context>` splice
+ * (context-auto-compaction §3.6.4 / §3.6.5).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
+ *
+ * PURE. Every input arrives as an argument, so the block a session produced can
+ * be reconstructed from a bug report with one call.
+ */
+import { ANCHOR_TAG_CLOSE, ANCHOR_TAG_OPEN, ANCHOR_TRUNCATION_MARK, BLOCK_TAG_CLOSE, BLOCK_TAG_OPEN, COMPACTION_BLOCK_VERSION, COMPACTION_LIMITS, } from './limits.js';
+import { isPriorSummaryBlock } from './digest.js';
+/**
+ * The section skeleton the summary must fill.
+ *
+ * THE HEADINGS ARE PART OF THE CONTRACT, because the next model to read them is
+ * an LLM: a summary with predictable sections can be scanned for "what is still
+ * open" without re-reading the whole thing.
+ */
+export function buildSummarySystemPrompt(opts) {
+    const lines = [
+        'You are compacting a software-engineering conversation so the agent can keep working',
+        'after older messages are dropped from its context window.',
+        '',
+        'Write a record of the conversation below using EXACTLY these sections, in this order:',
+        '',
+        '## Task',
+        "The user's original goal, and any revision to it.",
+        '## Decisions',
+        'What was decided and why. One line each.',
+        '## Files',
+        'path -> what changed in it, or what is in it that matters.',
+        '## Facts',
+        'Commands, paths, APIs, identifiers and values discovered. Verbatim where exactness matters.',
+        '## Open',
+        'What remains to be done, in the order it should be done.',
+        '## Pitfalls',
+        'What was tried and did not work, so it is not tried again.',
+        '',
+        'Rules:',
+        `- Stay under ${opts.maxChars} characters in total.`,
+        '- Prefer verbatim identifiers, paths and commands over prose describing them.',
+        '- NEVER invent a fact the transcript does not contain. An empty section is correct',
+        '  when the transcript says nothing about it; write "(none)" under it.',
+        '- Write in the language of the conversation.',
+        '- Output the sections and nothing else. No preamble, no sign-off.',
+    ];
+    if (opts.hasPriorSummary) {
+        // WITHOUT THIS CLAUSE the second compaction is a model deciding, with no
+        // instruction either way, how much of a summary a summary needs - which is
+        // the mechanism by which flattened summaries decay into nothing over a long
+        // run (D-22 / R-14).
+        lines.push('', 'The transcript below OPENS WITH A `PRIOR SUMMARY` SECTION. That section is an', 'authoritative record of everything that came before it, produced by an earlier', 'compaction of this same conversation. MERGE IT AND CARRY IT FORWARD - do not', 're-condense it. Facts, file paths and pitfalls already recorded there are to be', 'reproduced, not paraphrased away, and anything it marks as incomplete stays marked.');
+    }
+    if (opts.instructions && opts.instructions.trim().length > 0) {
+        lines.push('', '## Focus', 'The user asked you to pay particular attention to the following. Keep everything', 'the sections above require, and be more detailed where it is relevant:', opts.instructions.trim());
+    }
+    return lines.join('\n');
+}
+/** The user message the summarization call sends: the digest, and nothing else. */
+export function buildSummaryUserMessage(digest, now) {
+    return { role: 'user', content: digest, timestamp: now };
+}
+function contentIsParts(content) {
+    return Array.isArray(content);
+}
+function firstText(content) {
+    if (typeof content === 'string')
+        return content;
+    return content.map((p) => (p.type === 'text' ? p.text : '[image]')).join('\n');
+}
+/**
+ * Recognize an anchor this feature produced on a previous pass.
+ *
+ * STRUCTURAL, NOT LENGTH-DEPENDENT (D-21 / P1-9). v1 of the design identified
+ * the anchor as "the first `user` message of the conversation" and chose between
+ * two shapes by length. Neither rule composes across repeated compactions,
+ * because after the first pass the first user message IS the compacted block:
+ * the merged shape promotes a SUMMARY to "the user's original task", and the
+ * standalone shape keeps the block as an anchor AND re-digests it. Neither
+ * failure raises anything, and both get worse every pass.
+ */
+export function isTaggedAnchor(message) {
+    if (message.role !== 'user')
+        return false;
+    return firstText(message.content).trimStart().startsWith(ANCHOR_TAG_OPEN);
+}
+/**
+ * Build (or carry through) the leading anchor.
+ *
+ * ALWAYS ITS OWN LEADING MESSAGE, AND ALWAYS STRUCTURALLY IDENTIFIABLE. A
+ * summarizer that is 90 % faithful is fine for the middle of a conversation and
+ * catastrophic for the sentence that says what the user wanted (D-6).
+ */
+export function buildAnchor(messages) {
+    const first = messages.find((m) => m.role === 'user');
+    if (!first)
+        return null;
+    // Already ours: carry it through byte-for-byte. This is what makes the rule
+    // idempotent across an unbounded number of compactions.
+    if (isTaggedAnchor(first))
+        return { message: first, shape: 'tagged' };
+    // A message carrying `ContentPart[]` may depend on an IMAGE, which no tag can
+    // wrap and no clip can preserve. It is kept byte-for-byte verbatim, and the
+    // block records `anchor="verbatim"` so the next pass recognizes it by position
+    // rather than by a tag it cannot carry.
+    if (contentIsParts(first.content)) {
+        return { message: first, shape: 'verbatim' };
+    }
+    const raw = first.content;
+    const clipped = raw.length > COMPACTION_LIMITS.anchorChars
+        ? `${raw.slice(0, COMPACTION_LIMITS.anchorChars)}${ANCHOR_TRUNCATION_MARK}`
+        : raw;
+    const message = {
+        role: 'user',
+        content: `${ANCHOR_TAG_OPEN}\n${clipped}\n${ANCHOR_TAG_CLOSE}`,
+        ...(first.timestamp !== undefined ? { timestamp: first.timestamp } : {}),
+    };
+    return { message, shape: 'tagged' };
+}
+/**
+ * How many leading messages are ALREADY structurally preserved, and must be
+ * carried through untouched rather than digested.
+ *
+ * This is `planCompaction`'s `protectedPrefix` (§3.6.2). The HOST computes it
+ * because it is the host that knows what an `<original_task>` message is; core
+ * stays free of any knowledge of the block format.
+ */
+export function countProtectedPrefix(messages) {
+    const first = messages[0];
+    if (!first)
+        return 0;
+    // Case 1 — a TAGGED anchor identifies itself. The block, if any, is next.
+    if (isTaggedAnchor(first)) {
+        return messages[1] && isPriorSummaryBlock(messages[1]) ? 2 : 1;
+    }
+    // Case 2 — a VERBATIM anchor is not self-identifying (no tag can wrap the image
+    // it exists to preserve), so it is recognized BY POSITION: a `user` message at
+    // index 0 followed IMMEDIATELY by our block. `messages[1]`, never `messages[n]`
+    // — reading the slot the anchor itself occupies is an off-by-one whose only
+    // symptom is that a verbatim-anchor session re-digests its own anchor and block
+    // on every subsequent compaction, which is the exact P1-9 decay this function
+    // exists to prevent, arriving through the back door.
+    if (first.role === 'user' && messages[1] && isPriorSummaryBlock(messages[1]))
+        return 2;
+    // Case 3 — no anchor of ours, but a block at the head anyway (a history hand-
+    // edited, or restored from a file this feature did not write).
+    if (isPriorSummaryBlock(first))
+        return 1;
+    return 0;
+}
+/** Read `generation="N"` off a prior block, so the next one can say `N + 1`. */
+export function readGeneration(messages) {
+    for (const message of messages) {
+        if (!isPriorSummaryBlock(message))
+            continue;
+        const text = firstText(message.content);
+        const match = /generation="(\d+)"/.exec(text);
+        if (match)
+            return Number.parseInt(match[1], 10);
+        return 1;
+    }
+    return 0;
+}
+/** The body used when the ladder ran out and there is no summary (§3.7 rung 3). */
+export function truncationBody(replaced) {
+    return (`${replaced} earlier ${replaced === 1 ? 'message was' : 'messages were'} dropped to free ` +
+        'context. Their content is not available. Do not assume anything about what they ' +
+        'contained; ask the user if you need it.');
+}
+/**
+ * The spliced block.
+ *
+ * A `user` MESSAGE, NEVER A FABRICATED ASSISTANT ONE (D-5). An assistant message
+ * claiming the model said something it did not is a lie the model will then act
+ * on, and it corrupts every subsequent turn. The XML tag is the same disclosure
+ * device `<fast_review>` and `<skill>` already use in this codebase, and the
+ * instruction line is what stops the model reading the block as the user ASKING
+ * for a summary.
+ */
+export function buildCompactedBlock(input) {
+    const body = input.summary.slice(0, COMPACTION_LIMITS.summaryMaxChars);
+    const header = `${BLOCK_TAG_OPEN} version="${COMPACTION_BLOCK_VERSION}" replaced="${input.replaced}" ` +
+        `turns="${input.turns}" anchor="${input.anchor}" generation="${input.generation}">`;
+    const intro = [
+        'The conversation above this point was compacted to free context. The following',
+        'is an accurate record of it. Continue the work from here; do not re-derive this',
+        'history, do not ask the user to repeat it, and do not apologise for the gap.',
+    ];
+    if (input.truncated) {
+        intro.push('', 'THE RECORD IS INCOMPLETE: summarization failed, so the dropped messages were not', 'summarized at all. Treat anything not stated below as unknown rather than absent.');
+    }
+    return {
+        role: 'user',
+        content: `${header}\n${intro.join('\n')}\n\n${body}\n${BLOCK_TAG_CLOSE}`,
+        timestamp: Date.now(),
+    };
+}

package/dist/compaction/tail-budget.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The tail-relief projection - what a retained tail may occupy, and whether it
+ * has to be clipped (context-auto-compaction-hardening §3.3.3 / W2).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
+ *
+ * ITS OWN MODULE BY A PRE-MADE DECISION, not an improvised split. The design's
+ * §7 records it in advance: "If `compactor.ts` approaches the guideline during
+ * implementation, the tail-relief projection block moves to
+ * `compaction/tail-budget.ts` - noted here so the decision is not improvised."
+ * It did (`CLAUDE.md` caps a source file at 1 000 lines), so it did.
+ *
+ * PURE APART FROM THE LOG SINK. Everything it needs arrives as an argument,
+ * which is what lets the projection be tested without standing up a `Compactor`.
+ */
+import { type Message, type TailReliefResult } from '@aragon-agent/core';
+/**
+ * What the whole history may occupy and still leave room for one reply.
+ *
+ * THE BLOCK ALLOWANCE IS NOT PADDING. On the `plan === null` path the
+ * `<compacted_context>` block has not been written when this is measured, so a
+ * budget with no room reserved for it would let the block push the relieved
+ * history straight back over.
+ */
+export declare function tailBudgetTokens(input: {
+    contextWindow: number;
+    maxOutputTokens: number;
+}): number;
+export interface TailReliefAttempt {
+    messages: readonly Message[];
+    /** Index the tail starts at; nothing before it is eligible. */
+    from: number;
+    systemPrompt: string;
+    budget: number;
+    /** W2 fires rarely; when it does it is the most interesting event in the session. */
+    log: (event: string, fields: Record<string, unknown>) => void;
+}
+/**
+ * Relieve the tail when - and ONLY when - the history is over budget.
+ * `null` means "it fits, or nothing was eligible".
+ *
+ * THE PROJECTION IS THE GATE. Relief is a real, bounded, announced data loss
+ * inside the turns the run is about to continue from, so it must never become a
+ * routine tidy-up: it runs only when the alternative is a request the provider
+ * cannot accept.
+ */
+export declare function attemptTailRelief(attempt: TailReliefAttempt): TailReliefResult | null;
+/** The shape `CompactionRecord.tailRelief` and the archive both carry. */
+export declare function reliefSummary(relief: TailReliefResult): {
+    messages: number;
+    charsRemoved: number;
+};

package/dist/compaction/tail-budget.js

@@ -0,0 +1,67 @@
+/**
+ * The tail-relief projection - what a retained tail may occupy, and whether it
+ * has to be clipped (context-auto-compaction-hardening §3.3.3 / W2).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
+ *
+ * ITS OWN MODULE BY A PRE-MADE DECISION, not an improvised split. The design's
+ * §7 records it in advance: "If `compactor.ts` approaches the guideline during
+ * implementation, the tail-relief projection block moves to
+ * `compaction/tail-budget.ts` - noted here so the decision is not improvised."
+ * It did (`CLAUDE.md` caps a source file at 1 000 lines), so it did.
+ *
+ * PURE APART FROM THE LOG SINK. Everything it needs arrives as an argument,
+ * which is what lets the projection be tested without standing up a `Compactor`.
+ */
+import { estimatePromptTokens, relieveTail, } from '@aragon-agent/core';
+import { COMPACTION_LIMITS, tailClipMarker } from './limits.js';
+import { requiredHeadroom } from './pressure.js';
+/**
+ * What the whole history may occupy and still leave room for one reply.
+ *
+ * THE BLOCK ALLOWANCE IS NOT PADDING. On the `plan === null` path the
+ * `<compacted_context>` block has not been written when this is measured, so a
+ * budget with no room reserved for it would let the block push the relieved
+ * history straight back over.
+ */
+export function tailBudgetTokens(input) {
+    return Math.max(0, input.contextWindow -
+        requiredHeadroom({ maxOutputTokens: input.maxOutputTokens }) -
+        COMPACTION_LIMITS.blockAllowanceTokens);
+}
+/**
+ * Relieve the tail when - and ONLY when - the history is over budget.
+ * `null` means "it fits, or nothing was eligible".
+ *
+ * THE PROJECTION IS THE GATE. Relief is a real, bounded, announced data loss
+ * inside the turns the run is about to continue from, so it must never become a
+ * routine tidy-up: it runs only when the alternative is a request the provider
+ * cannot accept.
+ */
+export function attemptTailRelief(attempt) {
+    if (attempt.budget <= 0)
+        return null;
+    const projected = estimatePromptTokens(attempt.messages, attempt.systemPrompt);
+    if (projected <= attempt.budget)
+        return null;
+    const relief = relieveTail(attempt.messages, {
+        from: attempt.from,
+        clipChars: COMPACTION_LIMITS.tailToolResultChars,
+        targetTokens: attempt.budget,
+        systemPrompt: attempt.systemPrompt,
+        marker: tailClipMarker,
+    });
+    if (relief.clippedMessages === 0)
+        return null;
+    attempt.log('compaction_tail_relief', {
+        clippedMessages: relief.clippedMessages,
+        charsRemoved: relief.charsRemoved,
+        projectedBefore: projected,
+        budget: attempt.budget,
+    });
+    return relief;
+}
+/** The shape `CompactionRecord.tailRelief` and the archive both carry. */
+export function reliefSummary(relief) {
+    return { messages: relief.clippedMessages, charsRemoved: relief.charsRemoved };
+}

package/dist/compaction/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * 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 { TokenUsage } from '@aragon-agent/core';
+/**
+ * `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';
+/** Whether a figure was measured by the provider or estimated by us. */
+export type PressureSource = 'usage' | 'estimate';
+export interface Pressure {
+    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;
+    /**
+     * `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;
+}
+/** One compaction, in whatever state it reached. Rendered by `CompactionCard`. */
+export interface CompactionRecord {
+    /** 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;
+    /**
+     * 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 {
+    /** Registered AND enabled AND a summarizer model resolves. */
+    live: boolean;
+    /** The summarizer's model id, or `''`. */
+    model: string;
+    /**
+     * How many compactions ANNOUNCED themselves (quiet-noop §6.2 / D-5).
+     *
+     * COMPACTIONS THAT RAN, NOT CHECKPOINTS THAT FIRED. A `pressure` compaction
+     * that declines before calling a model or changing the history never advances
+     * this, which is what keeps the card's `#N` contiguous. `declined` below is
+     * the other half of the same total.
+     */
+    compactions: 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.
+ *
+ * `compaction_start` and `compaction_end` are emitted ONLY for compactions that
+ * COMMITTED TO WORK (quiet-noop §3.1): a `pressure` compaction that declines
+ * before calling a model or changing the history emits NEITHER, and is
+ * deliberately indistinguishable from a turn at which `shouldCompact` returned
+ * false. `manual` and `overflow` always emit both.
+ *
+ * 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). Consumers that count PAIRS are unaffected; consumers that counted
+ * ATTEMPTS must read `/compact status` or the JSONL diagnostic log instead -
+ * CORE's own `compaction_start` / `compaction_end` pair still fires for every
+ * attempt, declined or not, and that is the stream the log subscribes to.
+ */
+export type CompactionEvent = {
+    type: 'compaction_start';
+    index: number;
+    trigger: CompactionUiTrigger;
+    model: string;
+} | {
+    type: 'compaction_end';
+    record: CompactionRecord;
+} | {
+    type: 'usage';
+    usage: TokenUsage;
+} | {
+    type: 'snapshot';
+    snapshot: CompactionSnapshot;
+};
+export type CompactionEventListener = (event: CompactionEvent) => void;

package/dist/compaction/types.js

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+export {};