@cerebriline/core 4.100.240

package/dist/extensions/context/compaction-shared.d.ts

@@ -0,0 +1,608 @@
+import type { ModelInfo, ReasoningHistoryMode, ToolResultContent } from "@cerebriline/llms";
+import { resolveDefaultMaxOutputTokens } from "@cerebriline/llms";
+import { CHARS_PER_TOKEN, estimateThinkingTokens, estimateTokens, type MessageWithMetadata } from "@cerebriline/shared";
+export { CHARS_PER_TOKEN, estimateThinkingTokens, estimateTokens };
+import type { CoreCompactionSummarizerConfig } from "../../types/config";
+import type { ProviderConfig } from "../../types/provider-settings";
+import type { ToolLedgerEntry } from "./tool-ledger";
+export declare const DEFAULT_MAX_INPUT_TOKENS = 128000;
+/** Estimate the usable input share when only a context window is reported. */
+export declare const CONTEXT_WINDOW_INPUT_RATIO = 0.9;
+/** Compact once the transcript consumes this share of the usable input budget. */
+export declare const COMPACTION_TRIGGER_RATIO = 0.9;
+export declare const DEFAULT_TARGET_RATIO = 0.7;
+export declare const DEFAULT_PRESERVE_RECENT_TOKENS = 20000;
+/**
+ * The recency floor for a given window.
+ *
+ * `DEFAULT_PRESERVE_RECENT_TOKENS` was a single number applied to every model,
+ * which is right for exactly one window size. Measured against the two ends it
+ * has to serve: on a 32k window it asks to preserve more than the compaction
+ * target, so compaction can reclaim nothing; on a 1M window it throws away
+ * everything but the last few turns of a task with room for forty times that.
+ */
+export declare function resolvePreserveRecentTokens(input: {
+    contextWindow?: number;
+    maxInputTokens?: number;
+    messageTargetTokens?: number;
+    override?: number;
+}): number;
+/** Floor for a compaction summary, and the cap when no window is known. */
+export declare const DEFAULT_SUMMARY_MAX_OUTPUT_TOKENS = 4096;
+/**
+ * Ceiling for a compaction summary, however much window is free.
+ *
+ * A summary is the whole of what survives the messages it replaces, so it is
+ * worth spending real tokens on -- but it also becomes the context every later
+ * turn carries, so it cannot be allowed to grow into the space compaction just
+ * freed. This is the point past which a longer summary stops being a better one.
+ */
+export declare const MAX_SUMMARY_OUTPUT_TOKENS = 8192;
+/** Share of the usable input budget a summary may occupy. */
+export declare const SUMMARY_OUTPUT_WINDOW_SHARE = 0.08;
+export declare const TOOL_RESULT_CHAR_LIMIT = 2000;
+export declare const FILE_CONTENT_CHAR_LIMIT = 2000;
+export declare const MIN_TRUNCATED_MESSAGE_TOKENS = 8;
+export declare function resolveSummaryMaxOutputTokens(maxInputTokens: number | undefined): number;
+export interface CompactionOutputBudgets {
+    /** Generation of the compaction being written, 1-based. */
+    generation: number;
+    /** Summary and retrospective together. */
+    combinedTokens: number;
+    summaryMaxTokens: number;
+}
+export declare function resolveCompactionOutputBudgets(input: {
+    messageTargetTokens?: number;
+    maxInputTokens?: number;
+    generation?: number;
+}): CompactionOutputBudgets;
+/**
+ * What is left for the retrospective once the summary has been written.
+ *
+ * Measured against what the summary actually cost, not what it was allowed:
+ * the point of writing them in this order is that an economical summary buys
+ * the retrospective room rather than wasting it.
+ */
+export declare function resolveThinkingSummaryMaxTokens(input: {
+    budgets: CompactionOutputBudgets;
+    summaryTokens: number;
+}): number;
+export { resolveDefaultMaxOutputTokens };
+/**
+ * What one message costs in the context as the provider will receive it.
+ *
+ * The index comes along because the answer depends on position: under a
+ * `reasoningHistory` of `last` only the final assistant turn still carries its
+ * reasoning, and a measurer handed a message on its own cannot know whether it
+ * is that one.
+ */
+export type MeasureContextTokens = (message: MessageWithMetadata, index: number) => number;
+/**
+ * What this session's turns have actually cost, as a basis for how much of the
+ * window to hold back for the next one.
+ *
+ * The two models this was measured on want opposite things. One answers a tool
+ * call in 24 to 2,164 output tokens and never reasons at length: holding 32,000
+ * tokens back for it spends a fifth of the window on nothing. The other opens
+ * 35,000 to 45,000 characters of thinking on most turns, around 17,000 tokens,
+ * and a reservation sized for the first model would put it into overflow
+ * recovery repeatedly. No single fraction serves both, and the transcript
+ * already says which one is running.
+ *
+ * The high-water mark of the recent window rather than the mean: the reservation
+ * exists for the largest turn, and an average over a session that thinks on one
+ * turn in four describes none of them.
+ *
+ * **Measured from the transcript, never from the bill.** `metrics.outputTokens`
+ * is what the provider charged for generating the turn, and a turn whose
+ * reasoning has since been condensed away is still carrying its original
+ * invoice. Measured on pandorum 2026-09-19: a capped think billed 30,786 tokens
+ * and was replaced with a 624-character note the same second, and the bill went
+ * on reserving half a 65,536-token window for the next twelve turns -- pinning
+ * the trigger to its 50% floor while the turns that followed produced 130 and
+ * 144 tokens. `measure` is the caller's estimator for what a message costs in
+ * the context as it stands, which is the question the reservation is asking.
+ */
+export declare function resolveObservedOutputTokens(messages: readonly MessageWithMetadata[], measure: MeasureContextTokens, sampleTurns?: number): number | undefined;
+/**
+ * The largest prompt that still leaves the model room to answer.
+ *
+ * The trigger used to ask only whether the prompt fit. It does not follow that
+ * a reply fits: a turn needs the prompt *and* its output inside one window, and
+ * the output cap is up to `maxTokens`. Measured live on a 110,000-token window
+ * with a 32,000 cap -- the transcript was allowed to 99,000, the request path
+ * then found 11,000 short of what it needed and sent no cap at all, and the turn
+ * died on the output limit with compaction still reporting there was room.
+ *
+ * Taking the smaller of the two keeps the old ratio as an upper bound while
+ * making room for a full turn the binding constraint, which is what it is.
+ */
+/**
+ * The tokens held back for the next reply, sized to this session's own turns.
+ *
+ * Extracted from {@link resolveCompactionTriggerTokens} so the two readers of
+ * this number cannot drift apart. The trigger asks it *before* a turn -- how
+ * much of the window must stay free -- and the starved-cap check asks it
+ * *after* one, against the cap the request path actually resolved. A second
+ * figure for the same quantity is the disagreement this file exists to end.
+ *
+ * The declared room comes from the gateway rather than being restated here: it
+ * synthesizes a cap in exactly this situation, and that default is a share of
+ * the window, so the flat 32,000 this used to be under-reserved on every window
+ * wider than 128k.
+ */
+export declare function resolveOutputRoomTokens(input: {
+    contextWindow?: number;
+    modelMaxTokens?: number;
+    observedOutputTokens?: number;
+}): number;
+export declare function resolveCompactionTriggerTokens(input: {
+    maxInputTokens: number;
+    contextWindow?: number;
+    modelMaxTokens?: number;
+    /** The high-water output of recent turns, from {@link resolveObservedOutputTokens}. */
+    observedOutputTokens?: number;
+}): number;
+export interface FileOperationSummary {
+    readFiles: string[];
+    modifiedFiles: string[];
+}
+export interface CompactionSummaryMetadata {
+    kind: "compaction_summary";
+    displayRole: "system";
+    userRunSpan: number;
+    summary: string;
+    details: FileOperationSummary;
+    tokensBefore: number;
+    generatedAt: number;
+    /**
+     * How many compactions this summary is the product of, 1-based.
+     *
+     * Carried on the message because it is the only durable record of it: the
+     * summary chains through its own metadata, and the output budget ladder is
+     * indexed by this number.
+     */
+    generation: number;
+    /** The retrospective written alongside this summary, if there was one. */
+    thinkingSummary?: string;
+    /**
+     * The harness's record of the calls this summary stands for. Read by the
+     * chat row, and by the next compaction through `toolLedgerEntries`.
+     */
+    toolLedger?: string;
+    /**
+     * The same record, structured, so the next generation can carry it.
+     *
+     * A ledger used to live for exactly one generation, on the reasoning that
+     * anything fed back accumulates without bound. That is true of prose and
+     * false of a record: a record can be evicted, and `evictToolLedger` does
+     * it in the order that keeps what cannot be recovered. What the one-shot
+     * rule cost was the standing evidence -- after a compaction the model no
+     * longer knew it had a checker to run, and went back to declaring the work
+     * done on a reading of the source.
+     */
+    toolLedgerEntries?: ToolLedgerEntry[];
+    /**
+     * Everything the user actually typed, verbatim, oldest first.
+     *
+     * Written by the harness and never by the model, which is the whole point.
+     * The prompt asks for the instructions word for word and the model
+     * paraphrases them, and from the second generation the only copy left is
+     * the paraphrase inside the previous summary -- so each compaction
+     * paraphrases a paraphrase. Measured on pandorum session
+     * 1789852877349_7bbnd, where a request naming the command to run came back
+     * as "The user is asking me to fix the collision in `manic_miner.html`"
+     * and the model never ran the command again.
+     *
+     * Never evicted. It is small, and it is the one thing in a transcript that
+     * exists nowhere else once the messages are gone.
+     */
+    userRequests?: string[];
+}
+export type EstimateMessageTokens = (message: MessageWithMetadata) => number;
+/**
+ * Measures the request a transcript would produce, for reporting.
+ *
+ * Distinct from `EstimateMessageTokens`, which sums whole serialized messages
+ * and so counts reasoning the provider is not sent and metadata that never
+ * leaves the host. That sum is the right input for a cut decision, where the
+ * comparison is between two transcripts measured the same way, and the wrong
+ * one for a number shown beside the context meter.
+ */
+export type MeasureReportedTokens = (messages: readonly MessageWithMetadata[]) => number;
+/**
+ * Resolve the model's usable prompt budget. A reported input limit is
+ * authoritative but cannot exceed the context window. When the model only
+ * reports a context window, retain a conservative margin for request overhead.
+ */
+export declare function resolveEffectiveMaxInputTokens(input: Pick<ModelInfo, "maxInputTokens" | "contextWindow">): number | undefined;
+export declare function truncateText(text: string, limit: number): string;
+/**
+ * The tool outputs that carry no `type` discriminator.
+ *
+ * `read_files`, `run_commands` and `search_codebase` answer with
+ * `ToolOperationResult` objects -- `{query, result, success, error?}` -- and
+ * `toPersistedToolResultContent` stores them in the same array as text and
+ * file blocks, because the persisted codec "accepts a wider runtime value set
+ * than the public `ToolResultContent` type describes". Anything here that
+ * switches on `block.type` alone therefore has to say what it does with the
+ * rest, and returning "" is the wrong answer: it blanked 50 of the 99 tool
+ * results in one measured pandorum session -- 414,337 characters, every file
+ * read and all three of the checker's verdicts among them. The summarizer saw
+ * a call followed by nothing and filled the gap with what it assumed had
+ * happened, so a session whose checker returned `ok:false` three times was
+ * summarised as "the game is running" and the next context believed it.
+ */
+export interface StructuredToolResultEntry {
+    query?: unknown;
+    result?: unknown;
+    success?: unknown;
+    error?: unknown;
+}
+export declare function asStructuredToolResultEntry(block: unknown): StructuredToolResultEntry | undefined;
+export declare function flattenToolResultContent(content: ToolResultContent["content"]): string;
+export declare function truncateToolResultContentForCompaction(content: ToolResultContent["content"]): ToolResultContent["content"];
+export declare function formatToolInput(input: Record<string, unknown>): string;
+export declare function serializeMessage(message: MessageWithMetadata): string;
+/**
+ * Render the discarded reasoning against what it produced.
+ *
+ * The retrospective's whole value is the pairing. Reasoning on its own reads as
+ * a plan and every plan reads as sound; it is the outcome next to it that shows
+ * which ones were. So each turn is one block: what the model thought, what it
+ * then called, and how that call came back -- applied, refused as a no-op,
+ * failed, or refused by the loop guard.
+ *
+ * Tool results are reduced to their verdict rather than included. A retrospective
+ * about method has no use for the contents of a file, and on the transcripts this
+ * was built against the results are most of the bytes.
+ */
+export declare function serializeReasoningWithOutcomes(messages: MessageWithMetadata[]): string;
+export declare function serializeConversation(messages: MessageWithMetadata[]): string;
+export declare function createTokenEstimator(): EstimateMessageTokens;
+export declare function isCompactionSummaryMessage(message: MessageWithMetadata): boolean;
+/**
+ * The compaction from which the recency tail is dropped anyway, counting from
+ * 1. Zero -- the default -- never drops it, so the tail policy is whatever
+ * `keepRecentMessages` says and does not change part-way through a run.
+ *
+ * This was 2, and that was a mistake worth recording rather than quietly
+ * deleting. It meant no session ever ran a single tail policy: the first
+ * compaction kept the tail and every later one dropped it. Two consequences
+ * followed, both measured.
+ *
+ * The first compaction became the weak one by construction -- over 30 first
+ * and 24 later compactions on pandorum, a median -30% leaving 20 messages
+ * against -65% leaving 4. A run then refilled to the trigger within a median
+ * of 12 turns and took a second compaction, which is the one the fix rate
+ * falls off (85% / 63% / 50% / 25% by compaction count over 335 runs).
+ *
+ * The second is that it made its own evidence unreadable. The v6 A/B that
+ * appeared to justify the ladder ran `--force-full-from-compaction 2` in both
+ * arms, so "keep" meant keep-once-then-drop and "drop" meant drop-always. That
+ * is not a contrast between keeping and dropping a tail, and it duly separated
+ * nothing on the verdict. Whatever the right tail policy is, it has to be one
+ * policy for a whole run before any arm can measure it.
+ *
+ * The override survives for anyone who wants the old behaviour deliberately;
+ * it is no longer the default. The no-tail *fallback* is unaffected -- a
+ * compaction that keeps the tail and still lands over the trigger retries
+ * without it, which is a rescue and not a schedule.
+ */
+export declare const FORCE_FULL_FROM_COMPACTION = 0;
+/**
+ * Whether this compaction keeps nothing, whatever `keepRecentMessages` says.
+ *
+ * `from` is the compaction index it starts at: `1` drops the tail on every
+ * compaction, and anything below `1` never does. Unset takes the measured
+ * default above.
+ */
+export declare function dropsTailAtThisCompaction(messages: readonly MessageWithMetadata[], from: number | undefined): boolean;
+export declare function getCompactionSummaryMetadata(message: MessageWithMetadata): CompactionSummaryMetadata | undefined;
+export declare function isToolResultOnlyUserMessage(message: MessageWithMetadata): boolean;
+export declare function isTurnStartMessage(message: MessageWithMetadata): boolean;
+/**
+ * What the user typed, verbatim, in the order they typed it.
+ *
+ * Turn-start messages only, so a tool result and a summary the harness wrote
+ * are both excluded. Consecutive duplicates collapse: a resend of the same
+ * instruction is the same instruction.
+ */
+/** The most any single quoted request may take before its middle is cut. */
+export declare const MAX_USER_REQUEST_CHARS = 2000;
+export declare function collectUserRequests(messages: readonly MessageWithMetadata[]): string[];
+export declare function findFirstUserMessageIndex(messages: MessageWithMetadata[]): number;
+export declare function findLastTurnStartIndex(messages: MessageWithMetadata[]): number;
+export declare function findLastAssistantIndex(messages: MessageWithMetadata[]): number;
+export declare function findLatestSummaryIndex(messages: MessageWithMetadata[]): number;
+/**
+ * The share of the material after a pinned prompt that a compaction folds when
+ * the prompt-preservation cap would otherwise leave it nothing to do.
+ *
+ * A fraction rather than a token count, deliberately. Every absolute threshold
+ * in this pipeline is only as trustworthy as the token estimator feeding it,
+ * and that estimator drifts by multiples. "Half of what follows the prompt" is
+ * half of what follows the prompt no matter how the counting drifts, because
+ * the bias appears in both sides of the ratio and cancels.
+ */
+export declare const PINNED_PROMPT_FOLD_RATIO = 0.5;
+/**
+ * The share of a transcript's messages the preserved tail should reach before
+ * the token floor alone is allowed to end the walk.
+ *
+ * A token floor on its own says nothing about how much *conversation* survives,
+ * and the two come apart when messages are heavy. Measured live: a 113-message
+ * transcript whose recent turns carried ~3.3k tokens each satisfied a 20,000
+ * token floor after six messages, so a compaction with a ~73,000 token budget
+ * kept seven. Twenty thousand tokens of two file dumps is not a thread anyone
+ * can pick up.
+ *
+ * A quarter is chosen to be legible on a short transcript and irrelevant on a
+ * long one: 25% of 500 messages will always reach the ceiling first, so the
+ * ratio stops applying exactly where honouring it would be reckless.
+ */
+export declare const DEFAULT_PRESERVE_RECENT_MESSAGES_RATIO = 0.25;
+/**
+ * The three bounds on how much of the tail survives a compaction.
+ *
+ * Two lower bounds and one upper, because "how much is enough" and "how much is
+ * too much" are different questions and only the second has a budget behind it.
+ */
+export interface RecencyBounds {
+    /**
+     * Minimum tokens to preserve; the conversation is unusable below this, and
+     * never more than the budget the compacted request has to fit in — a floor
+     * above the ceiling is not a floor, it is a refusal to compact.
+     */
+    tokenFloor: number;
+    /** Minimum share of the transcript's messages to preserve. */
+    messagesRatio: number;
+    /**
+     * The most the preserved tail may cost before the last turn stops being
+     * exempt from the cut.
+     *
+     * The last typed turn survives verbatim so the model keeps the request it is
+     * working on. That exemption is unbounded, and a long tool loop under one
+     * prompt is all one turn: measured live, a 250,621-byte request compacted to
+     * 226,763 -- ten small messages folded, 9.5 percent reclaimed -- because the
+     * cut was clamped to the start of a turn that was nearly the whole
+     * transcript, and the trigger fired again on the very next turn. Past this
+     * ceiling, keeping the turn whole costs more than it is worth and the cut is
+     * allowed into it.
+     */
+    lastTurnCeiling?: number;
+    /**
+     * Maximum tokens to preserve. Compaction computes a target for the
+     * post-compaction request and this is what that target buys: without it the
+     * floor is also the ceiling, and every compaction folds to the minimum no
+     * matter how much room the model actually had.
+     */
+    tokenCeiling: number;
+}
+export declare function resolveRecencyBounds(input: {
+    preserveRecentTokens: number;
+    preserveRecentMessagesRatio?: number;
+    messageTargetTokens?: number;
+    lastTurnCeiling?: number;
+}): RecencyBounds;
+export interface CompactionCutPlan {
+    /**
+     * Everything before this index is folded into the summary; the messages
+     * from here on survive verbatim. Zero means no cut makes progress.
+     */
+    cutIndex: number;
+    /**
+     * A typed prompt that lies *before* the cut but must still survive
+     * verbatim, or -1 when the cut already preserves every typed prompt.
+     */
+    pinnedIndex: number;
+}
+export declare function findCutPlan(messages: MessageWithMetadata[], bounds: RecencyBounds, estimateMessageTokens: EstimateMessageTokens): CompactionCutPlan;
+/**
+ * Fold the whole transcript, keeping only the request that started the turn.
+ *
+ * The cut plan for the strategy that keeps no recency tail: the summary is the
+ * context, so the cut is the end of the transcript and there is nothing after
+ * it. None of {@link findCutPlan}'s reasoning applies, because all of it is
+ * about where to stop, and this stops nowhere.
+ *
+ * One message is still pinned, and it is a deliberate exception rather than a
+ * half-measure. The typed request that started the turn is the single thing
+ * whose loss is unrecoverable *and* unnoticeable: the material worked on is
+ * still on disk, the tool record is rebuilt by the ledger, but a summary that
+ * drops the request leaves the model with a detailed account of work whose
+ * purpose it no longer knows. That is measured, not hypothetical — a
+ * jackdelta-9b session compacted 322 messages to 70 and sixteen seconds later
+ * asked the user what the task was. It costs one message, and it is the one
+ * message worth a guaranteed carry rather than a requested one.
+ *
+ * Returns `pinnedIndex: -1` when there is no typed request to pin: a
+ * transcript that is entirely a previous summary plus a tool loop has nothing
+ * that qualifies, and pinning index 0 there would carry the old summary
+ * forward verbatim alongside the new one.
+ */
+export declare function planFullCut(messages: MessageWithMetadata[]): CompactionCutPlan;
+export declare function collectPaths(value: unknown): string[];
+export declare function mergeUnique(base: string[], next: Iterable<string>): string[];
+export declare function extractFileOps(messages: MessageWithMetadata[]): FileOperationSummary;
+/** Commands longer than this are truncated in dropped-work summaries. */
+export declare const COMMAND_SUMMARY_CHAR_LIMIT = 100;
+/**
+ * Compact record of the tool work performed inside a span of dropped
+ * messages: which files were read and edited (with line ranges when
+ * known) and which commands ran.
+ */
+export interface ToolActivitySummary {
+    readFiles: string[];
+    editedFiles: string[];
+    commands: string[];
+}
+export declare function hasToolActivity(summary: ToolActivitySummary): boolean;
+/**
+ * Summarize the tool work inside a span of messages that compaction is
+ * dropping. Read ranges come from read_files inputs; edited ranges come
+ * from the numbered diff in the matching editor result when present.
+ */
+export declare function summarizeToolActivity(messages: MessageWithMetadata[]): ToolActivitySummary;
+export declare function formatToolActivitySummary(summary: ToolActivitySummary): string;
+export declare function renderFilesSection(fileOps: FileOperationSummary): string;
+export declare function ensureFilesSection(summary: string, fileOps: FileOperationSummary): string;
+/**
+ * What the summarizer is asked for when nothing else is configured.
+ *
+ * The summary replaces the turns it stands for, permanently: every later turn
+ * reads this and never the conversation again. So the instruction that matters
+ * is not "be concise" -- brevity is what loses the work -- but which specific
+ * things must survive the compression. The old default asked for a concise,
+ * factual note under five headings and said nothing about identifiers, paths,
+ * decisions already taken or approaches already ruled out, which is exactly
+ * what a model needs in order not to redo them.
+ *
+ * `{{files_read}}` and `{{files_edited}}` are substituted before sending. A
+ * template that omits them still gets a Files section appended, because losing
+ * track of which files are in play is the one failure that makes a summary
+ * actively misleading rather than merely thin.
+ */
+export declare const DEFAULT_COMPACTION_PROMPT = "You are writing the hand-over note for a session that is about to lose its transcript. Everything below will be discarded; only your note survives, and whoever continues this work will have nothing else to go on.\n\nWrite for that reader. Prefer specifics over summary: exact names, identifiers and paths, quoted wording, error text, commands, and numbers. Do not compress away detail that would have to be rediscovered \u2014 an over-long note costs a little context, a vague one costs the whole investigation.\n\n## Goal\nWhat is being built or fixed, in one or two sentences, including any constraint the user stated.\n\n## Done\nWhat is finished and verified, with the evidence \u2014 which files changed, what the test or command said. Be specific enough that none of it gets redone.\n\n## In progress\nWhat is underway right now, and exactly where it stopped.\n\n## Ruled out\nApproaches already tried that did not work, and why. Omit if none \u2014 but never drop one that was tried, or it will be tried again.\n\n## Key facts\nDecisions taken, values discovered, identifiers, signatures, and anything learned about the material at hand that would not be obvious to someone looking at it fresh. Omit if none.\n\n## Next\nThe immediate next steps, in order.\n\nWrite them for a reader holding no file contents. Where a step touches a file it\nmust begin by reading the part it touches, and no step may say to write, rewrite\nor restore content that this note does not itself contain \u2014 that reader would\nhave to reconstruct it from memory, and what it produces will be a worse version\nof something that is still on disk. Prefer the smallest change that achieves the\nresult over redoing the whole of anything.\n\n## Files\nRead: {{files_read}}\nEdited: {{files_edited}}";
+export declare function buildSummaryRequest(options: {
+    previousSummary?: string;
+    conversationText: string;
+    fileOps: FileOperationSummary;
+    /** Overrides {@link DEFAULT_COMPACTION_PROMPT}; blank falls back to it. */
+    promptTemplate?: string;
+    /**
+     * What the user typed, quoted by the harness.
+     *
+     * The prompt asks the summary to open with what was asked, verbatim, and
+     * the transcript below does not always contain it: a prompt the cut pinned
+     * survives outside the span being summarized, so on the one-prompt-then-a-
+     * long-loop shape the summarizer was asked to quote an instruction it had
+     * never been shown. It did the honest thing and wrote that the
+     * instructions were missing from its view, into the summary, where the
+     * next turn reads it first.
+     */
+    userRequests?: readonly string[];
+    /**
+     * What the quoted block may spend of the summarizer's own input.
+     *
+     * Sized by the caller against the summarizer's limit rather than left at
+     * the default: on a small model the unbounded block is a large share of
+     * the whole request, and it pushed the summary over its output budget and
+     * into a retry -- paying a second model call to quote an instruction more
+     * fully than the model had room to read.
+     */
+    userRequestBudgetChars?: number;
+    /**
+     * The numbered record of the calls, for the replay to cite.
+     *
+     * Supplied so citing a number is a lookup rather than a memory feat: the
+     * writer is asked to put `[#7]` where a call belongs, and it can only do
+     * that if it can see which call is 7.
+     */
+    toolLedger?: string;
+    /**
+     * The writer already holds the transcript: it is writing as the next turn
+     * of the conversation (compaction as a continuation). This says which part
+     * of that context the replay covers, and takes the place of the
+     * `Conversation:` section -- repeating the transcript as text is exactly
+     * the prefill a continuation exists to avoid.
+     */
+    conversationInContext?: string;
+}): string;
+/**
+ * The second phase's prompt: a retrospective, not a second summary.
+ *
+ * The summary describes what happened. This describes how the work went, which
+ * is the part that dies with the thinking blocks compaction discards -- every
+ * wrong turn, every retry, every stretch spent on an approach that was never
+ * going to work. A model that starts from a summary alone starts with no memory
+ * of having been wrong, and makes the same mistakes in the same order.
+ *
+ * Written hard against verbosity, because the models this matters most for are
+ * the ones that ruminate: on a coder model that hits its thinking cap most
+ * turns, an unbounded "reflect on your reasoning" produces more of exactly the
+ * behaviour it is meant to flag. Hence the ban on specifics -- those are in the
+ * summary, and repeating them here spends the budget twice for one fact.
+ */
+export declare const DEFAULT_THINKING_COMPACTION_PROMPT = "You are writing the retrospective that goes at the top of your own context after compaction. It is not a summary \u2014 what happened is written up separately, and repeating it here wastes the space this needs.\n\nYou are reading your own reasoning from the work about to be discarded, together with what each stretch of it produced: which tool calls landed, which were refused, which were retried unchanged, and which turns ran long.\n\nWrite the honest assessment. Be terse. Every line must be something you would want to know before starting the next hour of this task.\n\n## What worked\nApproaches that produced progress, stated as approaches rather than as events.\n\n## What did not\nApproaches that cost time and produced nothing. Name the failure mode: repeating an unchanged call, editing from a stale read, rewriting where narrowing would do, chasing a symptom.\n\n## Where the time went\nThe stretches that were expensive against what they achieved, including any turn where the reasoning ran long without converging.\n\n## Do differently\nWhat to do instead. Concrete enough to act on, short enough to remember.\n\nRules:\n- No file names, line numbers, code, identifiers or values. Those are in the summary. This is about method.\n- No narration of the sequence of events. Judgement only.\n- Leave out any section with nothing worth saying.\n- Terse throughout. A dozen short lines is a good retrospective; a page is a failed one.";
+export declare function buildThinkingSummaryRequest(options: {
+    previousThinkingSummary?: string;
+    reasoningText: string;
+    /** Overrides {@link DEFAULT_THINKING_COMPACTION_PROMPT}; blank falls back. */
+    promptTemplate?: string;
+}): string;
+export declare function resolveSummarizerConfig(options: {
+    activeProviderConfig: ProviderConfig;
+    summarizer?: CoreCompactionSummarizerConfig;
+    /**
+     * The summarizer's usable input budget, once it is known. Left out on the
+     * first pass, which exists to resolve that budget from the merged model.
+     */
+    maxInputTokens?: number;
+    /**
+     * The output cap for this call, when the caller has one.
+     *
+     * The window-derived default is flat for the life of a session; the
+     * generation ladder is not, and the retrospective's cap is not even known
+     * until the summary has been written. Both are decided by the caller.
+     */
+    outputTokenCap?: number;
+}): ProviderConfig;
+export declare function buildSummaryMessage(options: {
+    summary: string;
+    fileOps: FileOperationSummary;
+    tokensBefore: number;
+    userRunSpan: number;
+    generation?: number;
+    /** The retrospective, prepended as this message's own reasoning. */
+    thinkingSummary?: string;
+    /**
+     * The measured record of the tool calls being folded, appended after the
+     * summary — see {@link renderToolLedger}.
+     *
+     * Deliberately not part of `metadata.summary`, which is what the next
+     * compaction hands the model as `previousSummary`. A ledger that fed back
+     * would be re-emitted into the summary that replaces it, and each
+     * generation would carry every earlier generation's calls: the transcript
+     * would shrink while the summary grew, which is the one outcome compaction
+     * cannot have. So a ledger lives for exactly one generation, and by the
+     * next one its calls are in the prose.
+     */
+    toolLedger?: string;
+    /** The same ledger, structured, for the generation after this one. */
+    toolLedgerEntries?: ToolLedgerEntry[];
+    /** Everything the user typed, verbatim, oldest first. */
+    userRequests?: string[];
+    /** How much room the quoted requests may take, all together. */
+    userRequestBudgetChars?: number;
+}): MessageWithMetadata;
+/**
+ * Recover the token calibration from a transcript that was written by an
+ * earlier process.
+ *
+ * Every assistant turn records what the provider counted for the request that
+ * produced it, so a resumed session is not actually uncalibrated — it just
+ * starts as if it were, because the calibration lives in process memory. That
+ * gap is what makes a resume compact immediately: the character estimate reads
+ * roughly twice the real size of a transcript (three assumed characters per
+ * token against a measured 5.9), and twice a normal working context is over any
+ * threshold.
+ *
+ * The newest turn with a recorded count is used, paired with the request that
+ * produced it — the messages before it, plus the system prompt and tools, which
+ * is the same payload {@link measureRequestInputChars} measures live. Both the
+ * ratio and the count are adopted, so the first decision after a resume is made
+ * on the same evidence the last decision before it was.
+ *
+ * Nothing happens once a live response has been observed, and nothing happens
+ * for a transcript that carries no counts (a fresh session, or a provider that
+ * reports no usage) — those keep the estimate they always had.
+ */
+export declare function seedCalibrationFromTranscript(request: {
+    systemPrompt?: string;
+    messages: MessageWithMetadata[];
+    tools?: unknown[];
+    reasoningHistory?: ReasoningHistoryMode;
+    /** Whose transcript this is, so the seeded count answers only to it. */
+    sessionId?: string;
+}): void;