@cubicecho/agent-core 2.12.0 → 2.14.0

package/README.md

@@ -29,7 +29,7 @@ only, Node >=22.
 | `hooks` | The host's side of lifecycle hooks: `gather` before a request and `notify` after, the shared context budget, `withContext` to put what they add on the turn's question, `untrusted` to fence text nobody vouched for, and `turnMessages` to hand them a transcript. Running a hook is a runner the caller passes. |
 | `events` | The in-memory bus a watcher reads while a run happens: `emit`, `watch`, `history`, `fold`, and `runMetrics` for what a run cost. A watcher's backlog is capped and reports its own gaps. |
 | `client` | A pooled `OpenAI` client per endpoint, plus the context window: the served one where a local server says, the listed one otherwise, and their caches. |
-| `retry` | What to do when a request is lost, refused or too big: `isTransient`, `isModelLoading`, `backoffMs`, `ContextOverflow`, `EndpointSilent`, `requestTokens`. |
+| `retry` | What to do when a request is lost, refused or too big: `isTransient`, `isModelLoading`, `backoffMs`, `ContextOverflow`, `EndpointSilent`, `requestTokens`, `contextTokens`. |
 | `calibration` | How many characters a token is worth on one model, learned from the prompt counts its endpoint reports: `charsPerTokenFor`, `calibrate`. |
 | `continuation` | `continueTurn`: carries on an answer the token ceiling cut off, by prefilling it as a trailing assistant message. |
 | `config` | The structural interfaces every function here asks for. |
@@ -314,6 +314,35 @@ for up to `loadingTimeoutMs` (two minutes by default, zero to turn it off) witho
 `maxRetries`, with one notice at the start. `runAgentLoop` reads it as `loadingTimeoutSeconds` off
 the config. A 503 that says nothing about loading stays on the ordinary backoff.
 
+### What is filling the window
+
+A total tells an operator a run is close to the edge and nothing about what to do next, so
+`contextTokens` cuts the same body four ways, along the four levers there are: `system` is the
+system and developer messages, which means shortening the prompt; `tools` is the declared schemas,
+which means loading them on demand instead of declaring them whole; `toolResults` is exactly the
+`tool` messages, which is precisely what `pruneToolResults` shrinks; and `history` is everything
+else, which is what compaction folds, the arguments of the calls in it included.
+
+```ts
+const { system, tools, history, toolResults, total } = contextTokens(body, {
+  charsPerToken: charsPerTokenFor(supports, config.model),
+  // Optional: what the endpoint said the prompt cost, once a turn has come back.
+  promptTokens: turn.usage?.prompt_tokens,
+});
+```
+
+The parts are shares of one total rather than four separate estimates, because a readout whose
+parts do not add up to the number beside them is one nobody trusts; the largest part absorbs the
+rounding, so they sum exactly. Nothing in the round trip reports anything finer than a prompt
+count — a completion says how many tokens it read and not a word about where they came from — so
+the proportions are a guess whatever the total is, and `contextChars` is there for a caller that
+wants the exact characters underneath them.
+
+Given a `promptTokens` the total is what was charged and every part is a share of it. Without one
+the total is `requestTokens`, and the tool block is counted the way `requestTokens` and
+`TurnMetrics.toolSchemaTokens` count it rather than shared out, so the breakdown and the metrics
+line cannot disagree about the same tool list.
+
 ## The loop
 
 `runAgentLoop` is the part of an agent that three servers had each written, and that had drifted
@@ -365,8 +394,17 @@ and — naming only tools that exist — a reply that is only a JSON call or hol
 Found calls are run as `call_recovered_0` onward, the text is what is left, `onTurn` and the
 result see the turn that way, and a notice says so, since the real fix is the server's parser.
 
+Every request declares its tools in name order, whichever way the caller assembled the array. A
+chat template renders the tool block ahead of the system prompt, so the tool array is the first
+thing a prompt cache has to match, and an array built from a map, from database rows, or from the
+order servers happened to connect in is a different array on the next boot — the same tools, the
+same run, and the cache for the whole transcript thrown away. Ordering by name makes it a property
+of the set instead. `toolOrder: false` sends the caller's order, for a host that means it — a model
+reads the array top to bottom — and a comparator orders it another way. `orderTools` is the same
+thing for a caller with its own loop, and `buildBody` takes the order as its last argument.
+
 With `toolDiscovery: "ondemand"` and a catalogue, the request declares `load_tools` and what has
-been loaded, appended in the order it was loaded, and the catalogue rides on the system prompt
+been loaded, and the catalogue rides on the system prompt
 unmarked, the same text on every step. Marking loads there rewrote the head of the prompt and lost
 the prompt cache for the whole transcript on each one; a model that loads a tool twice is told in
 the `load_tools` result that it already has it. A model that calls
@@ -513,6 +551,51 @@ way to save tokens.
 `pruneToolResults` keeps the transcript's indexes, so a plan made before pruning still applies to
 what it returns, as above.
 
+### A fold you store, instead of a transcript you rewrite
+
+`compactTranscript` hands back a new array, which is the whole answer for a host whose transcript
+*is* that array. A host that keeps its messages append-only — rows in a database, every one still
+shown in the chat — wants the other half: what the fold was, as something to store on the session.
+`runCompaction` is `compactTranscript` without the rewrite. It returns `{ summary, through, at }`,
+or `undefined` when a hook vetoed or the summary came back empty, and `compactTranscript` is built
+out of it, so there is one summariser and one cut rather than two that drift.
+
+```ts
+const from = session.fold?.through ?? 0;
+const plan = planCompaction(session.messages, {
+  limit,
+  used,
+  from, // where the last fold ended, rather than scanning for it
+  previous: session.fold?.summary,
+});
+if (!plan) return;
+const fold = await runCompaction(session.messages, plan, summarise, { hooks: { run, context } });
+if (fold) await save(session.id, fold); // the messages themselves are never touched
+```
+
+`planCompaction` takes `from` and `previous` because its defaults are a *recovery*: it skips the
+leading `system` messages, and reads an earlier summary back out of a `SUMMARY_LEAD` message among
+them. A host whose system prompt is a separate argument and whose summary is a column has neither
+in the array, and knows both exactly. Given them, nothing is scanned.
+
+`applyCompaction(messages, fold)` is the way back — the summary as a `system` message, then
+everything from `through` — and it writes the same `SUMMARY_LEAD` `planCompaction` looks for, so
+the next fold continues those notes rather than summarising them a second time. No fold yet hands
+back the messages themselves.
+
+```ts
+const request = [systemMessage, ...applyCompaction(session.messages, session.fold)];
+```
+
+**Two numberings.** A stored transcript keeps its indexes and a folded request does not, so
+anything naming a position has to say which one it means. `requestIndex(index, fold)` maps the
+stored index onto the request — for `withContext`'s index, or a range being shown to a hook.
+`turnMessages` takes an `offset`, the stored index of the array's first message, so a message keeps
+the uuid it had before the fold and a memory server deduping on it files that turn once rather than
+twice; `turnIndex` takes one too, for the turns a fold took out of the array it is counting.
+Planning over the stored transcript, as above, sidesteps both: the plan's indexes are the host's
+already, and so are the ones `runCompaction` hands the `beforeCompact` hooks.
+
 ## Watching a run
 
 `watch` replays what the run has already emitted, then yields what happens next until `done`.
@@ -745,7 +828,35 @@ A snapshot names endpoints by `endpointId`, a SHA-256 digest of the URL and key,
 written to a settings row or a file without a credential going with it. Importing merges and only
 latches off, the same as a refusal does. A snapshot of another `version` is ignored. How old is too
 old is left to the consumer, who can read `savedAt` first: a server upgraded between boots may
-accept what it used to refuse, and nothing latched ever unlatches without a reset.
+accept what it used to refuse, and nothing latched ever unlatches on its own.
+
+It unlatches when you say so. A server upgraded behind the same URL — a newer llama.cpp that
+compiles the grammar, a proxy that has learned `stream_options` — keeps being sent the downgraded
+request until something forgets what it refused, and `resetCapabilities` takes the endpoint to
+forget:
+
+```ts
+resetCapabilities({ baseUrl: row.baseUrl, apiKey: row.apiKey });  // this one changed
+expireCapabilities(6 * 60 * 60_000);                              // anything half a day old
+```
+
+`resetCapabilities` with no argument still clears every endpoint, which is what `resetAll` and a
+test mean by it; with one it clears that endpoint alone, so an upgraded local box does not cost the
+cloud endpoint beside it its latches, and returns whether there was anything to forget. Call it
+where the host already knows something changed: a settings row saved, a health check reading a new
+build string, an operator pressing a button.
+
+`expireCapabilities(maxAgeMs)` covers the case where nobody knows, dropping every endpoint older
+than that and returning how many. An expiry does not probe anything — it stops suppressing, so the
+next request carries the field again and a server that still refuses it refuses it once, which
+`negotiate` answers as it always did. At an age measured in hours that is a few extra round trips a
+day against a downgrade that would otherwise last as long as the process. Nothing calls it on a
+timer; when to sweep is yours, the same way how stale a snapshot is too stale is.
+
+An endpoint's age is when it was first met, not when a flag latched, and `exportCapabilities`
+carries it in the snapshot so an imported latch keeps its real age instead of being born again on
+every boot. Importing takes the older of the two ages, and a snapshot written before this field
+existed reads as met now.
 
 ## Where the merged behaviour came from
 

package/dist/agent-loop.d.ts

@@ -5,6 +5,7 @@ import type { Endpoint, ModelParams, RetryPolicy, ToolPolicy } from "./config.ts
 import { type RunEventInput, type RunMetrics } from "./events.ts";
 import { type HookContext, type HookEvent, type HookNote, type HookRunner } from "./hooks.ts";
 import type { Turn, TurnUsage } from "./stream.ts";
+import { type ToolOrder } from "./tool-loading.ts";
 /**
  * The one place a streamed request's body is decided from a config and what the endpoint and
  * the model have refused.
@@ -22,10 +23,13 @@ import type { Turn, TurnUsage } from "./stream.ts";
  * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model
  * that has refused nothing.
  * @param messages The request's messages, system prompt included, sent as they are.
- * @param tools The tool definitions. Sanitised here — a lookup for a definition seen before —
- * and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
+ * @param tools The tool definitions. Ordered by name, sanitised here — a lookup for a definition
+ * seen before — and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
+ * @param order How to order them before sending. `true`, the default, is by name, which keeps the
+ * cache when the caller's array is assembled differently from one request to the next. See
+ * `orderTools`.
  */
-export declare function buildBody(config: ModelParams, supports: Capabilities, refused: ModelCapabilities | undefined, messages: OpenAI.ChatCompletionMessageParam[], tools?: OpenAI.ChatCompletionTool[]): OpenAI.ChatCompletionCreateParamsStreaming;
+export declare function buildBody(config: ModelParams, supports: Capabilities, refused: ModelCapabilities | undefined, messages: OpenAI.ChatCompletionMessageParam[], tools?: OpenAI.ChatCompletionTool[], order?: ToolOrder): OpenAI.ChatCompletionCreateParamsStreaming;
 /**
  * A long tool argument or result cut to what a watcher needs, with the full length said.
  *
@@ -131,6 +135,12 @@ export interface AgentLoopOptions {
     tools?: OpenAI.ChatCompletionTool[];
     /** The same tools as a name-only catalogue. On-demand mode needs it, and is eager without it. */
     catalog?: CatalogServer[];
+    /**
+     * How the declared tools are ordered before each request. By name unless told otherwise, so a
+     * run whose tool array was assembled in a different order than last time still meets its cache.
+     * `false` sends them as given. See `orderTools`.
+     */
+    toolOrder?: ToolOrder;
     /**
      * What `preselect` picked. The first step is sent these and nothing else — no catalogue, no
      * `load_tools` — because a model with the menu still in front of it shops: it reloads what it
@@ -203,7 +213,8 @@ export interface AgentLoopResult {
  * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
  *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
- * prompt unchanged from step to step, loaded tools are appended to the tool array in load order,
+ * prompt unchanged from step to step, a load adds to the tool array — which every request sends
+ * in the stable order `toolOrder` asks for — and
  * a catalogued tool called without being loaded is loaded and run rather than refused, and a
  * preselection shapes the first step. A turn cut off at `maxTokens` is said so as a notice,
  * because it otherwise reads exactly like a finished one — or, given `maxContinuations`, is

package/dist/agent-loop.js

@@ -10,7 +10,7 @@ import { runTurn } from "./run-turn.js";
 import { relaxTools, sanitizeTools } from "./schema-compat.js";
 import { askJson, tryAsk } from "./side-task.js";
 import { parseToolArguments, recoverToolCalls } from "./tool-calls.js";
-import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, orderTools, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
 /**
  * The loop above a turn: send, run the tools the model asked for, send again, until it stops
  * asking.
@@ -40,11 +40,17 @@ const RESERVED = new Set(["model", "messages", "stream", "tools"]);
  * @param refused What the model has refused, as `negotiate` hands it over. Absent is a model
  * that has refused nothing.
  * @param messages The request's messages, system prompt included, sent as they are.
- * @param tools The tool definitions. Sanitised here — a lookup for a definition seen before —
- * and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
+ * @param tools The tool definitions. Ordered by name, sanitised here — a lookup for a definition
+ * seen before — and relaxed where the endpoint needs it. Empty sends no `tools` field at all.
+ * @param order How to order them before sending. `true`, the default, is by name, which keeps the
+ * cache when the caller's array is assembled differently from one request to the next. See
+ * `orderTools`.
  */
-export function buildBody(config, supports, refused, messages, tools = []) {
-    const declared = supports.strictSchemas ? sanitizeTools(tools) : relaxTools(sanitizeTools(tools));
+export function buildBody(config, supports, refused, messages, tools = [], order = true) {
+    const sorted = orderTools(tools, order);
+    const declared = supports.strictSchemas
+        ? sanitizeTools(sorted)
+        : relaxTools(sanitizeTools(sorted));
     const effort = config.reasoningEffort;
     const extra = Object.entries(config.extraBody ?? {}).filter(([field]) => !RESERVED.has(field) && !refused?.refusedFields.has(field));
     return {
@@ -183,7 +189,8 @@ function cacheDiagnosis(previous, messages, tools, usage) {
  * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
  *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
- * prompt unchanged from step to step, loaded tools are appended to the tool array in load order,
+ * prompt unchanged from step to step, a load adds to the tool array — which every request sends
+ * in the stable order `toolOrder` asks for — and
  * a catalogued tool called without being loaded is loaded and run rather than refused, and a
  * preselection shapes the first step. A turn cut off at `maxTokens` is said so as a notice,
  * because it otherwise reads exactly like a finished one — or, given `maxContinuations`, is
@@ -195,7 +202,7 @@ function cacheDiagnosis(previous, messages, tools, usage) {
  */
 export async function runAgentLoop(options) {
     const { config, system = "", tools = [], catalog = [], dispatch, hooks, signal } = options;
-    const { onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, } = options;
+    const { onTurn, beforeStep, parallel = false, recoverToolCalls: recover = true, maxContinuations = 0, toolOrder = true, } = options;
     const started = Date.now();
     // What the loop emitted, less the token deltas, for `runMetrics` at the end. Stamped here rather
     // than by the bus, which the loop does not know about.
@@ -262,11 +269,14 @@ export async function runAgentLoop(options) {
         messages = (await beforeStep?.(messages, step)) ?? messages;
         onEvent({ kind: "turn", text: `turn ${step + 1}` });
         const routed = preselected.length > 0 && step === 0;
-        const declared = routed
+        // Ordered here rather than left to `buildBody`, so `names` below is what the request actually
+        // declared — a diagnosis reading an order the server never saw calls an untouched tool array
+        // `tools-changed`.
+        const declared = orderTools(routed
             ? byName(new Set(preselected))
             : onDemand
                 ? loadedTools([LOAD_TOOLS_DEFINITION], byName(loaded))
-                : tools;
+                : tools, toolOrder);
         // Unmarked, so the system prompt is the same text on every step and a load does not throw
         // away the cache for the whole transcript. What is loaded is said in `declared` and in the
         // `load_tools` result instead. The preselected first step is the one exception, by design.
@@ -275,7 +285,7 @@ export async function runAgentLoop(options) {
             ...(prompt ? [{ role: "system", content: prompt }] : []),
             ...withContext(messages, question ? messages.indexOf(question) : -1, gathered.context, hooks?.preface),
         ];
-        const build = (supported, refused) => buildBody(config, supported, refused, request, declared);
+        const build = (supported, refused) => buildBody(config, supported, refused, request, declared, toolOrder);
         const turnOptions = {
             model: config.model,
             droppable: Object.keys(config.extraBody ?? {}),
@@ -427,7 +437,7 @@ export async function runAgentLoop(options) {
                     used.add(name);
                     const request = { id: call.id, name, args, raw };
                     content = parallel
-                        ? await once(answered, `${name}${normal}`, () => dispatch(request, signal))
+                        ? await once(answered, `${name}\0${normal}`, () => dispatch(request, signal))
                         : await dispatch(request, signal);
                 }
             }

package/dist/capabilities.d.ts

@@ -35,6 +35,17 @@ export interface Capabilities {
      * stopped. Empty until `modelCapabilitiesFor` is asked about a model.
      */
     models: Map<string, ModelCapabilities>;
+    /**
+     * When this entry was opened, as epoch milliseconds: first contact with the endpoint in this
+     * process, or the age an imported snapshot gave it. What `expireCapabilities` measures.
+     *
+     * Not when a flag latched. A flag that latches at all almost always does so on the first
+     * request or two, and an entry that latched nothing has nothing to expire, so the difference
+     * costs at most one retried field somewhat earlier than it was due — which is the direction to
+     * be wrong in. Stamping each latch instead would mean stamping it in four modules and
+     * remembering to in the fifth.
+     */
+    since: number;
 }
 /**
  * What one model on that endpoint turned out not to support. All start optimistic and only ever
@@ -124,8 +135,41 @@ export declare const knownCapabilities: () => ReadonlyMap<string, Capabilities>;
  * `importCapabilities` reaches an endpoint it has only a digest for.
  */
 export declare function capabilitiesById(id: string): Capabilities;
-/** Forgets every endpoint's capabilities. For tests, and for a settings change under test. */
-export declare function resetCapabilities(): void;
+/**
+ * Forgets what one endpoint refused, or every endpoint's when told none.
+ *
+ * A latch never unlatches on its own, so a server upgraded behind the same URL — a newer
+ * llama.cpp that compiles the grammar, a proxy that has learned `stream_options` — keeps being
+ * sent the downgraded request for the life of the process. This is the seam for a consumer that
+ * *knows* it changed: a settings row saved, a health check that reads a new build string, an
+ * operator pressing a button. See `expireCapabilities` for the case where nobody knows.
+ *
+ * @param endpoint Whose to forget, by the same identity `capabilitiesFor` takes. Absent clears
+ * every endpoint, which is what tests and `resetAll` mean by it.
+ * @returns Whether there was anything to forget.
+ */
+export declare function resetCapabilities(endpoint?: {
+    baseUrl: string;
+    apiKey?: string;
+}): boolean;
+/**
+ * Forgets every endpoint whose entry is older than this, so the next request finds out again.
+ *
+ * The other half of the problem `resetCapabilities` solves: a server upgraded behind the same URL
+ * with nobody to notice. What an expiry costs is one round trip per endpoint and model — the next
+ * request carries the field again, and a server that still refuses it refuses it once and
+ * `negotiate` re-sends — so at an age measured in hours it is a few requests a day against a
+ * downgrade that would otherwise last as long as the process. That is the trade `exportCapabilities`
+ * exists to avoid paying *per restart*; paying it per day is a different bargain.
+ *
+ * Nothing calls this on a timer. When to sweep is the consumer's, the same way how stale a
+ * snapshot is too stale is, and a sweep costs a walk of one settings row's worth of entries.
+ *
+ * @param maxAgeMs How old an entry may be. Zero or less expires everything.
+ * @param now The clock, for tests.
+ * @returns How many endpoints were forgotten.
+ */
+export declare function expireCapabilities(maxAgeMs: number, now?: number): number;
 /** What `negotiate` takes besides the request. All optional. */
 export interface NegotiateOptions {
     /**

package/dist/capabilities.js

@@ -71,14 +71,58 @@ export const knownCapabilities = () => capabilities;
 export function capabilitiesById(id) {
     let known = capabilities.get(id);
     if (!known) {
-        known = { strictSchemas: true, usageInStream: true, models: new Map() };
+        known = { strictSchemas: true, usageInStream: true, models: new Map(), since: Date.now() };
         capabilities.set(id, known);
     }
     return known;
 }
-/** Forgets every endpoint's capabilities. For tests, and for a settings change under test. */
-export function resetCapabilities() {
-    capabilities.clear();
+/**
+ * Forgets what one endpoint refused, or every endpoint's when told none.
+ *
+ * A latch never unlatches on its own, so a server upgraded behind the same URL — a newer
+ * llama.cpp that compiles the grammar, a proxy that has learned `stream_options` — keeps being
+ * sent the downgraded request for the life of the process. This is the seam for a consumer that
+ * *knows* it changed: a settings row saved, a health check that reads a new build string, an
+ * operator pressing a button. See `expireCapabilities` for the case where nobody knows.
+ *
+ * @param endpoint Whose to forget, by the same identity `capabilitiesFor` takes. Absent clears
+ * every endpoint, which is what tests and `resetAll` mean by it.
+ * @returns Whether there was anything to forget.
+ */
+export function resetCapabilities(endpoint) {
+    if (!endpoint) {
+        const held = capabilities.size > 0;
+        capabilities.clear();
+        return held;
+    }
+    return capabilities.delete(endpointId(endpoint));
+}
+/**
+ * Forgets every endpoint whose entry is older than this, so the next request finds out again.
+ *
+ * The other half of the problem `resetCapabilities` solves: a server upgraded behind the same URL
+ * with nobody to notice. What an expiry costs is one round trip per endpoint and model — the next
+ * request carries the field again, and a server that still refuses it refuses it once and
+ * `negotiate` re-sends — so at an age measured in hours it is a few requests a day against a
+ * downgrade that would otherwise last as long as the process. That is the trade `exportCapabilities`
+ * exists to avoid paying *per restart*; paying it per day is a different bargain.
+ *
+ * Nothing calls this on a timer. When to sweep is the consumer's, the same way how stale a
+ * snapshot is too stale is, and a sweep costs a walk of one settings row's worth of entries.
+ *
+ * @param maxAgeMs How old an entry may be. Zero or less expires everything.
+ * @param now The clock, for tests.
+ * @returns How many endpoints were forgotten.
+ */
+export function expireCapabilities(maxAgeMs, now = Date.now()) {
+    let dropped = 0;
+    for (const [id, known] of capabilities) {
+        if (now - known.since < maxAgeMs)
+            continue;
+        capabilities.delete(id);
+        dropped++;
+    }
+    return dropped;
 }
 /**
  * Every latching flag in play on one attempt, endpoint and model together, in a stable order.

package/dist/compaction.d.ts

@@ -70,6 +70,16 @@ export interface CompactionOptions {
      * an `estimate` of the caller's own.
      */
     charsPerToken?: number;
+    /**
+     * The first message that may be folded. Absent, the leading `system` messages are skipped and
+     * the fold starts after them.
+     */
+    from?: number;
+    /**
+     * The summary an earlier fold left, which this one continues. Absent, it is recovered from a
+     * `SUMMARY_LEAD` system message at the head, if there is one.
+     */
+    previous?: string;
 }
 /** Where to cut, as `compactTranscript` takes it. */
 export interface CompactionPlan {
@@ -92,10 +102,16 @@ export interface CompactionPlan {
  * than summarised as if it were conversation. No plan comes back when the window is not full
  * enough, or when the only legal cut folds too little to pay for the summary.
  *
+ * Both of those are recovered by reading the transcript, which is what a host whose array holds
+ * everything it sends has to do. A host that keeps its fold as a record beside an append-only
+ * transcript — its system prompt a separate argument, no summary message in the array at all —
+ * knows them exactly, and passes `from` and `previous` instead of hoping the scan agrees.
+ *
  * @param messages The transcript, system prompts included if the caller keeps them in it.
- * @param options The window, what is in use, and the ratios. See `CompactionOptions`.
+ * @param options The window, what is in use, the ratios, and where the last fold ended. See
+ * `CompactionOptions`.
  */
-export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, charsPerToken, estimate, }: CompactionOptions): CompactionPlan | undefined;
+export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, charsPerToken, estimate, from: givenFrom, previous: givenPrevious, }: CompactionOptions): CompactionPlan | undefined;
 /**
  * What the summariser is handed for a plan: the earlier summary if there was one, then each
  * message as its role and at most 4000 characters of its text.
@@ -114,6 +130,93 @@ export declare function summaryInput(plan: CompactionPlan): string;
 export declare const summariser: (config: Endpoint, model: string, { system, maxTokens, ...options }?: SideTaskOptions & {
     system?: string;
 }) => (text: string) => Promise<string>;
+/**
+ * One fold, as a host that keeps its transcript append-only stores it.
+ *
+ * The other half of `compactTranscript`: the same work, recorded rather than applied. A host that
+ * persists this beside an untouched transcript still shows the user every message, can undo a fold
+ * by dropping one row, and rebuilds the request with `applyCompaction` — where a host that keeps
+ * only the rewritten array has thrown the originals away.
+ */
+export interface CompactionRecord {
+    /** The model's notes on everything before `through`. Trimmed, and never empty. */
+    summary: string;
+    /** Index into the transcript the plan was made for: the first message still sent whole. */
+    through: number;
+    /** ISO 8601, so the chat can show where history was folded and how stale the notes are. */
+    at: string;
+}
+/** What `runCompaction` and `compactTranscript` take beside the plan. */
+export interface CompactionRunOptions {
+    /**
+     * Hooks to tell. `context` is extended with `compacting` and `range`, whose indexes are the
+     * plan's — and so the host's own, for a plan made over a stored transcript. `honourVeto` waits
+     * for the hooks and lets one stop the compaction; off by default, which adds no latency.
+     */
+    hooks?: {
+        run: HookRunner;
+        context: HookContext;
+        onNote?: (note: HookNote) => void;
+        honourVeto?: boolean;
+    };
+    /**
+     * The window is already exceeded — the caller caught a `ContextOverflow`, or is compacting to
+     * make a refused request fit — which overrides `honourVeto`.
+     */
+    forced?: boolean;
+}
+/**
+ * The hooks and the summariser for a plan, as a record to store rather than a transcript to send.
+ *
+ * What `compactTranscript` does before it rewrites anything, which is all a host needs when the
+ * fold lives on the session row and the messages stay where they are. Nothing here is persisted or
+ * logged — that is the host's, and so is deciding what to do with a fold that did not happen.
+ *
+ * @param messages The transcript the plan was made for. Read only, and only for the hooks.
+ * @param plan What `planCompaction` returned for it.
+ * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
+ * when a hook vetoes.
+ * @param options Hooks to tell and whether the window is already past. See `CompactionRunOptions`.
+ * @returns `undefined` when nothing was folded — a hook vetoed, or the summary came back empty —
+ * so the caller stores nothing and the transcript is still whole.
+ */
+export declare function runCompaction(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, { hooks, forced }?: CompactionRunOptions): Promise<CompactionRecord | undefined>;
+/**
+ * The transcript as the server should see it: the folded head replaced by its summary.
+ *
+ * The inverse of storing a `CompactionRecord`, and the shape `planCompaction` expects to meet
+ * again — the same `SUMMARY_LEAD`, in a `system` message at the same place — so the next fold
+ * continues these notes rather than summarising them a second time. Any earlier summary message in
+ * the kept head is dropped, since the record's already contains it.
+ *
+ * @param messages The stored transcript, whole. Not written to.
+ * @param record The fold, or `undefined` for a session that has not been compacted, which hands
+ * back `messages` itself.
+ * @param options `from` is the first message the fold was allowed to take — the plan's, for a host
+ * that keeps its system prompts in the array; everything before it is kept ahead of the summary.
+ * Absent, the leading `system` messages are found by scanning, and zero of them is the ordinary
+ * case for a host whose system prompt is a separate argument.
+ */
+export declare function applyCompaction(messages: Message[], record?: Pick<CompactionRecord, "summary" | "through">, { from }?: {
+    from?: number;
+}): Message[];
+/**
+ * Where a stored index sits in the request `applyCompaction` builds, once a fold has shifted
+ * everything after it.
+ *
+ * A transcript that stays append-only and a request that does not are two numberings of the same
+ * conversation, and anything that names a position — `withContext`'s index, a range handed to a
+ * hook — has to say which it is in. An index inside the folded stretch answers with the summary
+ * message that now stands for it.
+ *
+ * @param index The position in the stored transcript.
+ * @param record The fold in force, or `undefined` for a session that has none, which hands the
+ * index straight back.
+ * @param head How many messages the request keeps ahead of the summary — the leading system
+ * prompts, when the host keeps them in the array. Zero, the default, is the stored-fold case,
+ * where the summary is the request's first message.
+ */
+export declare const requestIndex: (index: number, record?: Pick<CompactionRecord, "through">, head?: number) => number;
 /**
  * The transcript with the plan's stretch replaced by one system message holding its summary.
  *
@@ -127,25 +230,18 @@ export declare const summariser: (config: Endpoint, model: string, { system, max
  * `ContextOverflow`. An empty summary folds nothing either. Rewrites the prefix; see the module
  * comment on when to run it.
  *
+ * `runCompaction` and `applyCompaction` are its two halves, and it is nothing but the two in
+ * order, so a host that stores the fold instead of the array gets the same summary at the same
+ * cut rather than a second implementation that drifts from this one.
+ *
  * @param messages The transcript the plan was made for. Not written to.
  * @param plan What `planCompaction` returned for it.
  * @param summarise Writes the summary from `summaryInput`'s text. See `summariser`. Not called
  * when a hook vetoes.
- * @param options Hooks to tell. `context` is extended with `compacting` and `range`, whose
- * indexes are the plan's. `honourVeto` waits for the hooks and lets one stop the compaction; off
- * by default, which adds no latency. `forced` says the window is already exceeded — the caller
- * caught a `ContextOverflow`, or is compacting to make a refused request fit — and overrides
- * `honourVeto`.
+ * @param options Hooks to tell and whether the window is already past. See
+ * `CompactionRunOptions`.
  * @returns `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
  * new array.
  */
-export declare function compactTranscript(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, { hooks, forced, }?: {
-    hooks?: {
-        run: HookRunner;
-        context: HookContext;
-        onNote?: (note: HookNote) => void;
-        honourVeto?: boolean;
-    };
-    forced?: boolean;
-}): Promise<Message[]>;
+export declare function compactTranscript(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, options?: CompactionRunOptions): Promise<Message[]>;
 export {};