@cerebriline/core 4.100.240

package/dist/extensions/context/polykv-session.d.ts

@@ -0,0 +1,372 @@
+import type { PolykvOptions } from "@cerebriline/llms";
+import { type OpencotiAllocation, type OpencotiKvSnapshot, type PolykvCapacity } from "@cerebriline/llms";
+import { type BasicLogger } from "@cerebriline/shared";
+/**
+ * The conversation's KV pool, on the engine that owns the cells.
+ *
+ * opencoti-llamafile keeps a tree of pools; a pool owns `[D, L)` and shares
+ * everything before `D` with its parent. The part of an agent's context that
+ * never changes -- system prompt and tool schemas -- can therefore be prefilled
+ * once, pinned, and attached by every later request instead of re-sent.
+ *
+ * That prefix is not a rounding error here. Measured on the Ollama path in this
+ * fork: 12,859 tokens of system prompt and tool definitions on every single
+ * request, and one turn whose prefill ran past undici's five-minute header
+ * timeout and killed the session.
+ *
+ * Two rules from the engine's own design are load-bearing and are why this
+ * module exists rather than a couple of inline calls:
+ *
+ * - **Compaction is a prompt rewrite, never an in-place KV op.** Compacted text
+ *   is new text and cannot match the old cells, so a re-root is
+ *   `fork(root, D_sys, new suffix)` followed by releasing the old subtree.
+ * - **A pin left on an abandoned subtree is a leak.** Unpin after migrating,
+ *   every time, including on the failure paths.
+ *
+ * Nothing here may fail a turn. A pool that cannot be created or read means the
+ * session runs exactly as it did before any of this existed: the whole prompt
+ * on every request, and the estimate-based compaction trigger deciding when to
+ * compact. Every entry point returns `undefined` rather than throwing.
+ */
+/**
+ * How close to full the engine has to say the pool is before this compacts.
+ *
+ * Below the estimate-based trigger's own ratio on purpose. This number is
+ * measured by the thing holding the cells, where every other signal in the
+ * compaction path is an estimate -- and the estimates were wrong in both
+ * directions inside a single session: a chars-per-token ratio that swung 3.16
+ * to 5.42, an overhead term that read 53,323 tokens for a 12,700-token payload.
+ * When the engine says it is nearly out, it is nearly out.
+ */
+export declare const POLYKV_COMPACTION_PRESSURE = 0.85;
+export interface PolykvProviderConfig {
+    providerId?: string;
+    baseUrl?: string;
+    /** The model, where the provider pools per model (xOllama). */
+    modelId?: string;
+    /** The provider's key, which a keyed xOllama wants on its engine routes. */
+    apiKey?: string;
+    headers?: Record<string, string>;
+    fetch?: typeof fetch;
+    /** The profile's PolyKV section. Absent means "never configured". */
+    polykv?: PolykvOptions;
+    /**
+     * Set on a swarm agent's config: its pools belong to the swarm's tree
+     * (`polykv-swarm.ts`), so the lead-conversation pool logic here stands down
+     * rather than building a second, private tree for every agent.
+     */
+    polykvWorker?: unknown;
+    /** Set on a delegated agent's config: the engine session its turns carry. */
+    engineSessionId?: string;
+}
+/**
+ * Whether this session runs on an engine that has a pool tree, and wants it.
+ *
+ * `enabled` is read as off only when it says so. A profile written before the
+ * section existed carries nothing, and treating that as "disabled" would take
+ * pooling away from every session that already had it -- a silent regression
+ * dressed up as a default.
+ */
+export declare function isPolykvProvider(config: PolykvProviderConfig | undefined): boolean;
+/**
+ * Whether this server really has a pool tree, asked of the server.
+ *
+ * {@link isPolykvProvider} answers a question about the *profile* -- opencoti,
+ * a base URL, pooling not switched off -- which is as much as most of this
+ * module needs, because every pool call it makes degrades to "no pool" on its
+ * own. Offering a tool is different: the schema is paid for out of the context
+ * window before anything is called, and a swarm on a server booted without
+ * `--polykv-max-pools` -- the default -- fails on its first pool call having
+ * already spent it.
+ *
+ * So this one waits for `/props`. The read is cached per server for the life of
+ * the process, and an unreachable server answers `false`: "cannot ask" is not
+ * "yes", which is the same reading the slot limit takes.
+ */
+/**
+ * Whether a delegated agent on this profile runs as a swarm worker: opencoti
+ * with pooling on (see {@link isPolykvProvider}), or xOllama.
+ *
+ * xOllama is decided per model, and at the provider: a plain model with seats
+ * for client pools on a server that negotiates windows pools the agent through
+ * the model's engine, and any other model -- a council, one without seats --
+ * runs it as the plain chat it would have been. Only the worker is widened:
+ * the lead-session pool code in this module speaks to an opencoti root and has
+ * none on xOllama, where the provider builds the lead's pool itself.
+ */
+export declare function isPolykvWorkerProvider(config: PolykvProviderConfig | undefined): boolean;
+/**
+ * The engine this config's PolyKV calls go to, as an opencoti-shaped config:
+ * opencoti's own, or on xOllama the selected model's engine behind
+ * `/api/engine` -- where the model is plain, keeps seats for clients and the
+ * server negotiates windows. `undefined` where there is no engine to drive.
+ *
+ * For the readers and the control plane only (`/kv`, `/capacity`, resizes,
+ * pools, session close): a chat still goes through the provider, whose own
+ * fetch speaks xOllama. So the result is never handed to a model factory.
+ */
+export declare function resolvePolykvEngineConfig(config: PolykvProviderConfig | undefined): Promise<PolykvProviderConfig | undefined>;
+export declare function polykvPoolsConfirmed(config: PolykvProviderConfig | undefined): Promise<boolean>;
+/**
+ * The messages whose templated tokens make up the shared prefix.
+ *
+ * Returned as a chat body rather than a string, because the string is not ours
+ * to write. The engine prefills whatever its own chat template produced, and a
+ * prefix assembled here -- the system prompt, a newline, `JSON.stringify` of
+ * the tool schemas -- is a different token sequence from the one that gets
+ * prefilled. The pool is then created, pinned and attached, and shares nothing,
+ * on every turn, with nothing reporting it. Only the server knows which
+ * template it loaded and how that template renders tools.
+ *
+ * The prefix does not have to be exactly right, only honest: the engine
+ * computes the shared length itself as the longest exact token match (auto-P),
+ * and an explicit hint may only cap that, never raise it. So a prefix running
+ * slightly past the true boundary shares less, rather than failing.
+ */
+export declare function renderPolykvPrefixMessages(options: {
+    systemPrompt?: string;
+    tools?: readonly unknown[];
+}): {
+    messages: readonly unknown[];
+    tools?: readonly unknown[];
+} | undefined;
+/**
+ * End the pinned prefix at a token boundary.
+ *
+ * A prefix ending in a trailing space merges with the first word of whatever
+ * follows into a single token, so the child's `[0, branch_pos)` no longer
+ * matches the parent's and the contiguous-prefix check answers 400. A newline
+ * is the boundary every chat template already ends its blocks on.
+ */
+export declare function endAtTokenBoundary(prompt: string): string;
+/**
+ * Create and pin the session's root pool, once.
+ *
+ * Idempotent: a session that already has one keeps it. The pin is what stops
+ * the engine reclaiming the prefix between turns, and is released by
+ * `releasePolykvSession`.
+ */
+export declare function ensurePolykvPool(options: {
+    sessionId: string | undefined;
+    providerConfig: PolykvProviderConfig;
+    systemPrompt?: string;
+    tools?: readonly unknown[];
+    logger?: BasicLogger;
+}): Promise<string | undefined>;
+/**
+ * How often one session may ask the engine for its room.
+ *
+ * `GET /capacity` is not a read on the published c7 engine: every GET folds the
+ * settle and bias EWMAs the admission projection is built from. The fold is
+ * what the enforced gate does on an admission, once per gated request -- and a
+ * client that also asks on its own cadence adds folds the engine never made,
+ * from moments that were not admissions, and then acts on the projection it
+ * skewed.
+ *
+ * Two callers want the answer: the compaction check, once a turn, and the
+ * delegation admission gate, once a round. Bounding here rather than in either
+ * of them is deliberate -- it holds however many callers appear later, and it
+ * cannot be forgotten at a new call site.
+ *
+ * (c8 makes the plain GET read-only and moves the fold behind `?fold=1`. This
+ * bound then stops being load-bearing, and is still the right manners.)
+ */
+export declare const POLYKV_CAPACITY_MIN_INTERVAL_MS = 5000;
+/** Forget a session's last capacity answer. Test seam, and release path. */
+export declare function clearPolykvCapacityCache(sessionId?: string): void;
+/**
+ * What the engine says about this pool's room, or `undefined` if it will not say.
+ *
+ * `expectedTokens` is the turn about to be sent, so the answer accounts for the
+ * request rather than describing the pool at rest.
+ *
+ * Answered from the last read when one is recent enough -- see
+ * {@link POLYKV_CAPACITY_MIN_INTERVAL_MS} for why that is a correctness
+ * property on c7 and not a performance one.
+ */
+export declare function readPolykvCapacity(options: {
+    sessionId: string | undefined;
+    providerConfig: PolykvProviderConfig;
+    expectedTokens?: number;
+    logger?: BasicLogger;
+}): Promise<PolykvCapacity | undefined>;
+/** Forget the cached allocations. Test seam. */
+export declare function clearPolykvAllocationCache(): void;
+/**
+ * This session's row of `GET /kv`'s `allocations[]`, or `undefined`.
+ *
+ * The compaction trigger's preferred signal (P4): `pressure` there is the RAW
+ * `used/window` of the window the session booked, the number the user's
+ * threshold is written against. Unlike a pool's `/capacity` it needs no pool --
+ * a session can book a window with pooling off -- so it is asked for on its
+ * own, and only where the server offers the route (`kv_status_v1`).
+ *
+ * **A delegated agent reads the booking it lives in.** A worker whose turns
+ * are pooled books nothing -- the engine charges its suffix to the owner the
+ * swarm assigned it (the lead's own session on priority 0) -- so the owner's
+ * row is its pressure. A worker whose last turn went out unpooled runs as a
+ * session of its own, and its own row is. Each falls back to the other when
+ * its row is not listed. Turning every worker away here, as this once did,
+ * left no delegated agent on a PolyKV node able to compact on engine pressure.
+ *
+ * Bounded by {@link POLYKV_CAPACITY_MIN_INTERVAL_MS}, the same manners as the
+ * capacity read, and a failed read is cached too.
+ */
+export declare function readPolykvAllocation(options: {
+    sessionId: string | undefined;
+    providerConfig: PolykvProviderConfig;
+    logger?: BasicLogger;
+}): Promise<OpencotiAllocation | undefined>;
+/**
+ * This session's last `GET /kv` read: every allocation row, and the server's
+ * `pressure` where it states one (`kv_pressure_v1`).
+ *
+ * The one read behind both the compaction trigger's row
+ * ({@link readPolykvAllocation}) and the pressure policy (`kv-pressure.ts`),
+ * so a turn asks `/kv` once. Bounded by
+ * {@link POLYKV_CAPACITY_MIN_INTERVAL_MS} per session, and a failed read is
+ * cached too.
+ */
+export declare function readPolykvKvSnapshot(options: {
+    sessionId: string | undefined;
+    providerConfig: PolykvProviderConfig;
+    logger?: BasicLogger;
+}): Promise<OpencotiKvSnapshot | undefined>;
+/**
+ * Whether the engine's own measurement says it is time to compact.
+ *
+ * The RAW ratio decides (P4, ruled): this session's `pressure` from `GET /kv`
+ * first, then the pool's own raw `pressure` (`session_pressure_v1`), and only
+ * where neither is stated the older `compaction_pressure` -- a 0.70..1.0 ramp
+ * that stops matching the threshold the user set the moment it is compared
+ * against one.
+ *
+ * A pool still settling reports pressure that describes a state it is leaving,
+ * so it is not asked to decide anything. The allocation is the booked window's
+ * own ledger and is not subject to that.
+ */
+export declare function polykvSaysCompact(capacity: PolykvCapacity | undefined, threshold?: number, allocation?: Pick<OpencotiAllocation, "pressure">): boolean;
+/**
+ * The window compaction must size against: the granted one, when it is known
+ * and smaller than the configured one.
+ *
+ * A conversation negotiated down to 160k of a configured 256k is a 160k
+ * conversation for its whole life -- the server holds that and nothing more --
+ * so a trigger computed against 256k fires after the window has already
+ * overflowed. The effective grant counts a shared prefix riding above a
+ * private budget. Larger than configured is not a reason to size up: the
+ * configured window is what the rest of the session (the output cap, the
+ * prompt) was built for.
+ */
+export declare function resolveGrantedContextWindow(sessionId: string | undefined, providerId: string | undefined, configuredWindow: number | undefined): number | undefined;
+/**
+ * After a compaction: the session goes on from its prefix pool plus the replay.
+ *
+ * The conversation still opens with the system prompt and tools the session's
+ * pool (its own root, or its place in the lead tree) already covers, so there
+ * is nothing to fork: the next request attaches to that pool and prefills the
+ * replay after it. What is left to do is give back the cells the session's
+ * slot still holds for the transcript the replay replaced -- unless the
+ * compaction already did (`continuation-compaction.ts` releases them before
+ * the synthesizer runs).
+ *
+ * Only where a pool covers the head: a session whose prefix lives in its slot
+ * alone would pay for it again. A held booking keeps its window -- the
+ * conversation goes on in it -- and only the slot is erased; a session with no
+ * booking is closed, which drops the slot and books nothing. A borrowed pool
+ * (a swarm worker) is left exactly as it is.
+ *
+ * Returns the pool the session stays on, or `undefined` when it has none.
+ */
+export declare function repointPolykvAfterCompaction(options: {
+    sessionId: string | undefined;
+    providerConfig: PolykvProviderConfig;
+    /** The compaction already dropped the session's slot cells. */
+    sessionCellsReleased?: boolean;
+    logger?: BasicLogger;
+}): Promise<string | undefined>;
+/**
+ * End a session: release its pool, then give its window back.
+ *
+ * The one call that stops a leak, and it now stops two of them. The pool half
+ * is unpin-then-release, which is what keeps a pinned prefix from blocking
+ * reclaim forever. The window half is `POST /sessions/{id}/close`, and without
+ * it a guaranteed allocation stays booked for the server's idle TTL -- five
+ * minutes on the build this was written against -- so a user who ends one 256k
+ * conversation and opens another waits out their own last session.
+ *
+ * **The window is released even when there was never a pool.** A session can
+ * book a window with pooling off, or before a pool has been built, and gating
+ * the close on pool state would leak exactly those -- which are the expensive
+ * ones, since the whole allocation is held rather than a prefix.
+ */
+export declare function releasePolykvSession(options: {
+    sessionId: string | undefined;
+    providerConfig: PolykvProviderConfig;
+    logger?: BasicLogger;
+}): Promise<void>;
+/**
+ * Snapshot a session's live context into a pool the workers can share.
+ *
+ * `from_session` first: the engine takes the prefix from the slot's own token
+ * history, so no tokens cross the wire and the failure class this module was
+ * written to fix -- a client-tokenised prefix that does not match the prefilled
+ * one -- cannot arise on that path at all.
+ *
+ * **When this runs matters as much as what it does.** The host prompt cache
+ * saves and clears idle slots the moment any new task launches, so the snapshot
+ * has to be taken at the end of the lead's turn, before any worker starts. Taken
+ * late it captures a slot that has already been cleared.
+ *
+ * `ephemeral` so the engine's own sweep can reclaim it if this process dies
+ * mid-round. That is the crash net; {@link releasePolykvPool} is the plan.
+ *
+ * **And it is refused often.** The engine's own soak against the shipped
+ * bytes saw `400` on 331 of 715 `from_session` creates. That is correct
+ * behaviour rather than a fault: the snapshot comes from the cache resident in
+ * the session's LAST slot, and once that slot has been bound to someone else
+ * the session has no affinity left -- refusing beats building this session's
+ * pool out of another session's context. The rate rises exactly when a swarm is
+ * most worth running, because it tracks how hard the slots are churning.
+ *
+ * So a refusal falls back to **borrowing the session's own root pool**, which
+ * is still pinned and still holds the system prompt and the tool schemas --
+ * about a third of the window by measurement. The workers share most of what
+ * matters instead of re-prefilling the lead's entire context each.
+ *
+ * A borrowed pool is marked, and **the caller must not release it**: it belongs
+ * to the lead and is serving the conversation. Dropping it at the end of a
+ * round would unpin the prefix the lead is still using, which is worse than the
+ * unpooled round this fallback exists to avoid.
+ *
+ * `undefined` only when there is nothing to borrow either, which lets the
+ * caller run the round unpooled rather than fail it.
+ */
+export declare function snapshotPolykvSession(options: {
+    sessionId: string | undefined;
+    providerConfig: PolykvProviderConfig;
+    logger?: BasicLogger;
+}): Promise<PolykvSnapshot | undefined>;
+export interface PolykvSnapshot {
+    poolId: string;
+    prefixTokens: number;
+    /**
+     * This pool was not created for the round and is not the round's to drop.
+     *
+     * It is the lead's root pool, pinned and serving the conversation. A caller
+     * that releases it unpins the prefix the lead is still using.
+     */
+    borrowed?: boolean;
+}
+/**
+ * Release a pool this process created, whatever happened to the work on it.
+ *
+ * Unpin first, always. The engine will not reclaim a pinned pool, and a pin
+ * left on an abandoned subtree blocks reclaim forever -- which is the leak the
+ * whole of this module's release discipline exists to prevent.
+ */
+export declare function releasePolykvPool(options: {
+    poolId: string;
+    providerConfig: PolykvProviderConfig;
+    logger?: BasicLogger;
+}): Promise<void>;

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

@@ -0,0 +1,90 @@
+/**
+ * Compaction for the strategy that keeps the last messages.
+ *
+ * The existing prompt asks for a hand-over note, and a note is the wrong
+ * artifact here. When a recency tail is kept, the summary is **prepended to
+ * messages that are still in the transcript** — the model reads it and then
+ * reads its own last few turns. A note changes voice mid-stream: the model
+ * goes from being told *about* a conversation, in the third person and the
+ * past tense, straight into its own first-person turns. The seam is visible
+ * and the model writes from the wrong side of it.
+ *
+ * So this prompt asks for a replay instead: the same voice as the messages it
+ * will sit in front of, first person, **in the present tense**. The model is
+ * not reporting on a session, it is re-telling its own.
+ *
+ * The tense is load-bearing and was wrong. A replay written in the past tense
+ * reads as history -- "The user asked me to fix the collision", "the editor
+ * then warned me the line numbers had shifted" -- and a model reading that in
+ * front of its own live turns treats the facts as old and possibly stale. It
+ * re-reads files it already knows, re-derives conclusions it already has, and
+ * discounts a warning that is still in force. Reported from a 29-minute
+ * pandorum run where the model kept working but stopped being efficient.
+ *
+ * Present tense makes the same sentences current: "The user is asking me",
+ * "Let me start by", "the editor is warning me this change shifted the line
+ * numbers by +11". Nothing about the content changes; only whether the model
+ * reads it as the state of play or as a story about one.
+ *
+ * Asking was not enough on its own, and the two reasons it was not are both
+ * in this file's history. The instruction was carried by a two-column table
+ * whose left half printed the phrasings it forbade, and a pandorum summary
+ * came back with that column nearly verbatim -- "I started by running the
+ * diagnostic" against a row reading "I started by reading the file". A
+ * negative exemplar is still an exemplar. And the prompt labelled five of its
+ * own sections in the past tense -- "What you were asked", "What you did",
+ * "Where you had got to" -- while demanding the present in its second
+ * paragraph. What came back was a present-tense opening and closing around a
+ * wholly past-tense body, which is the shape of a prompt disagreeing with
+ * itself. Only the column that shows what to write is left, and the labels
+ * are in the tense they ask for.
+ *
+ * Two things the replay must carry that a note gets away with omitting:
+ *
+ * - **The user's own words, verbatim.** A paraphrased instruction is the one
+ *   loss that cannot be recovered from anywhere else — the files are on disk
+ *   and the tool record is rebuilt by the harness, but what was asked exists
+ *   only in the transcript being discarded.
+ * - **Its tool calls, with what came back.** Trimmed, because a model asked to
+ *   replay its work pastes whole file bodies back, which is precisely what
+ *   compaction exists to remove arriving inside the thing meant to remove it.
+ *   `trimReplayOverflow` is the backstop for when it does that anyway.
+ *
+ * The harness places the tool ledger between this replay and the retained
+ * messages, so the model's own account and the measured one sit side by side
+ * and any disagreement is visible rather than silent.
+ */
+/** The instruction, when the recency tail is kept. */
+export declare const DEFAULT_REPLAY_COMPACTION_PROMPT = "Your transcript has grown too long and the earlier part of it is about to be discarded. Write the replay that takes its place.\n\nYour replay will be **prepended directly to the messages that remain** \u2014 your own most recent turns, which are still there and which you will read immediately after this. Write it so that seam is invisible.\n\nWrite in the **first person, present continuous tense**, in your own voice, in the same prose as the turns it sits in front of. You are not reporting on a session to someone else and you are not recounting something finished: you are picking the work back up, and everything in the replay is the situation as it stands right now.\n\nWrite **every step** as the step itself, then what came back. The opening of a\nstep is what you are about to do; the outcome is its own short sentence after\nit. These are the shapes \u2014 reuse them:\n\n- \"The user is asking me to fix the collision.\"\n- \"Let me start by reading the file.\"\n- \"Let me read a large chunk of the file.\" \u2014 then what it showed.\n- \"Let me try reconstructing the script section. It failed: `check_file` reports an unterminated regular expression at line 274.\"\n- \"Now the editor is warning me this change shifted the line numbers by +11.\"\n- \"The file parses now, so what is left is the collision check.\"\n\nThis holds for the middle of the replay and not only its first and last\nsentences. A step that opens by reporting itself has changed voice, and the\nseam this replay exists to remove is back.\n\nWritten in the past tense the replay reads as history, and history is something you are entitled to doubt: you will re-read files you already know, re-derive what you have already settled, and treat a warning that is still in force as something that merely once happened. Written in the present it is the state of play, which is what it actually is. Every sentence, not only the first and the last.\n\nCarry all of this:\n\n- **What you are asked to do, verbatim.** Quote the instructions you have been given word for word. Everything else here can be rebuilt from the files or from the record below your replay; what was asked exists nowhere else once these messages are gone.\n- **What you have done, in order.** Narrate it, and **cite the calls instead of writing them out.** Every call you made, with its arguments and what it returned, is numbered in the record below. Where a call belongs in your account, put its number in square brackets with a `#`, and carry on:\n\n  \"Let me run the checker. [#3] It reports a `SyntaxError` at line 90.\"\n\n  The harness puts call 3 in at that point, exactly as it happened. Writing the call out yourself instead would spend your budget copying a record that is already exact, and yours would be the less accurate of the two. Cite each call once, in the order you made them. Where a run of calls in sequence belongs at the same point \u2014 the same check repeated, a read and the edit that followed it \u2014 cite the span as `[#2-5]` rather than one at a time; the harness puts all of them in there. A number you leave out is not lost \u2014 it is added at the end \u2014 but then it sits away from the step it belongs to.\n\n  **The record is complete and closed.** Every call you have made is in it, and nothing else is. The highest number in it is the last call you made, so there is no `[#N]` past the end to cite \u2014 if you find yourself reaching for one, the step you are about to describe is a step you have not taken yet, and it does not belong in an account of what you have done. Cite only a number that is actually in the record, and leave a step with no call behind it uncited rather than attaching it to a number that names someone else's work.\n- **What is coming back wrong**, and what you are doing about it. A call that was refused or returned an error is the most important kind to keep \u2014 without it you will simply make it again.\n- **What you have concluded**, including anything you have ruled out and why. An approach that failed, omitted here, is an approach you will try again.\n- **Where you are now**, and what you are about to do next.\n\nDo not invent anything you are not sure of. In particular, do not report a result you cannot see: a call whose output is not in front of you is a call whose outcome you do not know, and writing that it succeeded is the one error here that the next turn cannot recover from.\n\nDo not write instructions to yourself to rewrite or restore content that this replay does not itself contain \u2014 you would be reconstructing from memory something that is still on disk, and producing a worse version of it.\n\nWrite the replay and stop. Do not continue the transcript that follows these instructions, and do not copy any part of it back: it is what you are replacing.";
+export interface CutTranscript {
+    text: string;
+    /** How much of the summary was the request, copied back. */
+    cutChars: number;
+}
+export declare function cutEchoedTranscript(text: string): CutTranscript;
+export interface ReplayBlockLimits {
+    /** Longest a fenced block may be before the harness elides its middle. */
+    maxBlockChars: number;
+}
+export declare const REPLAY_BLOCK_LIMITS: ReplayBlockLimits;
+export interface TrimmedReplay {
+    text: string;
+    /** How many blocks the harness had to cut because the model did not. */
+    trimmedBlocks: number;
+}
+/**
+ * Cut the payloads the model was asked to trim and did not.
+ *
+ * Only fenced blocks are touched. A length rule that cannot tell a pasted file
+ * from the prose around it would cut the summary itself, and the prose *is*
+ * the artifact — a long replay of a long session is correct. So the prose is
+ * never trimmed here however long it runs; the request budget is what bounds
+ * that, and it bounds it by asking again rather than by silently deleting the
+ * middle of a sentence.
+ *
+ * An unterminated fence is treated as running to the end of the text. A model
+ * that exhausts its budget mid-block leaves one open, and the summary is still
+ * the only record of that stretch — dropping it to punish the malformed fence
+ * would discard the very thing being preserved.
+ */
+export declare function trimReplayOverflow(text: string, limits?: Partial<ReplayBlockLimits>): TrimmedReplay;

package/dist/extensions/context/tool-ledger.d.ts

@@ -0,0 +1,198 @@
+/**
+ * What the tools did, for a transcript that is about to be discarded.
+ *
+ * Both compaction strategies need this and neither can get it from the model.
+ * A summary is the model's account of its own work, and the one thing it is
+ * measurably worst at is remembering which calls it actually made: it
+ * reconstructs plausible ones, drops the refused ones, and repeats work it has
+ * already done because nothing in the summary said it had. The ledger is the
+ * harness's account of the same stretch, taken from the messages rather than
+ * from the model, and it is appended to the summary rather than requested
+ * inside it.
+ *
+ * Three problems shape the format.
+ *
+ * **Size.** A whole-file write is the largest single thing in any transcript
+ * and the least worth reproducing, because the file is still on disk. So a
+ * long field is never copied — it is measured, and where a revision log is
+ * available the entry names the revision that holds it. That is the trade the
+ * file-revision store already exists to make: an address instead of a body.
+ *
+ * **Repetition.** A stuck run calls the same thing over and over; that is the
+ * behaviour the corpus shows ending runs. Listing forty identical `read_files`
+ * calls buries the four that matter, so identical calls collapse — unless the
+ * *result* changed, which is the one case where the repeat is the story rather
+ * than the noise.
+ *
+ * **Legibility.** The reader is a small model that has just lost its memory.
+ * One line per call, the failures marked, no JSON it has to parse.
+ */
+/**
+ * Any message with a content array, in either of the two block shapes this
+ * repository carries — see {@link normaliseCall}.
+ */
+export interface ToolLedgerMessage {
+    content?: unknown;
+}
+/**
+ * A file the folded stretch touched, and the revisions holding its earlier
+ * content.
+ *
+ * Stated per file rather than per call, and that is a correction. The ledger
+ * used to print `path: #1 → #2` on a call's own line, which reads as a claim
+ * about *that call* -- and the revision log cannot support one: it records
+ * revisions in order with the tool that made each, not which call made which,
+ * and the correspondence breaks exactly where it matters (identical calls are
+ * collapsed into one entry, a refused call makes no revision, and an opaque
+ * writer can make several). A wrong revision number is worse than none,
+ * because the model acts on it by trying to restore it.
+ *
+ * The span is true however the calls line up, and it is what the model needs
+ * anyway: not "what did this call do" -- the result line says that -- but
+ * "where can I get this file's earlier content".
+ */
+export interface ToolLedgerFileHistory {
+    path: string;
+    /** The revisions that exist, e.g. `#1–#7`, or `#1` when there is one. */
+    span: string;
+}
+export interface ToolLedgerEntry {
+    /** 1-based, in the order the calls were made. */
+    index: number;
+    toolName: string;
+    /** The arguments, trimmed and on one line where they fit. */
+    input: string;
+    /** What came back, trimmed. */
+    result: string;
+    /** The call reported an error, or returned a refusal. */
+    failed: boolean;
+    /** How many identical calls this entry stands for. 1 is the common case. */
+    repeated: number;
+    /**
+     * The paths this call named, in the order its arguments gave them.
+     *
+     * Recorded unconditionally, because a path is a fact about the call rather
+     * than a claim about the file. What is held for those paths is answered
+     * once per file by {@link collectFileHistories}.
+     */
+    files: string[];
+}
+export interface ToolLedgerLimits {
+    /** Longest a single scalar field may be before it is elided. */
+    maxFieldChars: number;
+    /** Longest the rendered arguments may be, all fields together. */
+    maxInputChars: number;
+    /** Longest a result may be. */
+    maxResultChars: number;
+    /** A string with at least this many lines is reported as a size. */
+    multilineLineFloor: number;
+}
+export declare const DEFAULT_TOOL_LEDGER_LIMITS: ToolLedgerLimits;
+export interface ToolLedgerOptions {
+    limits?: Partial<ToolLedgerLimits>;
+}
+/**
+ * The revisions held for one file, as a span like `#1–#7`.
+ *
+ * Supplied by the caller because the ledger is pure: it reads messages, and
+ * the revision log lives with the session. Nothing for a file the log does not
+ * track, which is most of them — an untracked file simply does not appear.
+ */
+export type RevisionSpanLookup = (path: string) => string | undefined;
+/**
+ * Pair the calls in a stretch of messages with their results.
+ *
+ * Paired by call id, never by position: a turn can issue several calls and
+ * their results arrive in one message, so counting on order puts the wrong
+ * answer against the wrong call — which reads as a tool that returned
+ * something it never returned.
+ */
+export declare function buildToolLedger(messages: readonly ToolLedgerMessage[], options?: ToolLedgerOptions): ToolLedgerEntry[];
+/**
+ * Concatenate a carried ledger with this compaction's own, as one run.
+ *
+ * The seam is where the repeat rule matters most: a checker run just before a
+ * compaction and again just after is one fact reported twice, and it is the
+ * call most likely to repeat because it follows every edit. So the same rule
+ * `buildToolLedger` applies within a stretch is applied across the join —
+ * same tool, same arguments, same answer collapses; a changed answer does not,
+ * because a changed answer is the most informative pair in the record.
+ */
+export declare function mergeToolLedger(previous: readonly ToolLedgerEntry[], next: readonly ToolLedgerEntry[]): ToolLedgerEntry[];
+/**
+ * Bring a carried ledger back under budget, losing the recoverable calls
+ * first.
+ *
+ * Three tiers, oldest first within each: successful non-verdict calls, then
+ * failed non-verdict calls, then anything that returned a verdict. A refused
+ * read outranks a successful one because the summary is measurably worst at
+ * keeping refusals, and without it the model simply makes the call again.
+ *
+ * Eviction rather than truncation, because a ledger is a record: half an entry
+ * says something that did not happen, where a missing entry only fails to say
+ * something that did.
+ */
+export declare function evictToolLedger(entries: readonly ToolLedgerEntry[], budgetChars: number): ToolLedgerEntry[];
+/**
+ * The ledger as the model will read it.
+ *
+ * One line per call, the marks where the eye lands rather than at the end of a
+ * long line: a reader scanning for what went wrong should not have to finish
+ * every line to find out.
+ */
+/** One entry, as it prints in the ledger and inline in a replay. */
+export declare function renderToolLedgerEntry(entry: ToolLedgerEntry): string;
+/**
+ * The numbering key the replay cites against: which call is which, and
+ * nothing else.
+ *
+ * Deliberately without the results. The writer needs to know that call 7 is
+ * the checker run, not what the checker said -- it has the conversation for
+ * that, and the results are the bulk of the ledger. Sending them would also
+ * undo a budget decision made elsewhere: a long tool result is truncated on
+ * its way into the transcript, while the ledger elides the middle and keeps
+ * the tail, so the full ledger hands back a fragment the transcript had
+ * deliberately cut.
+ */
+export declare function renderToolLedgerKey(entries: readonly ToolLedgerEntry[]): string;
+export interface LedgerSpliceResult {
+    text: string;
+    /** Entries the replay placed itself, in the order it placed them. */
+    cited: number[];
+    /** Entries it did not, appended after the prose so nothing is lost. */
+    uncited: number[];
+    /**
+     * Citations naming a call that does not exist, or naming one twice.
+     *
+     * Dropped from the text, counted here. Measured on pandorum: a replay
+     * citing `[#31]`–`[#33]` against a 30-entry ledger, which is the model
+     * narrating steps it did not take — the bad number is discarded but the
+     * invented sentence around it stays, so this is the only signal that the
+     * prose has run past the record.
+     */
+    invalid: number[];
+}
+/**
+ * Put each call where the replay says it happened.
+ *
+ * The replay narrates the work and the ledger records the calls, in the same
+ * order, so the writer is asked for a citation rather than a transcription:
+ * `[#7]` costs it four tokens where writing the call out cost four hundred.
+ * Measured before this existed, tool transcription took 69% of a small model's
+ * whole output budget and the prose was cut off mid-sentence.
+ *
+ * Every way this can go wrong degrades to what it replaced. A citation naming
+ * an entry that does not exist, or one already used, is dropped; an entry the
+ * replay never cites is appended at the end. The worst case is a ledger block
+ * after the prose, which is where the ledger sat anyway.
+ */
+export declare function spliceLedgerCitations(replay: string, entries: readonly ToolLedgerEntry[]): LedgerSpliceResult;
+export declare function renderToolLedger(entries: readonly ToolLedgerEntry[], histories?: readonly ToolLedgerFileHistory[]): string;
+/**
+ * The files the ledger touched that the revision log still holds, once each.
+ *
+ * First-touched order rather than sorted: the ledger is read top to bottom and
+ * a file's place in that order is the reader's way back to the calls it
+ * belongs to.
+ */
+export declare function collectFileHistories(entries: readonly ToolLedgerEntry[], spanFor: RevisionSpanLookup | undefined): ToolLedgerFileHistory[];