@aragon-agent/cli 0.6.1 → 0.6.3

package/dist/compaction/pressure.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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;
+/**
+ * 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 {
+    /** 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;
+    /** 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;
+export interface HeadroomRequirement {
+    /** The session's effective output cap for one call. */
+    maxOutputTokens: number;
+}
+/**
+ * The tokens the NEXT request needs on top of the history.
+ *
+ * `THINKING_HEADROOM_TOKENS` (4096) and `CONTEXT_SAFETY_MARGIN_TOKENS` (1024) are
+ * existing core exports and are reused rather than re-spelled.
+ */
+export declare function requiredHeadroom(req: HeadroomRequirement): number;
+/**
+ * The trigger, and the second term is not belt-and-braces (D-12).
+ *
+ * 90 % OF A 200 k WINDOW LEAVES 20 k, WHICH IS PLENTY. 90 % OF A 32 k WINDOW
+ * LEAVES 3.2 k, WHICH IS LESS THAN A SINGLE `max_tokens` OF 8192 - the request is
+ * already impossible. A pure ratio trigger is therefore correct for the models
+ * most users run and quietly wrong for the small ones, and "quietly wrong on the
+ * cheap models" is not a property this product ships.
+ */
+export declare function shouldCompactAt(p: Pressure, threshold: number, req: HeadroomRequirement): boolean;

package/dist/compaction/pressure.js

@@ -0,0 +1,167 @@
+/**
+ * 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);
+}
+/**
+ * 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 nothing to calibrate against and the
+        // raw estimate is used - still under-reporting, but `requiredHeadroom` below
+        // is the belt for that case and it does not depend on the ratio being right.
+        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,
+        contextWindow: window,
+        ratio,
+        headroom: Math.max(0, window - occupied),
+        source,
+        windowKnown: input.windowKnown,
+        ...(input.estimateOffset !== undefined ? { estimateOffset: input.estimateOffset } : {}),
+        deltaTokens,
+    };
+}
+/**
+ * The tokens the NEXT request needs on top of the history.
+ *
+ * `THINKING_HEADROOM_TOKENS` (4096) and `CONTEXT_SAFETY_MARGIN_TOKENS` (1024) are
+ * existing core exports and are reused rather than re-spelled.
+ */
+export function requiredHeadroom(req) {
+    return req.maxOutputTokens + THINKING_HEADROOM_TOKENS + CONTEXT_SAFETY_MARGIN_TOKENS;
+}
+/**
+ * The trigger, and the second term is not belt-and-braces (D-12).
+ *
+ * 90 % OF A 200 k WINDOW LEAVES 20 k, WHICH IS PLENTY. 90 % OF A 32 k WINDOW
+ * LEAVES 3.2 k, WHICH IS LESS THAN A SINGLE `max_tokens` OF 8192 - the request is
+ * already impossible. A pure ratio trigger is therefore correct for the models
+ * most users run and quietly wrong for the small ones, and "quietly wrong on the
+ * cheap models" is not a property this product ships.
+ */
+export function shouldCompactAt(p, threshold, req) {
+    if (p.contextWindow <= 0)
+        return false;
+    return p.ratio >= threshold || p.headroom < requiredHeadroom(req);
+}

package/dist/compaction/summarize-call.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The bounded summarization call (context-auto-compaction §3.6.4).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
+ *
+ * THIS MODULE DOES NOT OWN AN `AbortController`, AND THAT IS A PROHIBITION
+ * RATHER THAN AN OVERSIGHT - the identical rule `fast/review-call.ts` records at
+ * length, and for the identical reason: the retry layer returns SILENTLY on
+ * abort, so a cancellation and a timeout arrive as byte-identical bare `Error`s
+ * carrying no `errorType`. Once the controller is private to this module, the
+ * caller can no longer stamp WHICH of the two happened, and every cancelled
+ * summarization is misreported as a failure.
+ *
+ * So this module RECEIVES the signal and a timeout callback, and returns an
+ * outcome. It does not create, own, or classify the abort.
+ */
+import type { AssistantMessage, LLMRequest, ModelRef, TokenUsage } from '@aragon-agent/core';
+/** The assistant text of a completion, or `''` for an answer with no text block. */
+export declare function assistantText(message: AssistantMessage | undefined): string;
+export declare function errorText(err: unknown): string;
+/**
+ * The call's spend.
+ *
+ * OPTIONAL BY DECLARATION. All three adapters populate `usage` before yielding
+ * `done`, but the field is `usage?` on `AssistantMessage`, and a `computeCost`
+ * over `undefined` is a NaN that reaches the status bar and stays there for the
+ * session (the RV-11 lesson from the fast tier).
+ */
+export declare function usageOf(message: AssistantMessage | undefined): TokenUsage;
+export declare function accumulateUsage(total: TokenUsage, next: TokenUsage): TokenUsage;
+export interface SummarizeRequestParams {
+    ref: ModelRef;
+    apiKey: string;
+    digest: string;
+    instructions?: string;
+    hasPriorSummary: boolean;
+    /** Created and owned by the compactor; forwarded into the provider from there. */
+    signal: AbortSignal;
+    now: number;
+}
+/**
+ * The request one summarization sends. NO TOOLS, no thinking, one bounded user
+ * message - the exact shape `fast/review-call.ts` uses.
+ */
+export declare function buildSummarizeRequest(params: SummarizeRequestParams): LLMRequest;
+export interface SummarizeCallParams extends SummarizeRequestParams {
+    /**
+     * `ProviderRegistry.complete()` - NOT `stream()` (P2-6).
+     *
+     * Nothing consumes a summary incrementally, and `complete` is itself
+     * `consumeStream(this.stream(...))`, which is the fast reviewer's precedent.
+     */
+    complete(providerId: string, request: LLMRequest): Promise<AssistantMessage>;
+    /**
+     * Fired when `callTimeoutMs` elapses.
+     *
+     * THE CALLER ABORTS, NOT THIS MODULE. See the file header.
+     */
+    onTimeout(): void;
+}
+export type SummarizeOutcome = {
+    ok: true;
+    text: string;
+    usage: TokenUsage;
+} | {
+    ok: false;
+    error: unknown;
+};
+/** Send one summarization and bound it in wall clock. */
+export declare function runSummarizeCall(params: SummarizeCallParams): Promise<SummarizeOutcome>;

package/dist/compaction/summarize-call.js

@@ -0,0 +1,86 @@
+/**
+ * The bounded summarization call (context-auto-compaction §3.6.4).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
+ *
+ * THIS MODULE DOES NOT OWN AN `AbortController`, AND THAT IS A PROHIBITION
+ * RATHER THAN AN OVERSIGHT - the identical rule `fast/review-call.ts` records at
+ * length, and for the identical reason: the retry layer returns SILENTLY on
+ * abort, so a cancellation and a timeout arrive as byte-identical bare `Error`s
+ * carrying no `errorType`. Once the controller is private to this module, the
+ * caller can no longer stamp WHICH of the two happened, and every cancelled
+ * summarization is misreported as a failure.
+ *
+ * So this module RECEIVES the signal and a timeout callback, and returns an
+ * outcome. It does not create, own, or classify the abort.
+ */
+import { COMPACTION_LIMITS } from './limits.js';
+import { buildSummarySystemPrompt, buildSummaryUserMessage } from './summary-prompt.js';
+/** The assistant text of a completion, or `''` for an answer with no text block. */
+export function assistantText(message) {
+    if (!message || !Array.isArray(message.content))
+        return '';
+    return message.content
+        .filter((b) => b.type === 'text')
+        .map((b) => b.text)
+        .join('')
+        .trim();
+}
+export function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * The call's spend.
+ *
+ * OPTIONAL BY DECLARATION. All three adapters populate `usage` before yielding
+ * `done`, but the field is `usage?` on `AssistantMessage`, and a `computeCost`
+ * over `undefined` is a NaN that reaches the status bar and stays there for the
+ * session (the RV-11 lesson from the fast tier).
+ */
+export function usageOf(message) {
+    return message?.usage ?? { inputTokens: 0, outputTokens: 0 };
+}
+export function accumulateUsage(total, next) {
+    return {
+        inputTokens: total.inputTokens + next.inputTokens,
+        outputTokens: total.outputTokens + next.outputTokens,
+    };
+}
+/**
+ * The request one summarization sends. NO TOOLS, no thinking, one bounded user
+ * message - the exact shape `fast/review-call.ts` uses.
+ */
+export function buildSummarizeRequest(params) {
+    return {
+        model: params.ref.modelId,
+        ...(params.ref.baseUrl ? { baseUrl: params.ref.baseUrl } : {}),
+        apiKey: params.apiKey,
+        systemPrompt: buildSummarySystemPrompt({
+            maxChars: COMPACTION_LIMITS.summaryMaxChars,
+            ...(params.instructions ? { instructions: params.instructions } : {}),
+            hasPriorSummary: params.hasPriorSummary,
+        }),
+        messages: [buildSummaryUserMessage(params.digest, params.now)],
+        maxTokens: COMPACTION_LIMITS.summaryOutputTokens,
+        // PAIRED WITH `temperature: 0` ON PURPOSE: the Anthropic adapter deletes
+        // `temperature` whenever a thinking budget is set, so these two are one
+        // choice and not two.
+        thinkingLevel: 'off',
+        temperature: 0,
+        signal: params.signal,
+    };
+}
+/** Send one summarization and bound it in wall clock. */
+export async function runSummarizeCall(params) {
+    const timer = setTimeout(params.onTimeout, COMPACTION_LIMITS.callTimeoutMs);
+    try {
+        const message = await params.complete(params.ref.providerId, buildSummarizeRequest(params));
+        return { ok: true, text: assistantText(message), usage: usageOf(message) };
+    }
+    catch (error) {
+        return { ok: false, error };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/compaction/summary-prompt.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 type { Message, UserMessage } from '@aragon-agent/core';
+/**
+ * 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 declare function buildSummarySystemPrompt(opts: {
+    maxChars: number;
+    /** Free text from `/compact <instructions>`, appended as `## Focus`. */
+    instructions?: string;
+    /** True when the digest opens with a `PRIOR SUMMARY` section. */
+    hasPriorSummary: boolean;
+}): string;
+/** The user message the summarization call sends: the digest, and nothing else. */
+export declare function buildSummaryUserMessage(digest: string, now: number): UserMessage;
+export type AnchorShape = 'tagged' | 'verbatim';
+export interface AnchorInfo {
+    /** The message to place first, verbatim in the history. */
+    message: Message;
+    shape: AnchorShape;
+}
+/**
+ * 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 declare function isTaggedAnchor(message: Message): boolean;
+/**
+ * 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 declare function buildAnchor(messages: readonly Message[]): AnchorInfo | null;
+/**
+ * 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 declare function countProtectedPrefix(messages: readonly Message[]): number;
+/** Read `generation="N"` off a prior block, so the next one can say `N + 1`. */
+export declare function readGeneration(messages: readonly Message[]): number;
+export interface BlockInput {
+    summary: string;
+    replaced: number;
+    turns: number;
+    anchor: AnchorShape;
+    generation: number;
+    /** True for a `mode: 'truncated'` splice — the model is entitled to know. */
+    truncated: boolean;
+}
+/** The body used when the ladder ran out and there is no summary (§3.7 rung 3). */
+export declare function truncationBody(replaced: number): string;
+/**
+ * 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 declare function buildCompactedBlock(input: BlockInput): UserMessage;