@cerebriline/core 4.100.240

package/dist/extensions/config/user-instruction-service.d.ts

@@ -0,0 +1,31 @@
+import type { AgentExtension } from "@cerebriline/shared";
+import { type SkillsExecutorWithMetadata } from "../tools";
+import { type AvailableRuntimeCommand, type ResolveRuntimeSlashCommandOptions } from "./runtime-commands";
+import { type CreateUserInstructionConfigWatcherOptions, type UserInstructionConfig, type UserInstructionConfigType } from "./user-instruction-config-loader";
+import { type CreateUserInstructionPluginOptions } from "./user-instruction-plugin";
+export interface UserInstructionConfigRecord<TConfig extends UserInstructionConfig = UserInstructionConfig> {
+    type: UserInstructionConfigType;
+    id: string;
+    filePath: string;
+    item: TConfig;
+}
+export interface CreateUserInstructionConfigServiceOptions extends CreateUserInstructionConfigWatcherOptions {
+}
+export interface UserInstructionConfigService {
+    start(): Promise<void>;
+    stop(): void;
+    refreshType(type: UserInstructionConfigType): Promise<void>;
+    listRecords<TConfig extends UserInstructionConfig = UserInstructionConfig>(type: UserInstructionConfigType): UserInstructionConfigRecord<TConfig>[];
+    listRuntimeCommands(): AvailableRuntimeCommand[];
+    resolveRuntimeSlashCommand(input: string, options?: ResolveRuntimeSlashCommandOptions): string;
+    hasConfiguredSkills(allowedSkillNames?: ReadonlyArray<string>): boolean;
+    createSkillsExecutor?(allowedSkillNames?: ReadonlyArray<string>): SkillsExecutorWithMetadata;
+    createExtension(options: Omit<CreateUserInstructionPluginOptions, "watcher" | "watcherReady">): AgentExtension;
+}
+/**
+ * Present multiple instruction sources as one extension/tool surface. This is
+ * used by the hub to overlay host-local Agent Plugin skills on a client-owned
+ * instruction snapshot without moving package discovery into each client.
+ */
+export declare function combineUserInstructionConfigServices(services: ReadonlyArray<UserInstructionConfigService>): UserInstructionConfigService;
+export declare function createUserInstructionConfigService(options?: CreateUserInstructionConfigServiceOptions): UserInstructionConfigService;

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

@@ -0,0 +1,129 @@
+import type { BasicLogger, MessageWithMetadata } from "@cerebriline/shared";
+import type { CoreCompactionContext, CoreCompactionResult, CoreCompactionSummarizerConfig } from "../../types/config";
+import type { ProviderConfig } from "../../types/provider-settings";
+import { type BudgetProjectionResult } from "./budget-projection";
+import { type EstimateMessageTokens, type MeasureReportedTokens, type RecencyBounds } from "./compaction-shared";
+import { type CompactionContinuation, type CompactionMeter } from "./continuation-compaction";
+import { type RevisionSpanLookup } from "./tool-ledger";
+export declare function buildAgenticSummaryInputBudget(options: {
+    messages: CoreCompactionContext["messages"];
+    targetTokens: number;
+    estimateMessageTokens: EstimateMessageTokens;
+}): BudgetProjectionResult;
+/**
+ * What the summarizer is told it is, which is not the same job in both modes.
+ *
+ * The system half used to say "concise" while the user half asked for the
+ * detail that has to survive, and the model was pulled both ways on the one
+ * message that has to carry everything. Both of these agree with their prompt
+ * instead — and they have to be separate texts, because the two prompts ask
+ * for different artifacts. A replay is written in the first person and is read
+ * as the model's own memory; a full summary is a state record read as the only
+ * surviving fact. Telling a model to write a hand-over note and then handing it
+ * the replay prompt reproduces the seam the replay prompt exists to remove.
+ */
+export declare const SUMMARIZER_SYSTEM_PROMPTS: {
+    readonly tail: "You are re-telling your own recent work in your own voice, because the earlier part of your transcript is about to be discarded and what you write takes its place directly in front of the turns that remain. Match the prose of those turns. Keep every specific — names, paths, quoted wording, errors, numbers — that you would otherwise have to rediscover.";
+    readonly full: "You write the state record for a working session of any kind. The transcript you are given is about to be discarded, so what you write is the only record that remains. Follow the requested structure exactly, section for section, and keep every specific — names, paths, quoted wording, errors, numbers — that whoever continues would otherwise have to rediscover.";
+    readonly retrospective: "You are assessing your own reasoning on work that is about to be discarded. This is judgement, not a record — what happened is written up separately. Be terse, and say only what you would want to know before starting the next hour of this task.";
+};
+/**
+ * The model calls a compaction is about to make, counted before it makes them.
+ *
+ * A compaction is several sequential requests -- the summary, the
+ * retrospective, then the council -- each of which can take a minute or more
+ * on a local model. From outside it is one spinner that sits there, and a run
+ * that looked hung on 2026-09-21 was in fact four calls deep and working. The
+ * count is what makes the difference legible.
+ */
+export declare function planCompactionSteps(options: {
+    thinkingSummaryEnabled: boolean;
+    councilEnabled: boolean;
+}): number;
+/** One compaction's progress through {@link planCompactionSteps} calls. */
+export interface CompactionProgress {
+    /** Count one model call, by the stage it belongs to. */
+    step(label: string): void;
+}
+export declare function createCompactionProgress(total: number, emit: (progress: {
+    step: number;
+    stepTotal: number;
+    stepLabel: string;
+}) => void): CompactionProgress;
+export declare function runAgenticCompaction(options: {
+    context: CoreCompactionContext;
+    providerConfig: ProviderConfig;
+    summarizer?: CoreCompactionSummarizerConfig;
+    /** Overrides the built-in summary instruction; blank uses the default. */
+    summaryPrompt?: string;
+    /** Second phase: a retrospective over the reasoning being discarded. */
+    thinkingSummaryEnabled?: boolean;
+    /** Overrides the built-in retrospective instruction; blank uses the default. */
+    thinkingSummaryPrompt?: string;
+    /**
+     * Third phase: two reviewers, each holding half the transcript, correct the
+     * summary and the retrospective against it, and a synthesiser merges them.
+     *
+     * Defaults on. Costs three extra calls per compaction and cannot fail one:
+     * every path through {@link runCouncilReview} returns what it was given.
+     */
+    councilEnabled?: boolean;
+    /** Replaces the council reviewers' instruction; blank uses the default. */
+    councilCriticPrompt?: string;
+    /** Replaces the council synthesiser's instruction; blank uses the default. */
+    councilSynthesizerPrompt?: string;
+    /**
+     * Whether a recency tail survives the compaction. Defaults to true.
+     *
+     * False is a different operation, not a tighter budget: the summary becomes
+     * the whole context rather than its preface, `bounds` stops being consulted,
+     * and the prompt the caller passes has to be one written for a reader with
+     * nothing else. See {@link planFullCut}.
+     */
+    keepRecentMessages?: boolean;
+    /**
+     * Where the ledger gets the revisions holding each touched file's content.
+     *
+     * Absent means the ledger still runs and simply says nothing about files.
+     * That is the honest degradation: a wrong revision label is worse than
+     * none, because the model will try to restore it.
+     */
+    spanFor?: RevisionSpanLookup;
+    /**
+     * Whether to append the harness's record of what was called.
+     *
+     * Defaults on. Turned off with the Checkpoints switch, which owns the
+     * revision addresses the ledger quotes.
+     */
+    toolLedgerEnabled?: boolean;
+    bounds: RecencyBounds;
+    estimateMessageTokens: EstimateMessageTokens;
+    /**
+     * Measures what a transcript costs as a request, for the reported
+     * before/after only. Absent in callers that only need the cut.
+     */
+    measureReportedTokens?: MeasureReportedTokens;
+    logger?: BasicLogger;
+    /**
+     * Write the summary as the session's next turn instead of from a pasted
+     * transcript (`continuation-compaction.ts`). The caller owns it and
+     * disposes of it on every path out.
+     */
+    continuation?: CompactionContinuation;
+    /** Where this compaction's prefill is counted, on either path. */
+    meter?: CompactionMeter;
+}): Promise<CoreCompactionResult | undefined>;
+/**
+ * Which part of the context a continuation's replay covers.
+ *
+ * The writer holds the whole conversation, and with a recency tail only the
+ * part before the cut is folded -- the rest stays in the context verbatim,
+ * directly after the replay. The boundary is named by the opening words of
+ * the first message that stays, because an index means nothing to a model.
+ */
+export declare function describeReplaySpan(input: {
+    messages: readonly MessageWithMetadata[];
+    cutIndex: number;
+    keepRecentMessages: boolean;
+    pinnedMessage?: MessageWithMetadata;
+}): string;

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

@@ -0,0 +1,19 @@
+import type { BasicLogger } from "@cerebriline/shared";
+import type { CoreCompactionContext, CoreCompactionResult } from "../../types/config";
+import { type EstimateMessageTokens, type MeasureReportedTokens } from "./compaction-shared";
+/**
+ * Fold the conversation history without a summarizer model. Typed user
+ * prompts always survive. The latest typed turn keeps its newest messages
+ * verbatim within the token target, dropping only the oldest ones (the
+ * kept suffix starts at an assistant message so no tool pair is split).
+ * Older turns keep their concluding assistant answer when it fits, newest
+ * turns first. Everything else is dropped and re-surfaced as dropped-work
+ * summaries attached to the surviving prompts.
+ */
+export declare function runBasicCompaction(options: {
+    context: CoreCompactionContext;
+    estimateMessageTokens: EstimateMessageTokens;
+    /** Measures a transcript as a request, for the reported before/after only. */
+    measureReportedTokens?: MeasureReportedTokens;
+    logger?: BasicLogger;
+}): CoreCompactionResult | undefined;

package/dist/extensions/context/budget-projection/index.d.ts

@@ -0,0 +1,2 @@
+export { buildBudgetProjection, findLatestTypedUserMessageIndex, } from "./project";
+export type { BlockBudgetClass, BudgetAction, BudgetActionKind, BudgetActionReason, BudgetPath, BudgetPolicyIntent, BudgetProjectionOptions, BudgetProjectionResult, BudgetProjectionWarning, ContentBlockBudgetClassification, LiveTailHandling, } from "./types";

package/dist/extensions/context/budget-projection/project.d.ts

@@ -0,0 +1,4 @@
+import type { MessageWithMetadata } from "@cerebriline/shared";
+import type { BudgetProjectionOptions, BudgetProjectionResult } from "./types";
+export declare function findLatestTypedUserMessageIndex(messages: MessageWithMetadata[]): number;
+export declare function buildBudgetProjection(options: BudgetProjectionOptions): BudgetProjectionResult;

package/dist/extensions/context/budget-projection/types.d.ts

@@ -0,0 +1,58 @@
+import type { ContentBlock, MessageWithMetadata } from "@cerebriline/shared";
+export type BudgetPolicyIntent = "agentic_summary" | "basic_compaction_projection" | "normal_provider_request";
+export type BudgetActionKind = "truncated_text" | "dropped_block" | "dropped_message" | "preserved";
+export type BudgetActionReason = "over_budget" | "unsafe_to_truncate" | "tool_pair_boundary" | "protected_live_tail";
+export type LiveTailHandling = "included_verbatim" | "included_degraded" | "summarized_as_context" | "omitted_with_warning" | "preserved_out_of_band";
+export type BlockBudgetClass = "text" | "thinking" | "tool_use" | "tool_result" | "unsafe_binary" | "unsafe_encrypted" | "opaque";
+export interface BudgetPath {
+    messageIndex: number;
+    blockIndex?: number;
+}
+interface BaseBudgetAction {
+    path: BudgetPath;
+    originalSize: number;
+    finalSize: number;
+}
+export type BudgetMutationAction = (BaseBudgetAction & {
+    kind: "truncated_text";
+    reason: Extract<BudgetActionReason, "over_budget">;
+}) | (BaseBudgetAction & {
+    kind: "dropped_block";
+    path: Required<BudgetPath>;
+    reason: Exclude<BudgetActionReason, "protected_live_tail">;
+}) | (BaseBudgetAction & {
+    kind: "dropped_message";
+    reason: Exclude<BudgetActionReason, "protected_live_tail">;
+});
+export interface BudgetPreservedAction extends BaseBudgetAction {
+    kind: "preserved";
+    reason: Extract<BudgetActionReason, "protected_live_tail" | "tool_pair_boundary">;
+}
+export type BudgetAction = BudgetMutationAction | BudgetPreservedAction;
+export type BudgetProjectionWarningCode = "budget_impossible" | "budget_unachievable_with_protections";
+export interface BudgetProjectionWarning {
+    code: BudgetProjectionWarningCode;
+    message: string;
+    path?: BudgetPath;
+}
+export interface BudgetProjectionOptions {
+    messages: MessageWithMetadata[];
+    targetTokens: number;
+    policyIntent: BudgetPolicyIntent;
+    estimateMessageTokens: (message: MessageWithMetadata) => number;
+}
+export interface BudgetProjectionResult {
+    status: "ok" | "failed";
+    messages: MessageWithMetadata[];
+    actions: BudgetAction[];
+    liveTailHandling: LiveTailHandling;
+    estimatedTokens: number;
+    warnings: BudgetProjectionWarning[];
+}
+export interface ContentBlockBudgetClassification {
+    block: ContentBlock;
+    budgetClass: BlockBudgetClass;
+    canStringTruncate: boolean;
+    canDropWholeBlock: boolean;
+}
+export {};

package/dist/extensions/context/capped-thinking.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Continuation notes for a turn whose thinking ran out of budget.
+ *
+ * A model that hits its thinking cap does not stop reasoning — it stops
+ * mid-sentence, emits whatever tool call it can, and on the next turn starts the
+ * same reasoning from the beginning. Observed on a live session: the same
+ * ground covered a dozen times, each pass reaching "this is the final plan" and
+ * then "wait, I just realised…", each one ending at the same cap, and each one
+ * producing a differently-malformed call because the argument-writing was the
+ * part that got cut.
+ *
+ * The reasoning is in the transcript, so in principle nothing is lost. In
+ * practice seventeen thousand tokens of interrupted rambling is not something a
+ * model reads and continues from; it is something it re-derives. So when the cap
+ * fires, that turn's thinking is replaced — for the next request only — with a
+ * short note of what it settled, what it ruled out, and what the tool call it
+ * managed to make came back as. Short enough to be read, and framed as
+ * conclusions rather than as a transcript to resume.
+ */
+import type { BasicLogger, DiscardedTurnCondensation, DiscardedTurnInput, MessageWithMetadata } from "@cerebriline/shared";
+import type { CoreCompactionSummarizerConfig } from "../../types/config";
+import type { ProviderConfig } from "../../types/provider-settings";
+/**
+ * Whether this reasoning ended because the thinking budget ran out.
+ *
+ * With the session's budget message, the exact marker test the capped-thinking
+ * condenser uses. Without one, the generic admission above, in the same tail
+ * window.
+ */
+export declare function reasoningHitBudget(thinking: string, budgetMessage?: string): boolean;
+/**
+ * The output cap for the condensation call itself.
+ *
+ * A fixed cap was removed once, for a good reason: at 700 tokens against a
+ * summariser that reasons, the whole budget went into thinking and the call
+ * returned no text at all. The condensation call now asks for no reasoning, so
+ * the budget is the note -- and something has to bound it, because a small
+ * model asked for prose in its own voice can fall into repeating itself.
+ * Measured live: a note that opened "Summary-of-thought process:" and then said
+ * a variant of that line thirty times.
+ *
+ * Set well above what the note needs, so it is a stop rather than a limit the
+ * note is written to.
+ */
+/**
+ * What the note itself has to have room for, whatever else shares the budget.
+ *
+ * The instruction above asks for every call the turn made and what each one
+ * returned, so this is a working budget rather than a stop: 2,000 tokens is
+ * about 5,000 characters, and the two notes this was measured against were 624
+ * and 768. It is also the ceiling that stops a small model that has started
+ * repeating itself, which is why it stays a fixed number and not a share.
+ */
+export declare const CONDENSED_THINKING_NOTE_TOKENS = 2000;
+/**
+ * The cap the condensation request carries.
+ *
+ * Static when nothing bounds the thinking, and a ladder off the level when
+ * something does -- because the server takes the thinking allowance out of this
+ * same number *first*. `ThinkBudgetWindow` prefers `num_predict` over the
+ * context length, so the share is a share of this cap: at `max` ({4,5}) a
+ * 2,000-token cap leaves the note 400 tokens, which is less than either note
+ * measured on pandorum already used.
+ *
+ * Whether that bites depends on the provider, which is why the ladder is a
+ * guard rather than a fix for a live fault. Measured on eleven2go 2026-09-19:
+ * `think:false` returns 0 characters of thinking against 2,743 with it unset,
+ * so on Ollama the switch `resolveSummarizerConfig` sets really does hold, and
+ * on llama.cpp `enabled: false` sends `reasoning_budget_tokens: 0`. The ladder
+ * is what keeps the note whole on a provider that ignores the switch and reads
+ * only the budget -- which is what opencoti does with `reasoning_effort`.
+ *
+ * A count rather than a level is the number the user typed. It is not a share
+ * of anything, so it is added rather than solved for, and it outranks a level
+ * the same way the request path ranks the two.
+ */
+export declare function resolveCondensedThinkingOutputCap(providerConfig: Partial<ProviderConfig>, noteTokens?: number): number;
+/**
+ * Whether a note is the model repeating itself rather than writing.
+ *
+ * Degeneration is not a graceful failure here: the note goes into the thinking
+ * channel as the model's own reasoning, so thirty near-identical lines are read
+ * as thirty things it thought. No note at all is strictly better -- the turn
+ * then re-derives, which is the behaviour this feature improves on rather than
+ * one it breaks.
+ *
+ * Two cheap tests, because the shape is unmistakable: mostly-repeated lines, or
+ * one line that repeats a phrase over and over.
+ */
+export declare function isDegenerateNote(note: string): boolean;
+/**
+ * The instruction half of the condensation request.
+ *
+ * Short on purpose, and separate from the task itself, which travels as the
+ * user message: the same split the compaction summariser uses. It says what the
+ * note is for; `DEFAULT_CAPPED_THINKING_PROMPT` says what it must contain.
+ */
+export declare const CAPPED_THINKING_SYSTEM_PROMPT = "You are compressing a train of thought, in the voice of the person who was thinking it. What you write goes back into that same reasoning as its own continuation -- not as a report about it -- so write it the way thinking is written: first person, present tense, plain sentences, no headings and no lists. Keep every specific: paths, symbols, line numbers, error text, and above all what was already ruled out and why.";
+export declare const DEFAULT_CAPPED_THINKING_PROMPT = "You were reasoning about a problem and ran out of thinking budget mid-thought. Below is how far you got, and what the tool call you managed to make returned.\n\nRewrite that reasoning, compressed, as the thinking it is. It is going back into your own reasoning channel as the part you have already done, so that your next pass starts from here instead of starting over and arriving at this same point again.\n\nWrite it as thought, not as a report about thought:\n- First person, present tense, the way you were already thinking. No headings, no bullet lists, no preamble, no sign-off. Do not label it or announce what it is; just think.\n- Carry what you called and what it returned. Every tool call in this turn, by name, with the argument that mattered and what came back -- the file you read and what was at the line you were looking for, the edit you attempted and whether it applied, the command you ran and what it printed. A retrospective that omits this is the one thing the next pass cannot recover, because the results are not in front of it any more.\n- State what you have settled as settled. Do not re-derive it and do not hedge it.\n- Say what you ruled out and why, in a clause each. This is the part that stops the next pass repeating this one, and it is the part that gets dropped first if you are careless.\n- Long enough that none of the above is missing, short enough that none of it is padding. Length follows the content: a turn that made four calls and settled three questions is not a paragraph. If you find yourself restating a line you have already written, you are finished: stop.\n- End on the one question still open and the single next action, stated concretely.\n\nTwo things to keep out of it:\n- Do not copy file contents. Name the file and the line and say what you concluded about it. Quoted code goes stale the moment the file is edited, and reasoning that argues with the next tool result costs more than it saved.\n- Do not narrate the interruption. It is not part of the problem.";
+interface ToolOutcome {
+    name: string;
+    input: string;
+    result: string;
+}
+/**
+ * Why a look for a capped turn came back with nothing.
+ *
+ * Every one of these has been mistaken for "the feature is broken" at least
+ * once, and from the outside they are indistinguishable: no note, no error, no
+ * line. They are distinguishable from in here, so they are reported.
+ */
+export type CappedThinkingStandDown = "no-budget" | "no-assistant-turn" | "turn-did-not-reason" | "budget-message-absent" | "under-budget";
+export interface CappedThinkingLookup {
+    index: number;
+    reason?: CappedThinkingStandDown;
+    /** Characters of reasoning on the turn that was examined. */
+    thinkingChars?: number;
+    /** Its last few hundred characters, which is where the message would be. */
+    thinkingTail?: string;
+    /** What the estimate made of it, when the estimate is what decided. */
+    measuredTokens?: number;
+    /** Call-only assistant messages stepped over on the way back. */
+    skippedFragments?: number;
+}
+/**
+ * The most recent turn whose reasoning hit the cap, and why not when not.
+ *
+ * Only the most recent: older capped turns have already had their consequences
+ * play out in the transcript, and rewriting history the model has since acted on
+ * is a different and more dangerous idea than helping it continue.
+ */
+export declare function locateCappedThinking(messages: readonly MessageWithMetadata[], budgetTokens: number | undefined, options?: {
+    budgetMessage?: string;
+}): CappedThinkingLookup;
+/** The index alone, for callers that have nothing to report it to. */
+export declare function findCappedThinkingIndex(messages: readonly MessageWithMetadata[], budgetTokens: number | undefined, options?: {
+    budgetMessage?: string;
+}): number;
+export declare function buildCappedThinkingRequest(options: {
+    thinking: string;
+    outcomes: readonly ToolOutcome[];
+    promptTemplate?: string;
+    /** The reply the turn had begun writing before it was cut off. */
+    partialAnswer?: string;
+}): string;
+export interface CappedThinkingCondenserConfig {
+    enabled?: boolean;
+    /** The per-turn thinking allowance this session sends. */
+    budgetTokens?: number;
+    /**
+     * What the server appends to the reasoning when that allowance runs out,
+     * when the session knows it — configured by Cline, or reported by Ollama as
+     * the model's own. Absent for a model that has none, which is the case the
+     * measurement exists for.
+     */
+    budgetMessage?: string;
+    promptTemplate?: string;
+    /** Absent when no provider is resolved yet; the condenser then stands down. */
+    providerConfig?: ProviderConfig;
+    summarizer?: CoreCompactionSummarizerConfig;
+    logger?: BasicLogger;
+}
+type PrepareTurnResult = {
+    messages?: readonly MessageWithMetadata[];
+} | undefined;
+type PrepareTurn = (context: never) => PrepareTurnResult | Promise<PrepareTurnResult>;
+/**
+ * Condense reasoning that is about to be thrown away rather than sent again.
+ *
+ * The transcript is the wrong place to catch the turn this feature was built
+ * for. A think only ends *at* the budget message when the model had no room to
+ * continue -- which means the same turn also ends at the output cap with no
+ * tool call, and the agent loop discards those before they reach the history.
+ * Measured across a full session: every capped turn was discarded, the detector
+ * re-examined the previous uncapped one, and the condenser stood down on each
+ * of them, correctly and uselessly. The reasoning went in the bin with the
+ * turn, and the retry started the same analysis from nothing.
+ *
+ * So the loop hands the reasoning here on its way to being dropped. The
+ * truncated message still never re-enters the transcript; only the note does.
+ *
+ * Returns `undefined` when there is nothing to condense with, so a caller can
+ * tell "off" from "produced nothing".
+ */
+export declare function createCappedThinkingNoteWriter(config: CappedThinkingCondenserConfig): ((input: DiscardedTurnInput) => Promise<DiscardedTurnCondensation>) | undefined;
+/**
+ * Rewrite the capped turn's reasoning, then hand off to the rest of the
+ * pipeline.
+ *
+ * Ahead of compaction rather than behind it, because a condensed turn is a
+ * smaller turn: whatever compaction then decides, it decides about a transcript
+ * that is not carrying seventeen thousand tokens of abandoned reasoning.
+ */
+export declare function createCappedThinkingPrepareTurn<T extends PrepareTurn>(inner: T | undefined, config: CappedThinkingCondenserConfig): T | undefined;
+export {};

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

@@ -0,0 +1,27 @@
+/**
+ * Why a compaction ran, in the four words a reader of an agent's row can use.
+ *
+ * The notice's `kind` already separates manual from automatic from overflow
+ * recovery, but "automatic" folds two different stories together: an agent
+ * that filled its own window, and one that was compacted because the server
+ * was short of cells for everybody else (global KV pressure). With every agent
+ * given the same 64k window, those are the two answers to "why did this one
+ * compact" -- so the notice names which.
+ *
+ * Precedence: a request that crossed its own threshold is "auto" even when the
+ * server was also under pressure -- it would have compacted anyway. Pressure
+ * is named only when it is the reason the compaction happened at all.
+ */
+export type CompactionCause = "auto" | "pressure" | "overflow" | "manual";
+export declare const COMPACTION_CAUSES: readonly CompactionCause[];
+export declare function resolveCompactionCause(input: {
+    mode: "auto" | "manual" | "overflow_recovery";
+    /** The provider reported this session's request over its window. */
+    contextOverflow: boolean;
+    /** The request crossed this session's own trigger threshold. */
+    overOwnThreshold: boolean;
+    /** The window-bound output cap fell below what a reply needs. */
+    outputCapStarved: boolean;
+    /** The engine's pressure signals: PolyKV capacity or global KV pressure. */
+    pressure: boolean;
+}): CompactionCause;

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

@@ -0,0 +1,65 @@
+/**
+ * What the transcript said before a compaction replaced it.
+ *
+ * Compaction is the one operation in this runtime that destroys its own input.
+ * Every other thing the model does to state is recoverable — an edit has a
+ * revision, a transaction has a base snapshot, a file has the disk — and the
+ * transcript had nothing. If the summary came back wrong, or thin, or about the
+ * wrong half of the session, the turns it stood for were already gone and the
+ * only evidence that anything had been lost was the model's later behaviour.
+ *
+ * That is tolerable while a recency tail survives, because the tail is a
+ * fallback in itself. It stops being tolerable the moment the summary *is* the
+ * context: a bad no-tail compaction is terminal, and this is the configuration
+ * an experiment elsewhere reportedly had to withdraw.
+ *
+ * So the messages are kept. In memory, per session, bounded, and never on the
+ * wire — a journal that reached the model would be the transcript it exists to
+ * replace.
+ *
+ * **Why not disk.** A transcript holds file contents, command output, and
+ * whatever the user typed; writing it somewhere durable is a new place for that
+ * to leak from and a new thing to clean up. The lifetime that matters is the
+ * session, and the session lives in memory.
+ *
+ * **Why bounded, and bounded by entries rather than bytes.** The entries are
+ * whole transcripts, so the cap is small: two. That is what `restore` needs —
+ * the state before the compaction that just ran, and the one before that, so a
+ * generation-2 summary built on a bad generation-1 summary can be unwound past
+ * both. Anything older is a transcript the session has already worked from for
+ * several turns, and restoring to it would discard more than it recovered.
+ */
+import type { MessageWithMetadata } from "@cerebriline/shared";
+/** One compaction, and what it replaced. */
+export interface CompactionJournalEntry {
+    /** 1-based, matching the summary message's own generation. */
+    generation: number;
+    /** The transcript as it stood before this compaction ran. */
+    before: readonly MessageWithMetadata[];
+    /** Messages it produced, for reporting what the trade actually was. */
+    afterMessageCount: number;
+    /** Which strategy wrote it, so a restore can say what it is undoing. */
+    strategy: string;
+    /** Whether a recency tail survived. A no-tail entry is the risky one. */
+    keptRecentMessages: boolean;
+    at: number;
+}
+/** How many pre-compaction transcripts are held. See the module comment. */
+export declare const COMPACTION_JOURNAL_DEPTH = 2;
+export interface CompactionJournal {
+    record(entry: Omit<CompactionJournalEntry, "at">): void;
+    /** The most recent entry, or the one at `generation` when given. */
+    latest(generation?: number): CompactionJournalEntry | undefined;
+    /**
+     * The transcript to go back to, undoing the last compaction.
+     *
+     * Returns the messages rather than applying them: what to do with a restored
+     * transcript is the caller's decision — a host may want to confirm it, and
+     * the runtime may want to re-run compaction with different settings rather
+     * than simply put the oversized transcript back.
+     */
+    restore(generation?: number): readonly MessageWithMetadata[] | undefined;
+    entries(): readonly CompactionJournalEntry[];
+    clear(): void;
+}
+export declare function createCompactionJournal(depth?: number): CompactionJournal;

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

@@ -0,0 +1,72 @@
+/**
+ * The revision log, as compaction needs to see it.
+ *
+ * Two jobs, and they are the two halves of the same bargain. The ledger a
+ * summary carries says "the content is not here, it is at `#4`", which is only
+ * worth writing if `#4` is still there when the model reads it; and the log
+ * only knows which histories are still addressable because compaction tells it
+ * what the summary it just wrote names. Neither half works alone.
+ *
+ * A narrow port rather than the log itself, for the reason `forgetReads` is
+ * one: the context extension has no business importing the atomic runtime, and
+ * a host that has no revision log at all should be able to leave this out and
+ * still compact. Absent, ledger entries say nothing about files -- which is
+ * honest, since a wrong revision number is worse than none.
+ */
+export interface CompactionRevisions {
+    /**
+     * The revisions held for a file, as a span like `#1–#7`, or nothing when
+     * the log does not track it. Fed straight to the tool ledger.
+     */
+    spanFor(filePath: string): string | undefined;
+    /** Every file the log currently holds a history for, as absolute paths. */
+    tracked(): readonly string[];
+    /**
+     * Close the compaction span and release what the next one cannot use.
+     * `keep` is the whitelist — see `RevisionLog.noteCompaction`.
+     */
+    noteCompaction(keep?: Iterable<string>): number;
+}
+/**
+ * Which tracked files the text still refers to.
+ *
+ * The whitelist that survives eviction. A tracked file counts as named if its
+ * **basename** appears in the text at a boundary, and that is the whole rule:
+ * the log's keys are absolute because tools resolve before they record, while
+ * a summary is prose and names a file however the model wrote it — absolute,
+ * workspace-relative, or bare in a sentence. Matching the longest tail of the
+ * path first sounds stricter and is not: any longer tail that appears puts a
+ * separator immediately before the basename, which is a boundary, so the
+ * basename matches in every case the longer one does. The extra comparisons
+ * decide nothing, and a rule that looks stricter than it is invites the reader
+ * to trust a precision it does not have.
+ *
+ * It follows that two files sharing a basename are kept or dropped together.
+ * That is the safe direction: a file kept that nothing names costs bytes the
+ * total cap already bounds and goes at the next compaction anyway, while a
+ * file dropped that the summary does name turns `#4` into an address the model
+ * will try to restore and cannot — the failure this mechanism exists to avoid.
+ *
+ * The one thing it will not do is match inside a word. `session.ts` found in
+ * `my-session.ts` is a different file, and a rule that cannot tell them apart
+ * keeps everything and decides nothing.
+ */
+export declare function mentionedPaths(text: string, tracked: readonly string[]): ReadonlySet<string>;
+/**
+ * Close the compaction span, keeping the histories the new transcript can
+ * still reach.
+ *
+ * The whitelist is read off the compacted messages themselves, which is both
+ * halves of what the user asked for in one rule: after a compaction those
+ * messages *are* the summary plus the retained tail, so scanning them covers
+ * the tail when there is one and needs no special case when there is not.
+ *
+ * The messages are scanned as JSON rather than as rendered text, deliberately.
+ * A path can be named in the summary prose, in the tool ledger appended after
+ * it, or in a tool call still sitting in the tail, and those are three
+ * different shapes; their serialisation is the one place all three are
+ * visible at once.
+ */
+export declare function releaseUnreachableRevisions(revisions: CompactionRevisions | undefined, messages: readonly unknown[], logger?: {
+    log(message: string, meta?: Record<string, unknown>): void;
+}): number;