@cerebriline/core 4.100.240

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

@@ -0,0 +1,262 @@
+/**
+ * A second opinion on a compaction, before it replaces the transcript.
+ *
+ * A summary is written once, from the whole of a transcript, by a model that
+ * has just spent its budget doing the work being summarised. It is the only
+ * artifact in the system that is never checked against the thing it describes
+ * -- and it is also the one artifact that, once written, *is* the thing it
+ * describes. Every later turn reads it and never the conversation again.
+ *
+ * Measured on pandorum: summaries that reported a checker run as a success
+ * when it had returned `ok:false` three times, that paraphrased the
+ * instruction they had been asked to quote, and that narrated in the past
+ * tense a prompt had asked three times to be present. None of these are
+ * failures of intelligence. They are failures of a single pass over more
+ * material than fits comfortably in one.
+ *
+ * So the summary is reviewed the way a council reviews a proposal. The
+ * transcript is cut in half; each half is given to a fresh reviewer along with
+ * the summary and the retrospective, and asked what is missing, what is
+ * contradicted and what is misquoted **in that half**. A synthesiser then
+ * glues the two corrected versions back into one.
+ *
+ * Three properties the shape is chosen for:
+ *
+ * - **Each reviewer sees half the evidence and all of the claim.** That is the
+ *   point: a reviewer holding half a transcript has room to actually read it,
+ *   where the original pass did not. It is also the danger, and the reviewer
+ *   prompt spends most of its words on it -- a reviewer who deletes what its
+ *   half does not cover turns a review into a truncation.
+ * - **The reviewers are parallel, not chained.** Both correct the *original*.
+ *   Chaining would make the second reviewer's job "review a text the first one
+ *   already changed", and its corrections would compound rather than converge.
+ * - **Nothing here may fail the compaction.** Every step falls back to what it
+ *   was given. A council that cannot run leaves an unreviewed summary, which
+ *   is exactly what shipped before it existed.
+ */
+import type { BasicLogger, MessageWithMetadata } from "@cerebriline/shared";
+/** What a reviewer and the synthesiser are told they are. */
+export declare const COUNCIL_SYSTEM_PROMPTS: {
+    readonly critic: "You are rewriting one half of an account of your own work, with the record of that work in front of you. Correct what the record contradicts, add what it shows missing, fix every quotation against it, and improve the prose where it has drifted out of voice. You return your half and only your half: another writer is rewriting the other one, and the two will be joined into a single continuous replay.";
+    readonly synthesizer: "You are joining two independently rewritten halves of one replay into a single continuous piece, and revising a retrospective against the result. Each half was rewritten by someone holding the whole record but owning only that half, so both are grounded — and both could be wrong about the other's territory. Your answer is the finished text, not an account of how you produced it.";
+};
+/**
+ * What the replay's writer is told when a council will review it: where to
+ * put the line that splits it in two.
+ *
+ * Its own prompt rather than a paragraph of the replay prompt, where it used
+ * to live: it was sent with the council switched off, when nothing reads the
+ * marker, and never with the full-compaction prompt, so a full compaction
+ * reviewed by the council always fell back to a guessed split. It is appended
+ * to whichever writer prompt runs, and only while the council is on.
+ */
+export declare const DEFAULT_COUNCIL_WRITER_PROMPT = "## Mark the halfway point\n\nExactly once, put a line containing `<<<HALFWAY>>>` and nothing else, at the\npoint where you are about half way through the work you are describing.\n\nMeasure the half by the **work**, not by the words: the marker goes where the\nfirst half of what happened ends and the second half begins. It must sit on a\nboundary between steps \u2014 after one step and its outcome are complete, never\ninside a step, never between a call and what it returned, and never inside a\nfenced block.\n\nNothing else about the replay changes. It is one continuous piece of prose that\nhappens to carry a marker; do not write headings for the halves, do not\nsummarise each half, and do not refer to the marker in the text.";
+/**
+ * The reviewer's instruction, as a template.
+ *
+ * `{{half}}`, `{{other_half}}` and `{{half_length}}` are substituted; the two
+ * halves, the numbered record and the transcript are appended by the harness
+ * after it, so a custom prompt cannot drop the evidence it is asked to check.
+ */
+export declare const DEFAULT_COUNCIL_CRITIC_PROMPT = "You wrote the replay below from the transcript that follows it. The replay has been cut in two and you own the **{{half}} half**. Someone else is rewriting the {{other_half}} half from the same transcript, at the same time, and the two halves will be joined back into one continuous replay.\n\nSo: **return the {{half}} half only.** Do not return the {{other_half}} half, do not restate it, do not summarise it, do not lead into it or round it off. It is shown to you for one reason only \u2014 so you can check your own half against it and see where your half ends. Anything of it you reproduce will appear twice in the joined replay, once from you and once from the writer who owns it.\n\n**The user's own words stay.** If your half quotes what the user asked for, that quotation is the most load-bearing text in it \u2014 it is the only place the instruction survives at all once the transcript is gone. Keep it word for word. Do not paraphrase it, do not shorten it, and never drop it to make room.\n\n**You are revising a draft, not writing one.** Start from the text below and change what is wrong with it. Do not re-derive your half from the transcript and write it out afresh: a step that is already right is already done, and rewriting it from scratch is how a correct sentence becomes a different, shorter, wronger one.\n\n**About the `[#7]` marks.** Those are citations, not step numbers and not part of the prose. Each one names a call in the numbered record, and the harness replaces it with that call before anyone reads this. So:\n\n- **Keep every citation your half already has, exactly as it is, where it is.** Do not renumber them, do not turn them into a numbered list, do not write them out as \"Step 7\".\n- **Only cite a number that appears in the record.** If your half describes something with no call behind it, leave it uncited \u2014 inventing a number attaches your sentence to somebody else's call, or to nothing.\n- If the transcript shows a call your half never mentions, add the step and cite its number from the record.\n\nWhat to change in your half:\n\n- **Something that happened and is missing.** A call that was made, an answer that came back, an instruction that was given, a conclusion that was reached, an approach that was ruled out. Add it.\n- **Something the transcript contradicts.** A call reported as succeeding that returned an error; a file said to have been read that was refused; a count, a line number or a filename that does not match. Correct it to what the transcript shows.\n- **Something quoted that does not match.** The user's own words, error text, identifiers, paths and numbers have to be character for character what the transcript holds.\n- **Something the {{other_half}} half contradicts.** Ground your half against it: the two are one account of one session, and a fact stated one way in your half and another way there is a fact to settle from the transcript.\n- **Prose that has drifted.** Fix it. If a step is written as a report of itself \u2014 past tense, or narrated as something finished \u2014 rewrite it as the step and its outcome. First person, present continuous, the voice of someone picking the work back up rather than recounting it.\n\nWrite every step as the step itself, then what came back as its own short sentence after it. This holds in the middle of your half and not only at its ends.\n\n**Length.** Your half is {{half_length}} characters. Return something close to that \u2014 within about 10% either way. You are correcting and rewriting it, not condensing it: material you drop is material nothing else will carry, because the transcript it came from is being deleted.\n\nAnswer with the {{half}} half of the replay and nothing else. No heading, no preamble, no note about what you changed, no marker line. Just the prose.";
+/**
+ * The synthesiser's instruction, as a template.
+ *
+ * `{{original_length}}` and `{{max_length}}` are substituted. The retrospective
+ * paragraph and the answer format come after it from the harness, because the
+ * reply is parsed by its headings, and so do the halves themselves.
+ */
+export declare const DEFAULT_COUNCIL_SYNTHESIZER_PROMPT = "A replay of your recent work was cut in half, and each half was rewritten against the full transcript by a different writer. Join them back into one continuous replay.\n\nBoth writers had the whole transcript, so both halves are grounded in the record \u2014 but each owned only its own half, and either could be wrong about the seam between them or about a fact the other half settles differently. Cross-check the two against each other: where they disagree about the same fact, keep the version that quotes the transcript over the version that describes it; where one states something the other contradicts, keep the one that is specific.\n\nWhat you are producing is one piece of prose, not two halves stacked up. Make the seam invisible: no heading between them, no marker line, no sentence that restarts or recaps. If the two writers both wrote the same step \u2014 once at the end of the first half and once at the start of the second \u2014 keep it once.\n\nKeep it in the first person and the present continuous tense, every step written as the step and its outcome after it.\n\n**Length.** The replay was {{original_length}} characters before it was rewritten. Aim at that. You may go up to {{max_length}} \u2014 about 10% more \u2014 and you should use that allowance only where it takes the extra room to keep something that would otherwise be lost. Do not use it to be more thorough for its own sake, and do not come in far under: material dropped here is material nothing else carries.";
+/** Substitute `{{name}}` placeholders; an unknown one is left as written. */
+export declare function renderCouncilPrompt(template: string, values: Record<string, string | number>): string;
+/**
+ * A writer prompt with the council's marker instruction, when the council runs.
+ *
+ * Not appended twice: a custom prompt copied from an older default already
+ * carries the section, marker and all.
+ */
+export declare function withCouncilWriterPrompt(prompt: string, writerPrompt?: string): string;
+/** The line the replay carries to say where its first half ends. */
+export declare const COUNCIL_HALF_MARKER = "<<<HALFWAY>>>";
+/**
+ * The replay in two pieces.
+ *
+ * Prefers the marker the writer placed, because a boundary between two
+ * stretches of work is a thing only the writer knows. Falls back to the
+ * nearest blank line to the midpoint when the marker is missing or lands far
+ * enough off-centre that one writer would get most of the replay -- a
+ * paragraph break is not a semantic boundary, but it is a boundary, and a
+ * balanced split at a slightly wrong place beats a correct one that nobody
+ * works on.
+ */
+export declare function splitReplayAtMarker(replay: string): {
+    first: string;
+    second: string;
+    source: "marker" | "rebalanced";
+} | undefined;
+/** Strip any marker the model left behind, so it never reaches the context. */
+export declare function stripHalfMarker(text: string): string;
+/** Which half of the transcript a reviewer was given. */
+export type CouncilHalf = "first" | "second";
+export interface CouncilSections {
+    replay?: string;
+    retrospective?: string;
+}
+/**
+ * The reviewer's instruction.
+ *
+ * Most of it is about what *not* to do, which is unusual here and is the
+ * lesson of the shape: the failure mode of a reviewer holding half the
+ * evidence is not missing a correction, it is confidently deleting a fact it
+ * cannot see the support for. A replay covering the whole of the work will
+ * always look half-unsupported to each reviewer, so saying it once is not
+ * enough.
+ */
+export declare function buildCouncilCriticRequest(input: {
+    half: CouncilHalf;
+    /** The half this writer owns and returns. */
+    ownReplay: string;
+    /** The other half, for grounding only. */
+    otherReplay: string;
+    transcript: string;
+    /**
+     * The numbered record the replay's `[#N]` citations point at.
+     *
+     * Without it the citations are unexplained punctuation. Measured on
+     * pandorum with thinking on, the writer wrote its own reading into its
+     * task list -- "write every step as `Step [number]. Outcome.`" -- and
+     * restructured its half around a step numbering that does not exist,
+     * returning 30% of what it was given.
+     */
+    toolLedgerKey?: string;
+    /** Replaces {@link DEFAULT_COUNCIL_CRITIC_PROMPT}; blank uses it. */
+    instructions?: string;
+    /**
+     * The writer is reading this as the next turn of the conversation the
+     * replay was written from (compaction as a continuation): the transcript
+     * is the context above, and repeating it here would pay for it twice.
+     */
+    transcriptInContext?: boolean;
+}): string;
+/**
+ * The synthesiser's instruction.
+ *
+ * It sees each half's original beside that half's rewrite, rather than the
+ * whole original in one piece: the halves are what the two writers actually
+ * worked on, so pairing them is what makes a change visible. It is also the
+ * only role that touches the retrospective, which is deliberate -- a
+ * retrospective is a judgement about how the work went, and a reviewer holding
+ * one half of the evidence is the worst possible judge of it. By the time this
+ * runs the merged replay exists, which is the thing the judgement is about.
+ */
+export declare function buildCouncilSynthesizerRequest(input: {
+    firstOriginal: string;
+    secondOriginal: string;
+    firstRewritten: string;
+    secondRewritten: string;
+    thinkingSummary?: string;
+    /** What the whole replay was before either half was rewritten. */
+    originalLength: number;
+    /** Replaces {@link DEFAULT_COUNCIL_SYNTHESIZER_PROMPT}; blank uses it. */
+    instructions?: string;
+    /**
+     * The synthesiser continues the conversation the replay was written in, so
+     * the originals are its own answer above: named by where they begin and
+     * end rather than pasted again.
+     */
+    originalsInContext?: boolean;
+}): string;
+/**
+ * Read the two sections back out of a reply.
+ *
+ * Tolerant of the heading level and of anything the model puts before the
+ * first heading, because the alternative to tolerance here is discarding a
+ * good correction over a `###`. A reply with no recognisable `Replay` section
+ * yields nothing and is treated as a reviewer that declined.
+ */
+export declare function parseCouncilSections(text: string): CouncilSections;
+/**
+ * Head, middle and tail rather than the opening.
+ *
+ * The question these excerpts exist to answer is whether the replay holds its
+ * voice all the way through, and the prompt says as much in as many words:
+ * the rule "holds for the middle of the replay and not only its first and last
+ * sentences". An excerpt that only ever showed the opening could not tell a
+ * replay that drifts from one that does not.
+ */
+export declare function logExcerpt(text: string, limit?: number): string;
+export interface CouncilReviewResult {
+    summary: string;
+    thinkingSummary?: string;
+    /** How many reviewers came back with something usable. */
+    reviewers: number;
+    /** Whether the synthesiser's merge replaced the original. */
+    merged: boolean;
+}
+/**
+ * Run the review. Returns what it was given if any part of it does not land.
+ */
+export declare function runCouncilReview(input: {
+    summary: string;
+    thinkingSummary?: string;
+    messages: readonly MessageWithMetadata[];
+    /**
+     * One model call. Throwing is allowed and is handled as a decline.
+     *
+     * `role` and `half` say which call it is, for a caller that runs the two
+     * kinds differently -- a compaction written as a continuation sends a
+     * critic as the next turn of the conversation and the synthesiser as a
+     * request of its own.
+     */
+    generate: (call: {
+        systemPrompt: string;
+        request: string;
+        role: "critic" | "synthesizer";
+        half?: CouncilHalf;
+    }) => Promise<string>;
+    /**
+     * The critics hold the transcript as their context; it is not repeated in
+     * their requests (see {@link buildCouncilCriticRequest}).
+     */
+    transcriptInContext?: boolean;
+    /**
+     * Called once the reviewers are done and before the synthesiser runs.
+     * Its `thinkingSummary`, when it returns one, is the retrospective the
+     * synthesiser revises.
+     *
+     * This is where a continuation gives its cells back: the critics were the
+     * last calls that needed the session's context, and the synthesiser reads
+     * only the halves.
+     */
+    prepareSynthesis?: () => Promise<{
+        thinkingSummary?: string;
+        originalsInContext?: boolean;
+    } | undefined>;
+    /**
+     * What the summarizer will accept as one request. A reviewer whose half
+     * does not fit declines rather than sending a call the provider refuses;
+     * the other half is still reviewed, which is why this is not a reason to
+     * abandon the council.
+     */
+    maxRequestChars?: number;
+    /**
+     * The numbered record the replay's `[#N]` citations point at, passed
+     * through to both writers so the citations are not unexplained
+     * punctuation they have to guess a meaning for.
+     */
+    toolLedgerKey?: string;
+    logger?: BasicLogger;
+    /**
+     * Review the halves one after the other instead of at once.
+     *
+     * Set when the agent runs inside an engine session it shares with a swarm:
+     * two concurrent reviewers are two concurrent requests against a window the
+     * other agents are drawing on, which is the load compaction is meant to
+     * relieve, not add to.
+     */
+    serial?: boolean;
+    /** Replaces the reviewers' instruction; blank uses the default. */
+    criticPrompt?: string;
+    /** Replaces the synthesiser's instruction; blank uses the default. */
+    synthesizerPrompt?: string;
+}): Promise<CouncilReviewResult>;

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

@@ -0,0 +1,44 @@
+/**
+ * Compaction for the strategy that keeps nothing.
+ *
+ * When the recency tail is disabled the summary *is* the context: the model
+ * reads it and nothing else. That is a harder brief than the replay prompt's,
+ * and the failure modes are measured rather than guessed. Three results shaped
+ * every choice here, and the reasons are recorded because each of them
+ * contradicts something that looks obviously right.
+ *
+ * **Asking for detail does not produce detail.** (arXiv 2605.23296.) Switching
+ * the instruction from "concise" to "very detailed" barely moves the output,
+ * and output length grows only ~3× as input grows from 2k to 96k tokens —
+ * models anchor summary length to the distribution they were trained on. So
+ * there is not one length adjective in this prompt. Completeness is enforced
+ * structurally instead: a fixed section list, every section required even when
+ * empty, explicit `(none)`, and per-section enumeration requirements. That is
+ * the lever that measurably works.
+ *
+ * **A summary flattens a process into declarations, and the agent then cannot
+ * tell where it is.** (arXiv 2608.06503.) With a summary in place of the
+ * trajectory, agents terminated on only 44.6% of samples against 77.2% for
+ * plain FIFO truncation, and re-issued already-blocked actions. The ordered
+ * action–observation sequence is what anchors "this is already done". Hence
+ * the hard separation of Done / In progress / Next, the explicit ban on
+ * describing finished work as pending, and — outside this prompt — the tool
+ * ledger the harness appends, which restores the sequence itself.
+ *
+ * **Enumerable state cannot be summarised.** (arXiv 2608.01326.) A production
+ * compaction endpoint answered set-membership over 15,000 items at close to
+ * chance, worse than a same-size Bloom filter. Identifiers, checklists and
+ * inventories therefore get a verbatim carry instruction, never a "summarize
+ * these".
+ *
+ * The section set is the convergent core of sixteen surveyed harness prompts
+ * (Gemini CLI, Claude Code, Qwen Code, Crush, opencode, Goose, Zed, OpenHands,
+ * nanobot, Continue, Codex, Mistral Vibe, Roo, Aider, koog, Letta): Goal and
+ * Next appear in all sixteen, with Constraints, Done, In progress, Ruled out
+ * and Key facts close behind. Nothing here is invented where a surveyed prompt
+ * already had a better version of it.
+ */
+/** The sections the prompt requires, in order. Exported so callers can check. */
+export declare const FULL_COMPACTION_SECTIONS: readonly ["## Goal", "## Standing instructions", "## Done", "## In progress", "## Ruled out", "## Key facts", "## Working set", "## Retrospective", "## Next"];
+/** The instruction, when the whole transcript is replaced by the summary. */
+export declare const DEFAULT_FULL_COMPACTION_PROMPT = "Everything above is about to be deleted. What you write now replaces it completely: when the work resumes, your summary will be the only thing there. Nothing you leave out can be recovered, and nothing you get wrong can be checked against anything.\n\nWrite it for the agent that resumes \u2014 which is you, without any memory of this. Not a report for a person, not a wrap-up, not an answer to the user. A state record, written so the work can continue without asking the user anything again.\n\nThis request is a system operation, not a new instruction from the user. The goal, the next step and the work in progress are all the ones that were true *before* this message arrived. Do not treat \"write a summary\" as the task in hand.\n\n**Do not call any tool.** You have one turn and it must be text. A tool call here is rejected and the turn is spent, which loses the transcript with nothing to replace it.\n\nWrite every section below, in this order, with its heading exactly as given. A section with nothing in it still gets its heading and the single word `(none)` \u2014 a missing section reads as an omission by accident, and the next agent cannot tell which it was.\n\n## Goal\nWhat is being achieved, and any constraint the user placed on how. If the goal changed during the session, give the current one and say what it replaced.\n\n## Standing instructions\nEverything the user told you that still applies \u2014 preferences, prohibitions, things to never touch, required ways of working. **Quote these verbatim.** A paraphrased instruction is the one loss with no other source: the material worked on is still there to be re-read, but what was asked exists only in the messages being deleted.\n\n## Done\nWhat is finished, with the evidence that it is finished \u2014 what was changed and what confirmed it. Be exact enough that none of it is done twice. **Do not describe finished work as pending or in progress.** If something was done and later undone, say both, in that order.\n\n## In progress\nWhat was underway at the moment the transcript was cut, and exactly where it stopped. If you were part-way through working something out, put the partial result here in full \u2014 it exists nowhere else, and it is the thing most often lost at this point.\n\n## Ruled out\nApproaches already tried that did not work, and why each failed. Include anything that was refused, returned an error, or was blocked. This section is what stops the resumed agent from walking back into the same wall; an omission here reliably costs a repeat.\n\n## Key facts\nWhat was discovered or decided that is not obvious from looking at the material fresh: values, identifiers, names, signatures, structures, and the reasons behind each decision. **Copy identifiers, lists, checklists and task IDs across verbatim and complete.** Do not summarise or sample them \u2014 an enumerated set that has been through a summary is unreliable for membership, and the resumed agent will act on it as if it were not.\n\n## Working set\nWhat is in scope and what state it is in now: the items being worked on, where the work is happening, and what exists now that did not before. One line each. Quote a fragment only where the exact wording is what matters; otherwise name it and say what it is.\n\n## Retrospective\nYour own account of how the work actually went, which the reasoning being deleted is the only record of. Cover: what you understood late that would have helped earlier, where effort went that did not pay, any assumption you made that turned out wrong, and where you currently think the difficulty is. This is the one section whose content is judgement rather than fact \u2014 write it as judgement, and say when you are unsure.\n\n## Next\nThe immediate next steps, in order, specific enough to act on without re-deriving them.\n\nTwo rules over all of it. **Do not invent anything.** If you cannot recall something, leave it out or say it is uncertain \u2014 a confident wrong detail in this summary cannot be checked against anything and will be acted on. And do not write a step that rewrites or restores content this summary does not itself contain: the material is still there to be read, and reconstructing it from memory produces a worse copy of something intact.";

package/dist/extensions/context/kv-pressure.d.ts

@@ -0,0 +1,258 @@
+import { type OpencotiAllocation, type OpencotiKvPressure } from "@cerebriline/llms";
+import type { BasicLogger } from "@cerebriline/shared";
+import { type PolykvProviderConfig } from "./polykv-session";
+/**
+ * Running agents give cells back when the server is refusing others, and take
+ * them again when it stops (`kv_pressure_v1` + `kv_resize_v1`, opencoti b108).
+ *
+ * The policy, as ruled (2026-09-25): admission refuses new agents under
+ * pressure; RUNNING agents compact and shrink, transparently, when there is
+ * pressure -- and never below their floor, because one agent with 60k beats
+ * two with 30k. The floor is the node's "Agent window" share (or the profile's
+ * `contextFloor` for a lead), recorded by the fetch that sent it.
+ *
+ * Three moves, all at a turn boundary -- the prepare step of the compaction
+ * pipeline, which is between this session's requests by construction:
+ *
+ * 1. **Compact on global pressure.** The server refused someone in the last
+ *    minute, this agent holds more than its floor, and compacting would let it
+ *    give back a real share of its window: compaction is requested through the
+ *    existing trigger -- one more reason beside the ratio, the overflow report
+ *    and the engine's own row, never a second compaction path.
+ * 2. **Shrink.** After a compaction, or at once when the context is already
+ *    small, the booking is resized to what the context needs plus room to
+ *    grow, never below the floor.
+ * 3. **Grow back.** When a recent read says nobody is being refused and the
+ *    booking is filling, it is resized up toward the window it first asked for
+ *    -- before the ratio trigger would compact it. Growth is preferred over
+ *    compaction whenever the server has the room.
+ *
+ * Every refusal the engine can give a resize is an ordinary outcome here: a
+ * busy session is tried again at the next boundary, a gone one is dropped, an
+ * exhausted grow takes `largest_admissible`. Nothing is a warning, and nothing
+ * fails a turn. On a server that does not advertise both features none of this
+ * runs and no resize is ever sent.
+ */
+/**
+ * How full a shrunk window is left: the context and a reply's room take this
+ * share, the rest is room to grow before the next decision. Below
+ * {@link KV_GROW_AT} so a window just shrunk is not grown on the next turn,
+ * and below the ratio trigger (0.9) so it is not compacted either.
+ */
+export declare const KV_SHRINK_FILL = 0.6;
+/**
+ * How full a window has to be, by the engine's own count, before it grows
+ * back. Below the ratio trigger, so growth comes first when there is room.
+ */
+export declare const KV_GROW_AT = 0.75;
+/** Resize targets are whole multiples of this, as the engine's grants are. */
+export declare const KV_RESIZE_ALIGN = 256;
+/**
+ * The least a shrink must give back to be worth a resize: a tenth of the
+ * window, and never under this many cells. A resize for a handful of cells is
+ * churn.
+ */
+export declare const KV_SHRINK_MIN_CELLS = 4096;
+export declare const KV_SHRINK_MIN_SHARE = 0.1;
+/**
+ * What a pressure compaction must buy, as a share of the window, beyond what
+ * a shrink without it would. Compaction costs the agent its detail; it is
+ * spent under pressure only when it frees a real part of the booking. Without
+ * this a window just shrunk to fit its compacted context would be compacted
+ * again on the next turn, for a few thousand cells.
+ */
+export declare const KV_PRESSURE_COMPACTION_MIN_GAIN_SHARE = 0.25;
+/**
+ * How much bigger than a compaction's result the context must be for a
+ * pressure compaction: a context already near what compaction would leave has
+ * nothing to give.
+ */
+export declare const KV_PRESSURE_COMPACTION_MIN_RATIO = 1.25;
+/**
+ * When the cells idle slots hold count as pressure (`kv_observable_v1`).
+ *
+ * `idle_resident` is resident cache no booking pays for: a released worker's
+ * private suffix, an LCP-kept slot's cache. The admission gate counts those
+ * cells as free (`cells_free`) and hands them out; the cache does not have
+ * them. The engine reclaims them one slot per FAILED `find_slot` -- so once
+ * the bookings grow into that room, what reclaims it is a failed batch, and
+ * a failed batch is an "Invalid input batch" for everyone in it or a partial
+ * eviction (b108: `used 9750` booked while ~81k released-worker tokens were
+ * held, then evictions of agents holding 20-31k of 64k).
+ *
+ * So it is pressure when it is a real part of the room admission still
+ * offers: at least {@link KV_IDLE_RESIDENT_PRESSURE_SHARE} of `cells_free`
+ * (of `cells_total` where the engine states no free count). A quarter because
+ * that is the point where the next few admissions -- each books a window of
+ * tens of thousands of cells -- can already reach cells that are not there,
+ * while a pool with room several times the ghosts has nothing to fear from
+ * them yet. And never under {@link KV_IDLE_RESIDENT_PRESSURE_MIN_CELLS}: one
+ * idle slot keeping a short request's cache is how the engine is meant to run
+ * (the 0399 gate read 1,997 after a single 512-token completion), not a leak.
+ */
+export declare const KV_IDLE_RESIDENT_PRESSURE_SHARE = 0.25;
+export declare const KV_IDLE_RESIDENT_PRESSURE_MIN_CELLS = 8192;
+/** Whether the idle-resident cells are pressure: see the constants above. */
+export declare function idleResidentIsPressure(resident: {
+    idleResident: number;
+    cellsFree?: number;
+    cellsTotal?: number;
+}): boolean;
+/**
+ * When the SWA half is full enough to be pressure (opencoti mail #322).
+ *
+ * On a model with a sliding window the cache has two halves, and bookings and
+ * `largest_admissible` count only the base. Every resident sequence keeps its
+ * last SWA window -- idle sessions and pools too -- so the SWA half fills while
+ * the base looks empty: the b116 evictions were "SWA half could not fit the
+ * batch (2048 tokens): swa 66044 used of 66048 cells" with the base at 163k of
+ * 1M. A batch needs a ubatch of free SWA cells on top of every live window,
+ * so the room that matters is a few batches, not a share of a big pool.
+ *
+ * 0.85: on that 66,048-cell half the last 15% is ~9,900 cells, four or five
+ * 2,048-token batches -- the headroom a wave of prefills uses up before the
+ * next turn boundary reads `/kv` again. Lower would call a half that is
+ * merely busy (each live sequence holds a whole window by design) pressure;
+ * higher leaves less than two batches between the reading and the failure.
+ * And `/kv`'s count is the engine's accounting, which leaves the idle slots'
+ * windows out: the physical half is fuller than it says, never emptier.
+ */
+export declare const KV_SWA_PRESSURE_OCCUPANCY = 0.85;
+/** Whether the SWA half is pressure: see {@link KV_SWA_PRESSURE_OCCUPANCY}. */
+export declare function swaIsPressure(swa: {
+    cellsUsed: number;
+    cellsTotal: number;
+    cellsFree?: number;
+    cellsPhysFree?: number;
+    cellsPhysTotal?: number;
+}): boolean;
+/** The booking this session's usage lands in, and its bounds. */
+export interface KvResizeSubject {
+    /**
+     * `own`: the session's own booking. `owner`: the swarm owner its pooled
+     * turns are charged to -- the owner resizes, never each worker.
+     */
+    kind: "own" | "owner";
+    /** The id the engine knows the booking by. */
+    engineId: string;
+    /** The host session whose grant follows the resize. */
+    grantKey: string;
+    /** Never shrunk below. Absent: no smaller window was declared acceptable. */
+    floor?: number;
+    /** Never grown above: the window first asked for. */
+    ceiling?: number;
+}
+/** What one turn boundary knows about the server's pressure. */
+export interface KvPressureTurn {
+    baseUrl: string;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+    subject: KvResizeSubject;
+    state: "active" | "clear" | "unknown";
+    pressure?: OpencotiKvPressure;
+    /** The subject's `/kv` row, as read this turn (updated by a resize). */
+    row?: OpencotiAllocation;
+    logger?: BasicLogger;
+    /**
+     * The server queues a busy booking's resize for its idle moment
+     * (`kv_resize_deferred_v1`): every resize is asked for that way, and one
+     * already queued is not asked again.
+     */
+    deferred?: boolean;
+    /**
+     * Cells idle slots hold beyond every booking, server-wide, as this turn's
+     * `/kv` read stated them (`kv_observable_v1`); absent on older engines.
+     * Added to `used` wherever a shrink is sized: right after a batch failure
+     * `used` alone is a floor, not a fact.
+     */
+    idleResident?: number;
+    /**
+     * {@link idleResident} is pressure of its own ({@link
+     * idleResidentIsPressure}): the state is `active` whatever the refusals
+     * say.
+     */
+    idlePressure?: boolean;
+    /**
+     * The SWA half is full ({@link swaIsPressure}), whatever the base says.
+     * Nothing grows into it. It is NOT a reason to compact or shrink: a
+     * sequence holds one SWA window whatever its context length, so neither
+     * frees an SWA cell, and a shrink hands base cells to admission, which
+     * books base only and would seat more sequences in the full half. What
+     * frees SWA is fewer resident sequences -- sessions released as their
+     * agents end.
+     */
+    swaPressure?: boolean;
+    /** The SWA half as read, for the log. */
+    swa?: {
+        cellsUsed: number;
+        cellsTotal: number;
+    };
+    /**
+     * The subject is a lead conversation's own booking, not a delegated
+     * agent's: it compacts for the server only while its own agents need
+     * this engine's cells (see {@link kvPressureWantsCompaction}).
+     */
+    lead?: boolean;
+}
+/** Test seam. */
+export declare function resetKvPressureState(): void;
+/**
+ * The booking a session lives in, or `undefined` when it has none of its own
+ * to resize.
+ *
+ * A pooled worker lives in the owner its last turn was charged to, and only
+ * an owner this process opened is resized -- the lead's own session lent to
+ * priority-0 agents is the lead's, and the lead resizes it at its own
+ * boundaries. Everything else is its own session under the id the wire
+ * carried.
+ */
+export declare function resolveKvResizeSubject(sessionId: string, providerConfig: PolykvProviderConfig): KvResizeSubject | undefined;
+/**
+ * Open a turn boundary: read the pressure, find the booking, and grow it back
+ * if the pressure has cleared and it is filling.
+ *
+ * `undefined` -- and nothing sent -- unless the server advertises both
+ * `kv_pressure_v1` and `kv_resize_v1`. Called before the compaction trigger
+ * sizes itself, so a window grown here is the window the trigger measures
+ * against this very turn.
+ */
+export declare function beginKvPressureTurn(options: {
+    sessionId: string | undefined;
+    providerConfig: PolykvProviderConfig;
+    logger?: BasicLogger;
+    /**
+     * Grow back here when the pressure has cleared. Off for a manual
+     * compaction and an overflow recovery: they are shrink-only boundaries.
+     */
+    grow?: boolean;
+}): Promise<KvPressureTurn | undefined>;
+/**
+ * Whether this turn should compact because the SERVER is under pressure.
+ *
+ * All of: refusals inside the window; a floor declared and the booking above
+ * it; the context meaningfully bigger than what compaction leaves; and
+ * compacting lets the booking shrink by at least
+ * {@link KV_PRESSURE_COMPACTION_MIN_GAIN_SHARE} of itself beyond what a plain
+ * shrink would. Tokens are on the provider's count (`requestTokens`) and the
+ * compacted size is put on the same scale by the caller.
+ */
+export declare function kvPressureWantsCompaction(turn: KvPressureTurn | undefined, input: {
+    requestTokens: number;
+    compactedTokens: number;
+    outputRoomTokens: number;
+}): boolean;
+/**
+ * Give cells back while the server is refusing: resize the booking down to
+ * what the context needs plus room to grow, never below the floor.
+ *
+ * `usageTokens` is the context about to be sent. Right after a compaction it
+ * is the compacted size, which the engine may not see yet -- its tree still
+ * holds the old cells until the next request -- so a `used_exceeds_window`
+ * then is expected, and the next boundary asks again with the engine's own
+ * count. An owner is sized from its own row: its usage is every agent's.
+ */
+export declare function shrinkForKvPressure(turn: KvPressureTurn | undefined, input: {
+    usageTokens: number;
+    outputRoomTokens: number;
+    afterCompaction: boolean;
+}): Promise<void>;