@cerebriline/core 4.100.240

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

@@ -0,0 +1,161 @@
+import { type PrepareTurnUsage } from "@cerebriline/shared";
+import { type SessionCompactionState } from "../../session/models/session-compaction";
+import type { CoreCompactionContext, CoreCompactionMode, CoreSessionConfig } from "../../types/config";
+import { type CompactionJournal } from "./compaction-journal";
+export interface ContextPipelinePrepareTurnInput {
+    agentId: string;
+    conversationId: string;
+    parentAgentId: string | null;
+    iteration: number;
+    messages: CoreCompactionContext["messages"];
+    apiMessages: CoreCompactionContext["messages"];
+    /**
+     * Turns the wire request opens with that compaction must not see: a
+     * pooled sub-agent's shared head (`pinConversationHead`). Taken off
+     * `messages` and `apiMessages` so nothing folds or rewrites them, and put
+     * back in front wherever the request itself is rebuilt or measured -- the
+     * continuation writer continues the conversation the slot holds, head
+     * included.
+     */
+    pinnedHead?: CoreCompactionContext["messages"];
+    abortSignal: AbortSignal;
+    systemPrompt: string;
+    tools: unknown[];
+    model: CoreCompactionContext["model"];
+    /**
+     * Set by the runtime when the provider rejected the previous request as
+     * exceeding the model's context window. Forces a compaction regardless of
+     * the token-estimate trigger (the estimate just proved wrong) and uses the
+     * deterministic basic strategy — recovery must not depend on another
+     * successful LLM request.
+     */
+    overflowRecovery?: boolean;
+    /**
+     * Someone asked for this compaction -- the lead, for a delegated agent
+     * (`compact_agents`). Runs as a manual compaction on this turn.
+     */
+    compactionRequested?: boolean;
+    emitStatusNotice?: (message: string, metadata?: Record<string, unknown>) => void;
+    /**
+     * Count what this preparation spent on the model. Every call of a
+     * compaction goes here, whether or not it produced a transcript: the
+     * agent's row read 4,055 tokens out after 28 compactions whose summaries
+     * and critics it never counted (swarm czbnh, 2026-09-29).
+     */
+    reportUsage?: (usage: PrepareTurnUsage) => void;
+}
+export interface ContextPipelinePrepareTurnResult {
+    messages: CoreCompactionContext["messages"];
+    systemPrompt?: string;
+}
+export type ContextPipelinePrepareTurn = (context: ContextPipelinePrepareTurnInput) => Promise<ContextPipelinePrepareTurnResult | undefined>;
+export interface ContextCompactionPrepareTurnOptions {
+    mode?: CoreCompactionMode;
+    manualTargetRatio?: number;
+    /**
+     * Where the pre-compaction transcript is kept, so a compaction can be undone.
+     *
+     * Supplied by a caller that wants to reach it — a host offering an "undo
+     * compaction" action, or a test. Omitted, one is created internally and the
+     * transcript is still kept; the journal is never optional, only its
+     * visibility is. See {@link createCompactionJournal}.
+     */
+    journal?: CompactionJournal;
+}
+/**
+ * The share of the *content* a compaction aims to leave behind.
+ *
+ * Of the content, not of the window. The system prompt, the tool schemas and
+ * any MCP tools are paid before a single message exists, and compaction cannot
+ * touch one token of them -- measured on pandorum 2026-09-19, 21,000-24,000
+ * tokens of a 65,536-token window, about a third of it gone before the
+ * conversation starts. (The system prompt is 1,607 of that; the rest is
+ * schemas.)
+ *
+ * Taking the share from the window made the target incoherent once the fixed
+ * price grew: a quarter of 65,536 is 16,384, below the price itself, so the
+ * transcript budget floored at nothing and every compaction became a full one
+ * whatever the tail setting said. Taking it from what is left asks the
+ * question that was always meant -- how much conversation may survive -- and
+ * has an answer for any window.
+ */
+export declare const COMPACTION_TARGET_CONTENT_SHARE = 0.25;
+/**
+ * How many tokens of transcript a compaction should leave.
+ *
+ * `maxInputTokens` is the whole window and `requestOverheadTokens` is what is
+ * spent before any message; the difference is the only part a compaction can
+ * spend, and the share is taken from that.
+ */
+export declare function resolveMessageTargetTokens(input: {
+    maxInputTokens: number;
+    requestOverheadTokens: number;
+    share?: number;
+}): number;
+/**
+ * Put an estimate on the same scale as the provider's own count.
+ *
+ * `estimate` and `estimateOfObserved` measure the same transcript the same way;
+ * `observed` is what the provider charged for it. The ratio between the last
+ * two is this session's standing estimator error, and applying it to the first
+ * is what makes a "before" and an "after" comparable. Falls back to the raw
+ * estimate when there is nothing to calibrate against -- the first request of a
+ * session, before any response has been counted.
+ */
+/**
+ * The transcript budget, expressed in the units the planner measures in.
+ *
+ * Two scales meet here and used not to. `shouldCompact` compares
+ * `triggerInputTokens` -- the provider's own count of the last request, when
+ * there is one -- against the threshold. Everything after it is an estimate:
+ * `requestOverheadTokens` and the `estimateMessageTokens` sum the cut is
+ * planned with. Subtracting an estimated overhead from a target derived from
+ * the real window mixes the two, and the error goes entirely one way when the
+ * estimator under-reads.
+ *
+ * Measured on pandorum 2026-09-19, iteration 10: ollama counted the request at
+ * 58,328 and the estimator read it as 36,826. The trigger fired correctly on
+ * 58,328 against 57,536. The target was then 57,536 x 0.7 = 40,275, less an
+ * estimated overhead of 23,796, giving 16,479 -- against a transcript the
+ * planner measured at 13,045. The compaction was asked to shrink something to
+ * a size it was already 3,434 tokens under, cut two messages, and the next
+ * turn overflowed and forced a real one. Two compactions, one file read
+ * between them.
+ *
+ * Scaling the request target by `estimate / observed` before the subtraction
+ * is what makes the two halves comparable. It is a no-op when the estimator
+ * agrees with the provider, and a no-op when there is no observation to
+ * calibrate against.
+ *
+ * **One-directional: it may tighten the target and never loosen it.** The
+ * correction exists because an under-reading estimator leaves a target the
+ * transcript is already past. An over-reading one is the opposite case, and
+ * there the plain subtraction is already tight -- inflating it would hand back
+ * a budget bigger than the trigger that just fired was asking for, and the
+ * compaction would find nothing to do. That is not hypothetical: it is the
+ * starved-output-cap path, where a thin cap forces a compaction on a
+ * transcript the estimator reads at 2.7x the provider's count, and a
+ * two-directional scale suppresses it entirely.
+ */
+export declare function resolveMessageTargetOnTriggerScale(input: {
+    requestTargetTokens: number;
+    requestOverheadTokens: number;
+    requestInputTokens: number;
+    triggerInputTokens: number | undefined;
+}): number;
+export declare function scaleEstimateToObserved(estimate: number, estimateOfObserved: number, observed: number | undefined): number;
+/** Test seam: the latch is process-wide, so a suite has to be able to clear it. */
+export declare function resetStarvedOutputCapLatch(): void;
+export declare function createContextCompactionPrepareTurn(config: Pick<CoreSessionConfig, "providerConfig" | "providerId" | "modelId" | "compaction" | "logger" | "telemetry" | "sessionId"> & Partial<Pick<CoreSessionConfig, "thinking" | "reasoningEffort" | "thinkingBudgetTokens" | "temperature">>, options?: ContextCompactionPrepareTurnOptions): ((context: ContextPipelinePrepareTurnInput) => Promise<ContextPipelinePrepareTurnResult | undefined>) | undefined;
+export declare function createCompactionStateAwarePrepareTurn(input: {
+    compact?: ContextPipelinePrepareTurn;
+    getState?: () => SessionCompactionState | undefined;
+    /**
+     * Persist a freshly-computed compaction state. `sourceMessages` are the
+     * exact canonical messages the state's source-prefix hash was computed
+     * over; hosts must validate projection against these rather than a
+     * separately derived transcript, which can legally differ mid-turn and
+     * spuriously reject the write.
+     */
+    saveState?: (state: SessionCompactionState, sourceMessages: CoreCompactionContext["messages"]) => void | Promise<void>;
+}): ContextPipelinePrepareTurn;

package/dist/extensions/context/context-minimum-warning.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Say so, once, when a session's window cannot hold one turn.
+ *
+ * The settings panel warns where a window is typed; a CLI user has no panel,
+ * and a window set by flag or `providers.json` below the fixed price plus the
+ * output cap reaches the first request unannounced -- to be cut short or
+ * refused there. This is the same arithmetic (`@cerebriline/shared`'s
+ * `resolveContextMinimumForWindow`), fed by what the compaction pipeline has
+ * just measured, logged at the session's first turn.
+ */
+/** Test seam: the once-per-session memory outlives any one test. */
+export declare function resetContextMinimumWarnings(): void;
+export declare function warnIfWindowBelowMinimum(input: {
+    sessionId: string | undefined;
+    logger: {
+        log?: (message: string, meta?: {
+            severity?: "warn";
+        }) => void;
+    } | undefined;
+    contextWindow: number | undefined;
+    systemPromptTokens?: number;
+    toolSchemaTokens?: number;
+    mcpToolSchemaTokens?: number;
+    /** The cap the session sends; resolved from the budget when absent. */
+    outputCapTokens?: number;
+    modelMaxOutputTokens?: number;
+}): void;

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

@@ -0,0 +1,260 @@
+/**
+ * Compaction as a continuation of the session.
+ *
+ * The summarizer used to be a stranger to the conversation it summarised: its
+ * own system prompt, no tools, and the transcript pasted in as text. Every
+ * compaction call therefore prefilled the whole transcript again -- the writer,
+ * each critic, the synthesizer -- on the server whose cells had just run out.
+ * On opencoti each of those calls also booked a window of its own.
+ *
+ * Here the writer is the conversation's next turn: the agent's own system
+ * prompt, tools and messages, and one more user message asking for the
+ * replay. A server with a prompt cache prefills that message and nothing
+ * else. On opencoti with pools the rest of the user's design follows
+ * (mail #320):
+ *
+ * 1. **Freeze** the session's resident stream as pool P (`from_session`,
+ *    pinned).
+ * 2. The **writer** continues the session in its own slot.
+ * 3. **P'** = P + the writer's instruction and summary (`fork from_session`).
+ * 4. The **critics** attach P' concurrently, each paying for its instruction
+ *    and its answer only.
+ * 5. **Release**, leaves first: the critics' sessions, P', P, then the
+ *    session's own cells.
+ * 6. The **synthesizer** joins the halves on an exact-size booking of its own,
+ *    which is closed as soon as it answers.
+ *
+ * The session then continues as P0 (the shared system+tools prefix it was
+ * already attached to) plus the replay: nothing is re-rooted, because the
+ * prefix pools never held the transcript.
+ *
+ * Without pools -- Ollama, llama.cpp, an opencoti that does not advertise
+ * them, or one that is refusing bookings right now -- steps 2 and 4 still run
+ * as plain continuations in the session's own slot, one critic after the
+ * other so the second finds the first's prefix still resident.
+ *
+ * Two rules hold throughout. **Nothing books more than it needs**: a critic on
+ * an owned pool is a worker charged its instruction and answer, a critic on an
+ * unowned pool and the synthesizer book exactly their request and output, and
+ * a session with no booking of its own gives its writer an exact one. **Every
+ * failure releases what was created** ({@link CompactionContinuation.dispose}),
+ * and a continuation that cannot write a summary hands the compaction back to
+ * the transcript-as-text path it replaced.
+ */
+import { type BasicLogger, type MessageWithMetadata, type ProviderErrorClass, type RequestTimings } from "@cerebriline/shared";
+import type { ProviderConfig } from "../../types/provider-settings";
+/** Which of the two shapes a compaction ran as. */
+export type ContinuationPath = "pooled" | "continuation";
+/** An exact booking for a request of `chars` characters and `output` tokens. */
+export declare function exactBooking(chars: number, output: number): number;
+/** One model call, as a continuation or as a request of its own. */
+export interface ContinuationCall {
+    purpose: "writer" | "critic" | "retrospective" | "synthesizer";
+    providerConfig: ProviderConfig;
+    /** The host session id the model is built for (telemetry, affinity). */
+    sessionId?: string;
+    systemPrompt: string;
+    messages: readonly MessageWithMetadata[];
+    tools: readonly unknown[];
+    maxTokens: number;
+    /** `none` keeps the tools in the prompt and asks for prose. */
+    toolChoice?: "none";
+    reasoning?: ContinuationReasoning;
+    abortSignal?: AbortSignal;
+}
+export interface ContinuationReasoning {
+    thinking?: boolean;
+    reasoningEffort?: string;
+    thinkingBudgetTokens?: number;
+    temperature?: number;
+}
+export interface ContinuationCallResult {
+    text: string;
+    reasoningChars: number;
+    incompleteReason?: string;
+    timings?: RequestTimings;
+    /** What the call spent, as the provider reported it. */
+    usage?: CompactionCallUsage;
+}
+/** One call's tokens, as a provider reports them for billing. */
+export interface CompactionCallUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+    totalCost?: number;
+}
+/** The one seam every call goes through; tests replace it. */
+export type ContinuationModel = (call: ContinuationCall, logger?: BasicLogger) => Promise<ContinuationCallResult>;
+/** A turn that failed at the model, with what the provider said about it. */
+export declare class ContinuationCallError extends Error {
+    readonly errorClass?: ProviderErrorClass | undefined;
+    constructor(message: string, errorClass?: ProviderErrorClass | undefined);
+}
+/**
+ * The call, through the same model path the agent's own turns take.
+ *
+ * `createAgentModelFromConfig` and `messagesToAgentMessages` are what the
+ * session runtime uses for the conversation, so the request this builds is
+ * rendered by the same conversion, the same environment hoisting and the same
+ * vendor fetch as the turn before it. The handler path the summarizer used
+ * converts messages with a different function, and a prefix is only shared if
+ * the two renderings agree byte for byte.
+ */
+export declare const defaultContinuationModel: ContinuationModel;
+/** Two reports of usage as one. A provider may report a call in parts. */
+export declare function addCallUsage(into: CompactionCallUsage | undefined, next: CompactionCallUsage | undefined): CompactionCallUsage | undefined;
+/** Prompt tokens the engine actually evaluated for one call. */
+export declare function evaluatedPromptTokens(timings: RequestTimings | undefined): number | undefined;
+/**
+ * What one compaction cost, for the line it logs and the numbers a gate
+ * compares. Filled by both paths: the continuation from the engine's own
+ * timings, the transcript-as-text path from the usage it reports.
+ */
+export interface CompactionMeter {
+    /** Prompt tokens evaluated across every call of the compaction. */
+    prefillTokens: number;
+    /**
+     * What every call of the compaction spent, as the providers reported it:
+     * the prompt sent (cached or not) and what was written. Not the prefill
+     * above -- that is what the engine had to evaluate -- but what a per-token
+     * price is charged on, and what the agent's own totals count.
+     */
+    usage?: CompactionCallUsage;
+    /**
+     * Told each call's usage as the call finishes, so the agent it ran for
+     * counts it -- live, and whether or not the compaction then succeeds.
+     */
+    onUsage?: (usage: CompactionCallUsage) => void;
+    /** Calls that reported nothing to count. */
+    unmeasuredCalls: number;
+    calls: number;
+    /** Extra cells booked at the compaction's peak, beyond the session's own. */
+    peakBookedCells: number;
+    /** The writer's `cache_n`, and what it was expected to reach. */
+    writerCacheN?: number;
+    writerExpectedCacheN?: number;
+    /** Each critic's `cache_n`, and what P' made possible. */
+    criticCacheN: number[];
+    criticExpectedCacheN?: number;
+    /** `cache_n` of the retrospective and synthesizer when they continued P'. */
+    siblingCacheN: number[];
+    /** Engine objects released, and those a release failed for. */
+    released: string[];
+    leaked: string[];
+    /** Decisions taken on the way, for the log line. */
+    notes: string[];
+}
+export declare function createCompactionMeter(onUsage?: (usage: CompactionCallUsage) => void): CompactionMeter;
+export declare function meterCall(meter: CompactionMeter | undefined, timings: RequestTimings | undefined, fallbackPromptTokens?: number, usage?: CompactionCallUsage): void;
+/** The half-plan for the council, decided once the writer's summary exists. */
+export interface CriticPlan {
+    critics: "concurrent" | "serial" | "skip";
+    reason: string;
+}
+/**
+ * One compaction's continuation: the session it continues, the pools it
+ * made, and every session it opened -- so all of it can be released on any
+ * path out.
+ */
+export interface CompactionContinuation {
+    readonly path: ContinuationPath;
+    readonly reason: string;
+    readonly meter: CompactionMeter;
+    /**
+     * The writer: the session's next turn, with `instruction` as the user
+     * message. Called again for a retry; the last call is the one the critics
+     * continue from.
+     */
+    write(instruction: string, maxTokens: number): Promise<ContinuationCallResult>;
+    /** Freeze P' after the last writer attempt, and plan the critics. */
+    afterWriter(summaryChars: number, criticMaxTokens: number): Promise<CriticPlan>;
+    /** One critic, as a continuation of P' (or of the session, unpooled). */
+    critic(half: "first" | "second", systemPrompt: string, request: string, maxTokens: number): Promise<string>;
+    /**
+     * Room on P' for the retrospective or the synthesizer, reserved now; or
+     * `undefined` when the call does not fit there, and must wait for the
+     * release and run on a booking of its own. Only on an engine that
+     * continues a pool token-exact (`pool_continue_v1`): anywhere else the
+     * call's own reasoning fields would render the prefix differently and it
+     * would share nothing.
+     */
+    reservePPrime(purpose: "retrospective" | "synthesizer", chars: number, maxTokens: number): PPrimeReservation | undefined;
+    /**
+     * The retrospective or the synthesizer: as a continuation of P' with a
+     * reservation that still holds, otherwise on an exact booking of its own
+     * where the engine books.
+     */
+    fresh(purpose: "retrospective" | "synthesizer", systemPrompt: string, request: string, maxTokens: number, providerConfig: ProviderConfig, reservation?: PPrimeReservation): Promise<ContinuationCallResult>;
+    /**
+     * Give the session's cells back: the critics, P', P, then the session's
+     * own slot. Idempotent; run before the synthesizer, and again by
+     * {@link dispose} on any path out.
+     */
+    release(): Promise<void>;
+    /** Release everything this continuation created. Idempotent. */
+    dispose(): Promise<void>;
+}
+/** Room on P' held for one call (`reservePPrime`). */
+export interface PPrimeReservation {
+    readonly purpose: "retrospective" | "synthesizer";
+    /** Cells charged against the owner's room while the call runs. */
+    readonly cells: number;
+}
+export interface PrepareContinuationInput {
+    /** The session's provider config: the connection its turns go out on. */
+    providerConfig: ProviderConfig;
+    /** The host's session id: the key of the pool registry and the wire id. */
+    sessionId: string | undefined;
+    systemPrompt: string;
+    tools: readonly unknown[];
+    /** The messages the agent's next request would carry. */
+    apiMessages: readonly MessageWithMetadata[];
+    /** The window the session holds (the granted one where it is smaller). */
+    contextWindow: number | undefined;
+    /** The provider's count of the last request, or the estimate. */
+    requestTokens: number;
+    /** The last request's own prompt count, when one was measured. */
+    observedRequestTokens?: number;
+    reasoning: ContinuationReasoning;
+    /** A summarizer model of its own is configured: it cannot continue this one. */
+    separateSummarizer: boolean;
+    /** The server is refusing bookings: no new ones, no pools. */
+    kvPressureActive: boolean;
+    overflowRecovery: boolean;
+    abortSignal?: AbortSignal;
+    logger?: BasicLogger;
+    /** Test seam for the model calls. */
+    model?: ContinuationModel;
+    /** Test seam for the waits between refusals. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** A number unique within the process, for the compaction's session ids. */
+    serial?: number;
+    /**
+     * The compaction's meter: shared with a transcript-as-text fallback, so
+     * the one line it logs counts both.
+     */
+    meter?: CompactionMeter;
+}
+/** Whether a failed call is the server saying "not now". */
+export declare function isInfraFault(error: unknown): boolean;
+/**
+ * Whether compaction on this connection can run as a continuation, and in
+ * which shape. `undefined` continuation with the reason when it cannot.
+ */
+export declare function prepareCompactionContinuation(input: PrepareContinuationInput): Promise<{
+    continuation?: CompactionContinuation;
+    reason: string;
+}>;
+/**
+ * The line every compaction logs: which path it took and why, what it
+ * prefilled, how much of the session's cache it reused, what it booked, how
+ * long it took.
+ */
+export declare function describeCompactionRun(input: {
+    path: ContinuationPath | "fallback";
+    reason: string;
+    meter: CompactionMeter;
+    durationMs: number;
+    sessionWindow?: number;
+}): string;