@cubicecho/agent-core 2.11.0 → 2.13.0

package/dist/calibration.d.ts

@@ -0,0 +1,33 @@
+import type OpenAI from "openai";
+import type { Capabilities } from "./capabilities.ts";
+/**
+ * The characters per token to size a request to this model with, `CHARS_PER_TOKEN` until a turn
+ * has reported one.
+ *
+ * The highest of the model's last few readings rather than their mean. The estimate guards a
+ * window, and `estimateTokens` says which side of wrong that should be on: a count that comes out
+ * high refuses a run that would have fit, one that comes out low only costs the round trip the
+ * guard was saving. The highest ratio is the lowest count, and the last few rather than all of
+ * them because a run's transcript grows by appending, so the latest requests are the best
+ * likeness of the next.
+ *
+ * @param supports The endpoint, as `capabilitiesFor` hands it over.
+ * @param model The name the endpoint knows the model as, as it goes in the body.
+ */
+export declare function charsPerTokenFor(supports: Capabilities, model: string): number;
+/**
+ * Takes one reading from a request that was answered, so the next one to this model is sized by it.
+ *
+ * `runTurn` calls it after every turn whose prompt was reported, so a caller using that has
+ * nothing to do. A request carrying an image or audio is not read: a vision model charges a
+ * picture hundreds of tokens its characters say nothing about. Neither is a reading outside what a
+ * tokenizer could produce, which is a miscount and not a tokenizer.
+ *
+ * @param supports The endpoint the request went to.
+ * @param body The request as it was last sent, which names the model.
+ * @param promptTokens The prompt count the endpoint reported for it. Zero or less is no report.
+ * @returns The ratio now in force for the model.
+ */
+export declare function calibrate(supports: Capabilities, body: OpenAI.ChatCompletionCreateParamsStreaming, promptTokens: number): number;
+/** Forgets every reading, so the next request is sized at `CHARS_PER_TOKEN` again. */
+export declare function resetCalibration(): void;

package/dist/calibration.js

@@ -0,0 +1,87 @@
+import { CHARS_PER_TOKEN, requestChars, toolsChars } from "./retry.js";
+/**
+ * How many characters a token is worth on one model, learned from what its endpoint reports.
+ *
+ * Four is right for English prose and wrong for everything a tool-using run is made of: JSON
+ * schemas and tool results pack closer to two or three, so the pre-flight guard let through
+ * requests the endpoint then refused. Every turn comes back with the exact prompt count for a
+ * request whose characters were already counted to size it, so the ratio is there for the taking.
+ *
+ * Kept apart from the capability latches, and out of `exportCapabilities`, on purpose. A latch is
+ * a refusal that holds until the process dies; this is a measurement that moves every turn and is
+ * learned again from the first one after a restart. `negotiate` compares every value on a
+ * `ModelCapabilities` to tell whether a flag moved under a request in flight, so a number that
+ * moves on every turn there would read as a latch changing and re-send refusals it should throw.
+ */
+/** How many of a model's latest readings the ratio is taken over. */
+const READINGS = 4;
+/**
+ * The ratios no tokenizer produces over a whole request. Below one is a request whose tokens are
+ * mostly somewhere the characters do not count — an image — and far above four is a server that
+ * reported the uncached part of the prompt as all of it.
+ */
+const PLAUSIBLE = { least: 1, most: 8 };
+/**
+ * The latest readings per model, under the endpoint's own `Capabilities` object — the identity
+ * `capabilitiesFor` already gives one server and key — so an endpoint forgotten by
+ * `resetCapabilities` takes its readings with it. Replaced rather than cleared by `resetCalibration`,
+ * since a `WeakMap` has no `clear`.
+ */
+let readings = new WeakMap();
+/**
+ * The characters per token to size a request to this model with, `CHARS_PER_TOKEN` until a turn
+ * has reported one.
+ *
+ * The highest of the model's last few readings rather than their mean. The estimate guards a
+ * window, and `estimateTokens` says which side of wrong that should be on: a count that comes out
+ * high refuses a run that would have fit, one that comes out low only costs the round trip the
+ * guard was saving. The highest ratio is the lowest count, and the last few rather than all of
+ * them because a run's transcript grows by appending, so the latest requests are the best
+ * likeness of the next.
+ *
+ * @param supports The endpoint, as `capabilitiesFor` hands it over.
+ * @param model The name the endpoint knows the model as, as it goes in the body.
+ */
+export function charsPerTokenFor(supports, model) {
+    const known = readings.get(supports)?.get(model);
+    return known?.length ? Math.max(...known) : CHARS_PER_TOKEN;
+}
+/** Whether any message carries a part whose tokens its characters do not count. */
+const hasMedia = (messages) => messages.some(({ content }) => Array.isArray(content) &&
+    content.some((part) => part.type !== "text" && part.type !== "refusal"));
+/**
+ * Takes one reading from a request that was answered, so the next one to this model is sized by it.
+ *
+ * `runTurn` calls it after every turn whose prompt was reported, so a caller using that has
+ * nothing to do. A request carrying an image or audio is not read: a vision model charges a
+ * picture hundreds of tokens its characters say nothing about. Neither is a reading outside what a
+ * tokenizer could produce, which is a miscount and not a tokenizer.
+ *
+ * @param supports The endpoint the request went to.
+ * @param body The request as it was last sent, which names the model.
+ * @param promptTokens The prompt count the endpoint reported for it. Zero or less is no report.
+ * @returns The ratio now in force for the model.
+ */
+export function calibrate(supports, body, promptTokens) {
+    if (!(promptTokens > 0) || hasMedia(body.messages))
+        return charsPerTokenFor(supports, body.model);
+    const ratio = (requestChars(body) + toolsChars(body.tools ?? [])) / promptTokens;
+    if (ratio < PLAUSIBLE.least || ratio > PLAUSIBLE.most) {
+        return charsPerTokenFor(supports, body.model);
+    }
+    let models = readings.get(supports);
+    if (!models) {
+        models = new Map();
+        readings.set(supports, models);
+    }
+    const known = models.get(body.model) ?? [];
+    known.push(ratio);
+    if (known.length > READINGS)
+        known.shift();
+    models.set(body.model, known);
+    return charsPerTokenFor(supports, body.model);
+}
+/** Forgets every reading, so the next request is sized at `CHARS_PER_TOKEN` again. */
+export function resetCalibration() {
+    readings = new WeakMap();
+}

package/dist/capabilities.d.ts

@@ -82,6 +82,14 @@ export interface ModelCapabilities {
      * endpoint's because one key reaches models that differ here, the way they differ on effort.
      */
     structuredOutput: boolean;
+    /**
+     * Continues a trailing assistant message rather than answering afresh, which `continueTurn`
+     * relies on. llama.cpp renders one as a prefill and picks up mid-word; hosted OpenAI takes the
+     * same request and writes a new reply after it, and some servers refuse it outright — llama.cpp
+     * itself does for a template with thinking enabled. Latched off by `continueTurn` on either,
+     * never by `negotiate`, since the refusal is about a request only a continuation sends.
+     */
+    assistantPrefill: boolean;
 }
 /**
  * What this endpoint is known not to support. The same object every time, so what `negotiate`

package/dist/capabilities.js

@@ -56,6 +56,7 @@ export function modelCapabilitiesFor(supports, model) {
             chosenTemperature: true,
             refusedFields: new Set(),
             structuredOutput: true,
+            assistantPrefill: true,
         };
         supports.models.set(model, known);
     }

package/dist/compaction.d.ts

@@ -62,8 +62,24 @@ export interface CompactionOptions {
     compactAt?: number;
     /** The fraction of `limit` the kept tail may fill. `KEEP_RATIO` by default. */
     keepRatio?: number;
-    /** One message's tokens. `messageTokens` by default. */
+    /** One message's tokens. `messageTokens` by default, divided by `charsPerToken`. */
     estimate?: (message: Message) => number;
+    /**
+     * The divisor the default `estimate` uses — `charsPerTokenFor` the model, for a transcript
+     * weighed the way `runTurn` sizes its requests. `CHARS_PER_TOKEN` when absent; ignored beside
+     * 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 {
@@ -86,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, 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.
@@ -108,26 +130,118 @@ 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.
  *
  * `beforeCompact` is told what is being folded while the summary is written, beside it rather
  * than ahead of it — a memory server filing it is not a rescue worth making the run wait for, and
- * `notify` never rejects. A hook cannot veto the compaction: `HookOutcome` has no way to say so,
- * and a run over its window has no better option anyway. An empty summary folds nothing, and the
- * transcript comes back as it was. Rewrites the prefix; see the module comment on when to run it.
+ * `notify` never rejects. A host that wants its hooks able to stop a compaction sets
+ * `honourVeto`, and then they run first and the summary waits on them: any `ok` outcome carrying
+ * `veto` leaves the transcript as it was, and each vetoing hook is noted by name. A `forced`
+ * compaction ignores a veto and runs the hooks beside the summary as before, because a run already
+ * past its window has no better option — a veto there only trades the summary for a
+ * `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`.
- * @param options Hooks to tell. `context` is extended with `compacting` and `range`, whose
- * indexes are the plan's.
+ * @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 `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, }?: {
-    hooks?: {
-        run: HookRunner;
-        context: HookContext;
-        onNote?: (note: HookNote) => void;
-    };
-}): Promise<Message[]>;
+export declare function compactTranscript(messages: Message[], plan: CompactionPlan, summarise: (text: string) => Promise<string>, options?: CompactionRunOptions): Promise<Message[]>;
 export {};

package/dist/compaction.js

@@ -1,4 +1,4 @@
-import { notify, turnMessages } from "./hooks.js";
+import { consult, notify, turnMessages, } from "./hooks.js";
 import { messageTokens } from "./retry.js";
 import { ask } from "./side-task.js";
 /** The fraction of the window in use before a summary is worth its own round trip. */
@@ -37,6 +37,25 @@ const messageText = (message) => {
     return `${textOf(message.content)} ${calls}`.trim();
 };
 const isSummary = (message) => message.role === "system" && textOf(message.content).startsWith(SUMMARY_LEAD);
+/** The summary as it sits in a transcript, which is the one shape `isSummary` recognises again. */
+const summaryMessage = (summary) => ({
+    role: "system",
+    content: `${SUMMARY_LEAD}${summary.trim()}`,
+});
+/**
+ * The leading system messages a fold never touches, and the summary an earlier one left among
+ * them. What a caller who keeps its system prompt out of the array knows already, and passes.
+ */
+const systemHead = (messages) => {
+    let from = 0;
+    let previous;
+    while (from < messages.length && messages[from].role === "system") {
+        if (isSummary(messages[from]))
+            previous = textOf(messages[from].content).slice(SUMMARY_LEAD.length);
+        from++;
+    }
+    return { from, previous };
+};
 /**
  * The transcript with every tool result but the latest few replaced by a one-line stub.
  *
@@ -80,22 +99,24 @@ export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}
  * 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 function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, estimate = messageTokens, }) {
+export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, charsPerToken, estimate = (message) => messageTokens(message, { charsPerToken }), from: givenFrom, previous: givenPrevious, }) {
     if (!(limit > 0))
         return undefined;
     const cost = used ?? messages.reduce((total, message) => total + estimate(message), 0);
     if (cost < limit * compactAt)
         return undefined;
-    let from = 0;
-    let previous;
-    while (from < messages.length && messages[from].role === "system") {
-        if (isSummary(messages[from]))
-            previous = textOf(messages[from].content).slice(SUMMARY_LEAD.length);
-        from++;
-    }
+    const head = systemHead(messages);
+    const from = Math.min(Math.max(givenFrom ?? head.from, 0), messages.length);
+    const previous = givenPrevious ?? head.previous;
     const budget = limit * keepRatio;
     let kept = 0;
     let cut = messages.length;
@@ -138,36 +159,120 @@ export function summaryInput(plan) {
  * `SUMMARY_PROMPT` unless given.
  */
 export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens = 1024, ...options } = {}) => (text) => ask(config, model, system, text, { maxTokens, ...options });
+/**
+ * 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 async function runCompaction(messages, plan, summarise, { hooks, forced = false } = {}) {
+    const context = hooks && {
+        ...hooks.context,
+        compacting: turnMessages(hooks.context.session.id, messages, plan.from, plan.cut),
+        range: { from: plan.from, through: plan.cut },
+    };
+    let summary;
+    if (hooks && context && hooks.honourVeto && !forced) {
+        const { vetoed } = await consult(hooks.run, "beforeCompact", context, hooks.onNote);
+        if (vetoed)
+            return undefined;
+        summary = await summarise(summaryInput(plan));
+    }
+    else {
+        [summary] = await Promise.all([
+            summarise(summaryInput(plan)),
+            hooks && context && notify(hooks.run, "beforeCompact", context, hooks.onNote),
+        ]);
+    }
+    if (!summary.trim())
+        return undefined;
+    return { summary: summary.trim(), through: plan.cut, at: new Date().toISOString() };
+}
+/**
+ * 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 function applyCompaction(messages, record, { from } = {}) {
+    if (!record?.summary.trim())
+        return messages;
+    const head = Math.min(Math.max(from ?? systemHead(messages).from, 0), record.through);
+    return [
+        ...messages.slice(0, head).filter((message) => !isSummary(message)),
+        summaryMessage(record.summary),
+        ...messages.slice(record.through),
+    ];
+}
+/**
+ * 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 const requestIndex = (index, record, head = 0) => {
+    if (!record)
+        return index;
+    return index < record.through ? head : index - record.through + head + 1;
+};
 /**
  * The transcript with the plan's stretch replaced by one system message holding its summary.
  *
  * `beforeCompact` is told what is being folded while the summary is written, beside it rather
  * than ahead of it — a memory server filing it is not a rescue worth making the run wait for, and
- * `notify` never rejects. A hook cannot veto the compaction: `HookOutcome` has no way to say so,
- * and a run over its window has no better option anyway. An empty summary folds nothing, and the
- * transcript comes back as it was. Rewrites the prefix; see the module comment on when to run it.
+ * `notify` never rejects. A host that wants its hooks able to stop a compaction sets
+ * `honourVeto`, and then they run first and the summary waits on them: any `ok` outcome carrying
+ * `veto` leaves the transcript as it was, and each vetoing hook is noted by name. A `forced`
+ * compaction ignores a veto and runs the hooks beside the summary as before, because a run already
+ * past its window has no better option — a veto there only trades the summary for a
+ * `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`.
- * @param options Hooks to tell. `context` is extended with `compacting` and `range`, whose
- * indexes are the plan's.
+ * @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 `messages` itself when nothing was folded — a veto or an empty summary — otherwise a
+ * new array.
  */
-export async function compactTranscript(messages, plan, summarise, { hooks, } = {}) {
-    const [summary] = await Promise.all([
-        summarise(summaryInput(plan)),
-        hooks &&
-            notify(hooks.run, "beforeCompact", {
-                ...hooks.context,
-                compacting: turnMessages(hooks.context.session.id, messages, plan.from, plan.cut),
-                range: { from: plan.from, through: plan.cut },
-            }, hooks.onNote),
-    ]);
-    if (!summary.trim())
+export async function compactTranscript(messages, plan, summarise, options = {}) {
+    const record = await runCompaction(messages, plan, summarise, options);
+    if (!record)
         return messages;
-    return [
-        ...messages.slice(0, plan.from).filter((message) => !isSummary(message)),
-        { role: "system", content: `${SUMMARY_LEAD}${summary.trim()}` },
-        ...messages.slice(plan.cut),
-    ];
+    return applyCompaction(messages, record, { from: plan.from });
 }

package/dist/continuation.d.ts

@@ -0,0 +1,59 @@
+import OpenAI from "openai";
+import { type Capabilities, type ModelCapabilities } from "./capabilities.ts";
+import { type RunTurnOptions } from "./run-turn.ts";
+import type { Turn } from "./stream.ts";
+/**
+ * Picking up an answer the token ceiling cut off, instead of keeping half of it.
+ *
+ * A turn that stops at `maxTokens` mid-answer comes back looking finished, and the half answer
+ * becomes the answer. A server that renders a trailing assistant message as a prefill lets the
+ * model carry on from the last token as if nothing had happened, which costs the rest of the
+ * reply and a prefill the cache mostly already holds.
+ */
+/** What `continueTurn` takes besides what `runTurn` does. */
+export interface ContinueTurnOptions extends RunTurnOptions {
+    /**
+     * How many more requests one answer may be given, 1 unless given; zero continues nothing.
+     * The cap is what stops a model that never reaches a stop token from looping on the ceiling.
+     */
+    maxContinuations?: number;
+}
+/**
+ * Whether a turn is one a continuation can finish: cut off at the ceiling, with an answer begun
+ * and no tool call in it.
+ *
+ * An answer not begun is a turn cut off in its scratchpad, and prefilling a half-closed fence is
+ * the template's business rather than something this can do the same way everywhere — llama.cpp
+ * refuses a prefill outright on a template with thinking enabled. A tool call is excluded because
+ * its arguments are what was cut, and `parseToolArguments` already reports that truncation.
+ *
+ * @param turn The turn as it came back.
+ */
+export declare const isContinuable: (turn: Turn) => boolean;
+/**
+ * Carries on an answer the token ceiling cut off, by sending the transcript again with the answer
+ * so far as a trailing assistant message, and joins the pieces into one turn.
+ *
+ * Only a turn `isContinuable` accepts is continued; any other comes back as it was. Content and
+ * reasoning are joined in order, the tool calls a continuation makes are kept, and usage is summed
+ * across the requests with `continuations` counting them. The continuation is read as starting in
+ * the answer, whatever `startInReasoning` says: a template that opens a fence for a fresh reply
+ * does not open one for a prefill. Its tokens reach `onOutput` as they arrive, so a watcher sees
+ * one answer carry on rather than two.
+ *
+ * Whether the server continues at all is latched per model as `assistantPrefill`. A refusal of the
+ * request latches it off, and so does a continuation that begins the answer again, which is how a
+ * server that takes the request and ignores the prefill — hosted OpenAI among them — shows itself;
+ * that check is only as good as a restart being word for word. Either way the answer so far is
+ * kept, with a notice. So is it when the continuation fails any other way, since the tokens
+ * already in hand are worth more than the error; only a stop is thrown.
+ *
+ * @param client The pooled client for this endpoint.
+ * @param supports What the endpoint has already refused.
+ * @param request Builds the body the cut-off turn was sent, exactly as `runTurn` was given it. The
+ * prefill is appended to what it builds.
+ * @param turn The turn that came back cut off.
+ * @param options `runTurn`'s options, with `model` needed for the latch — without one nothing is
+ * latched and each continuation finds out again — and the cap on continuations.
+ */
+export declare function continueTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming, turn: Turn, { maxContinuations, ...options }?: ContinueTurnOptions): Promise<Turn>;