@cubicecho/agent-core 2.4.0 → 2.5.0

package/dist/compaction.d.ts

@@ -0,0 +1,133 @@
+import type OpenAI from "openai";
+import type { Endpoint } from "./config.ts";
+import { type HookContext, type HookNote, type HookRunner } from "./hooks.ts";
+import { type SideTaskOptions } from "./side-task.ts";
+/**
+ * Keeping a long run inside its window: stale tool results cleared, and the oldest stretch folded
+ * into a summary the model writes itself.
+ *
+ * Both rewrite the transcript's prefix, and a prefix that changes is a prompt cache that misses —
+ * on a local server that is the whole prompt processed again, every token of it. So neither is
+ * meant to run a little on every turn: run them rarely, and together, at the point
+ * `planCompaction` says the window is filling, and the cache is paid for once rather than on
+ * every step.
+ */
+type Message = OpenAI.ChatCompletionMessageParam;
+/** The fraction of the window in use before a summary is worth its own round trip. */
+export declare const COMPACT_AT = 0.75;
+/** The fraction of the window the kept tail may fill, leaving room for the run to grow again. */
+export declare const KEEP_RATIO = 0.35;
+/**
+ * The summariser's instruction when the caller gives none.
+ *
+ * Asks for notes rather than a retelling, because what the summary replaces is the model's only
+ * record of what was decided, and a narrative spends its words on the order things happened in.
+ */
+export declare const SUMMARY_PROMPT: string;
+/**
+ * How a summary message opens, which is also how `planCompaction` knows one from a system prompt.
+ */
+export declare const SUMMARY_LEAD = "Summary of the earlier part of this conversation, which is no longer shown in full:\n\n";
+/** What `pruneToolResults` takes. */
+export interface PruneOptions {
+    /** How many of the latest tool results are left whole, 5 by default. */
+    keepLast?: number;
+    /** A result this long or shorter is left whole wherever it is, 256 characters by default. */
+    maxChars?: number;
+}
+/**
+ * The transcript with every tool result but the latest few replaced by a one-line stub.
+ *
+ * The cheap half of compaction. A `read_file` of a 40k-character file is 10k tokens on every turn
+ * after it, and by then the model has usually taken what it wanted from it; the stub keeps the
+ * call answered — a call with no result is a malformed transcript — and says how much was there,
+ * so a model that does need it again knows to ask. Short results are kept, since a stub saves
+ * nothing on them. Returns the same array when there was nothing to clear. Rewrites the prefix;
+ * see the module comment on when to run it.
+ *
+ * @param messages The transcript. Not written to.
+ * @param options How many results to keep and how long one must be to clear.
+ */
+export declare function pruneToolResults(messages: Message[], { keepLast, maxChars }?: PruneOptions): Message[];
+/** What `planCompaction` takes. */
+export interface CompactionOptions {
+    /** The model's window, in tokens. Zero or less never compacts. */
+    limit: number;
+    /**
+     * What the transcript costs now. The last turn's reported prompt tokens are the best number;
+     * absent is the estimate of the whole transcript.
+     */
+    used?: number;
+    /** The fraction of `limit` in use before compacting. `COMPACT_AT` by default. */
+    compactAt?: number;
+    /** The fraction of `limit` the kept tail may fill. `KEEP_RATIO` by default. */
+    keepRatio?: number;
+    /** One message's tokens. `messageTokens` by default. */
+    estimate?: (message: Message) => number;
+}
+/** Where to cut, as `compactTranscript` takes it. */
+export interface CompactionPlan {
+    /** The first message folded away. Everything before it is a system prompt and stays. */
+    from: number;
+    /** The first message kept whole, always a user message. */
+    cut: number;
+    /** The messages from `from` to `cut`, the ones the summary replaces. */
+    toSummarise: Message[];
+    /** The summary an earlier compaction left, which this one continues. */
+    previous?: string;
+}
+/**
+ * Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
+ *
+ * The kept tail is walked back from the end until it fills `keepRatio` of the window, then moved
+ * forward onto a user message: a transcript resuming mid-exchange — a tool result with no call
+ * before it, a reply with no question — is malformed and servers refuse it. The system prompts at
+ * the head are never folded, and a summary an earlier compaction left there is continued rather
+ * 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.
+ *
+ * @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`.
+ */
+export declare function planCompaction(messages: Message[], { limit, used, compactAt, keepRatio, estimate, }: 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.
+ *
+ * @param plan What `planCompaction` returned.
+ */
+export declare function summaryInput(plan: CompactionPlan): string;
+/**
+ * A summariser that asks `model` with `SUMMARY_PROMPT`, for `compactTranscript`.
+ *
+ * @param config The endpoint the summary is written through.
+ * @param model The model to write it, which may be a smaller one than the run's.
+ * @param options Cancellation and notices; the ceiling is 1024 and the instruction
+ * `SUMMARY_PROMPT` unless given.
+ */
+export declare const summariser: (config: Endpoint, model: string, { system, maxTokens, ...options }?: SideTaskOptions & {
+    system?: string;
+}) => (text: string) => Promise<string>;
+/**
+ * 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.
+ *
+ * @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.
+ */
+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 {};

package/dist/compaction.js

@@ -0,0 +1,173 @@
+import { 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. */
+export const COMPACT_AT = 0.75;
+/** The fraction of the window the kept tail may fill, leaving room for the run to grow again. */
+export const KEEP_RATIO = 0.35;
+/** How much of any one message the summariser is shown. A pasted file is not worth it whole. */
+const SUMMARY_SLICE = 4000;
+/**
+ * The summariser's instruction when the caller gives none.
+ *
+ * Asks for notes rather than a retelling, because what the summary replaces is the model's only
+ * record of what was decided, and a narrative spends its words on the order things happened in.
+ */
+export const SUMMARY_PROMPT = "You maintain the running memory of a long conversation. Rewrite the exchange below as " +
+    "notes the assistant can rely on after the original messages are gone. Keep decisions, " +
+    "facts, file paths, names, numbers, and anything still unresolved. Drop pleasantries and " +
+    "anything already superseded. Write compact prose or bullets — no preamble, no sign-off.";
+/**
+ * How a summary message opens, which is also how `planCompaction` knows one from a system prompt.
+ */
+export const SUMMARY_LEAD = "Summary of the earlier part of this conversation, which is no longer shown in full:\n\n";
+/** A message's content as plain text: parts joined, anything but text left out. */
+const textOf = (content) => typeof content === "string"
+    ? content
+    : Array.isArray(content)
+        ? content.map((part) => ("text" in part ? part.text : "")).join(" ")
+        : "";
+/** What the summariser reads for one message: its text and the calls it made. */
+const messageText = (message) => {
+    const calls = "tool_calls" in message && message.tool_calls
+        ? message.tool_calls
+            .map((call) => call.type === "function" ? `${call.function.name}(${call.function.arguments})` : "")
+            .join(" ")
+        : "";
+    return `${textOf(message.content)} ${calls}`.trim();
+};
+const isSummary = (message) => message.role === "system" && textOf(message.content).startsWith(SUMMARY_LEAD);
+/**
+ * The transcript with every tool result but the latest few replaced by a one-line stub.
+ *
+ * The cheap half of compaction. A `read_file` of a 40k-character file is 10k tokens on every turn
+ * after it, and by then the model has usually taken what it wanted from it; the stub keeps the
+ * call answered — a call with no result is a malformed transcript — and says how much was there,
+ * so a model that does need it again knows to ask. Short results are kept, since a stub saves
+ * nothing on them. Returns the same array when there was nothing to clear. Rewrites the prefix;
+ * see the module comment on when to run it.
+ *
+ * @param messages The transcript. Not written to.
+ * @param options How many results to keep and how long one must be to clear.
+ */
+export function pruneToolResults(messages, { keepLast = 5, maxChars = 256 } = {}) {
+    let kept = 0;
+    let out;
+    for (let at = messages.length - 1; at >= 0; at--) {
+        const message = messages[at];
+        if (message.role !== "tool")
+            continue;
+        if (kept++ < keepLast)
+            continue;
+        const text = textOf(message.content);
+        if (text.length <= maxChars || text.startsWith("[result cleared"))
+            continue;
+        out ??= [...messages];
+        out[at] = {
+            ...message,
+            content: `[result cleared, ${text.length.toLocaleString("en-US")} chars]`,
+        };
+    }
+    return out ?? messages;
+}
+/**
+ * Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
+ *
+ * The kept tail is walked back from the end until it fills `keepRatio` of the window, then moved
+ * forward onto a user message: a transcript resuming mid-exchange — a tool result with no call
+ * before it, a reply with no question — is malformed and servers refuse it. The system prompts at
+ * the head are never folded, and a summary an earlier compaction left there is continued rather
+ * 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.
+ *
+ * @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`.
+ */
+export function planCompaction(messages, { limit, used, compactAt = COMPACT_AT, keepRatio = KEEP_RATIO, estimate = messageTokens, }) {
+    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 budget = limit * keepRatio;
+    let kept = 0;
+    let cut = messages.length;
+    for (let at = messages.length - 1; at > from; at--) {
+        kept += estimate(messages[at]);
+        if (kept > budget)
+            break;
+        cut = at;
+    }
+    while (cut < messages.length && messages[cut].role !== "user")
+        cut++;
+    if (cut >= messages.length || cut - from < 2)
+        return undefined;
+    return { from, cut, toSummarise: messages.slice(from, cut), ...(previous ? { previous } : {}) };
+}
+/**
+ * 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.
+ *
+ * @param plan What `planCompaction` returned.
+ */
+export function summaryInput(plan) {
+    const transcript = plan.toSummarise
+        .map((message) => {
+        const text = messageText(message);
+        return text ? `${message.role}: ${text.slice(0, SUMMARY_SLICE)}` : "";
+    })
+        .filter(Boolean)
+        .join("\n\n");
+    return plan.previous
+        ? `Notes so far:\n${plan.previous}\n\nContinue them with this exchange:\n\n${transcript}`
+        : transcript;
+}
+/**
+ * A summariser that asks `model` with `SUMMARY_PROMPT`, for `compactTranscript`.
+ *
+ * @param config The endpoint the summary is written through.
+ * @param model The model to write it, which may be a smaller one than the run's.
+ * @param options Cancellation and notices; the ceiling is 1024 and the instruction
+ * `SUMMARY_PROMPT` unless given.
+ */
+export const summariser = (config, model, { system = SUMMARY_PROMPT, maxTokens = 1024, ...options } = {}) => (text) => ask(config, model, system, text, { maxTokens, ...options });
+/**
+ * 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.
+ *
+ * @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.
+ */
+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())
+        return messages;
+    return [
+        ...messages.slice(0, plan.from).filter((message) => !isSummary(message)),
+        { role: "system", content: `${SUMMARY_LEAD}${summary.trim()}` },
+        ...messages.slice(plan.cut),
+    ];
+}

package/dist/config.d.ts

@@ -30,8 +30,28 @@ export interface Endpoint {
 /** What to ask the model for. */
 export interface ModelParams {
     model: string;
+    /** The reply's ceiling. Zero or less sends none, leaving it to the server. */
     maxTokens: number;
     temperature: number;
+    /**
+     * `reasoning_effort` for a model that deliberates. Absent or `"off"` sends none, which is the
+     * only value a server that has never heard of reasoning accepts — a setting that means "leave
+     * the field out" rather than a level to ask for.
+     */
+    reasoningEffort?: string;
+    /**
+     * Request fields this interface cannot spell, merged into the body last by `buildBody`.
+     *
+     * What a model card asks for and nothing here names: `top_k`, `min_p`, `repeat_penalty` —
+     * what actually stops a small model looping — and a server's own fields, such as llama.cpp's
+     * `id_slot`, which pins a session to one slot of a `--parallel` server so its KV cache is
+     * still warm on the next turn. A local server ignores a field it does not know; OpenAI refuses
+     * one by name, and `negotiate` drops that name for the model and sends the request again.
+     * `model`, `messages`, `stream` and `tools` are the loop's and are not overridden from here.
+     * Ollama's `options` object is not read on its `/v1` route, so sampling there has to go in as
+     * top-level fields like any other.
+     */
+    extraBody?: Record<string, unknown>;
 }
 /** How tools reach the model, and how long it may keep calling them. */
 export interface ToolPolicy {

package/dist/events.d.ts

@@ -94,6 +94,11 @@ export interface RunUsage {
     promptTokens: number;
     completionTokens: number;
     totalTokens: number;
+    /**
+     * How much of `promptTokens` the endpoint served from its prompt cache. Optional so a caller
+     * emitting usage before this field existed still compiles; absent reads the same as zero.
+     */
+    cachedTokens?: number;
 }
 /**
  * One thing that happened in a run, as a watcher receives it.

package/dist/index.d.ts

@@ -9,18 +9,22 @@
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
+export { type AgentLoopHooks, type AgentLoopOptions, type AgentLoopResult, buildBody, preselect, preview, resolveApiKey, runAgentLoop, type ToolCallOutcome, type ToolCallRequest, } from "./agent-loop.ts";
 export { type Capabilities, capabilitiesFor, type ModelCapabilities, modelCapabilitiesFor, type NegotiateOptions, negotiate, resetCapabilities, } from "./capabilities.ts";
 export type { CatalogServer } from "./catalog.ts";
 export { contextLimitFor, getClient, listModels, type ModelInfo, NO_KEY, resetClients, timeoutMs, } from "./client.ts";
+export { COMPACT_AT, type CompactionOptions, type CompactionPlan, compactTranscript, KEEP_RATIO, type PruneOptions, planCompaction, pruneToolResults, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.ts";
 export type { AgentConfig, Endpoint, ModelParams, RetryPolicy, ToolPolicy, } from "./config.ts";
 export { errorMessage } from "./errors.ts";
 export { configureEvents, type EventBusOptions, emit, endRun, fold, history, type RunEvent, type RunEventInput, type RunEventKind, type RunUsage, resetEvents, watch, } from "./events.ts";
 export { assembleContext, configureHooks, type Gathered, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, type HookContext, type HookEvent, type HookMessage, type HookNote, type HookOptions, type HookOutcome, type HookRunner, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, withContext, } from "./hooks.ts";
 export { resetAll } from "./reset.ts";
-export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
+export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, messageTokens, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.ts";
 export { type RunTurnOptions, runTurn } from "./run-turn.ts";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
-export { ask, clean, listLines, parseJson, resetHints, type SideTaskOptions, tryAsk, } from "./side-task.ts";
+export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTaskOptions, tryAsk, } from "./side-task.ts";
+export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from "./snapshot.ts";
 export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
 export { estimateTokens } from "./tokens.ts";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";
+export { parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, } from "./tool-calls.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";

package/dist/index.js

@@ -9,16 +9,20 @@
  * prompts, and whatever the run is about — because that is the caller's, and it is the part
  * that differs between one server and the next.
  */
+export { buildBody, preselect, preview, resolveApiKey, runAgentLoop, } from "./agent-loop.js";
 export { capabilitiesFor, modelCapabilitiesFor, negotiate, resetCapabilities, } from "./capabilities.js";
 export { contextLimitFor, getClient, listModels, NO_KEY, resetClients, timeoutMs, } from "./client.js";
+export { COMPACT_AT, compactTranscript, KEEP_RATIO, planCompaction, pruneToolResults, SUMMARY_LEAD, SUMMARY_PROMPT, summariser, summaryInput, } from "./compaction.js";
 export { errorMessage } from "./errors.js";
 export { configureEvents, emit, endRun, fold, history, resetEvents, watch, } from "./events.js";
 export { assembleContext, configureHooks, gather, HOOK_CONTEXT_TOKENS, HOOK_EVENTS, HOOK_PREFACE, INJECT_EVENTS, notify, resetHooks, turnIndex, turnMessages, withContext, } from "./hooks.js";
 export { resetAll } from "./reset.js";
-export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
+export { backoffMs, ContextOverflow, compact, EndpointSilent, isOverflow, isTransient, messageTokens, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
 export { runTurn } from "./run-turn.js";
 export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
-export { ask, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
+export { ask, askJson, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
+export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from "./snapshot.js";
 export { streamTurn, } from "./stream.js";
 export { estimateTokens } from "./tokens.js";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";

package/dist/retry.d.ts

@@ -47,6 +47,15 @@ export declare const compact: (tokens: number) => string;
  * @param body The request as it will be sent, tools included.
  */
 export declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStreaming) => number;
+/**
+ * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
+ *
+ * For the arithmetic that weighs part of a transcript against a window — `planCompaction`'s kept
+ * tail — where `estimateTokens` on the text alone would leave out the calls and the envelope.
+ *
+ * @param message The message as it will be sent.
+ */
+export declare const messageTokens: (message: OpenAI.ChatCompletionMessageParam) => number;
 /**
  * Whether a refusal means the request was too big, rather than merely refused.
  *

package/dist/retry.js

@@ -136,6 +136,15 @@ export const requestTokens = (body) => {
         chars += messageChars(message);
     return Math.ceil(chars / CHARS_PER_TOKEN) + (body.tools?.length ? toolsCost(body.tools) : 0);
 };
+/**
+ * One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
+ *
+ * For the arithmetic that weighs part of a transcript against a window — `planCompaction`'s kept
+ * tail — where `estimateTokens` on the text alone would leave out the calls and the envelope.
+ *
+ * @param message The message as it will be sent.
+ */
+export const messageTokens = (message) => Math.ceil(messageChars(message) / CHARS_PER_TOKEN);
 /**
  * Servers refuse an over-long request in their own words; these are the ones worth reading as
  * that rather than as a broken request. Matched loosely — every one of them is some

package/dist/run-turn.d.ts

@@ -39,8 +39,9 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
     /**
      * What the model will read, in tokens. Zero — the default — sends whatever it is given.
      *
-     * With a limit, the request is sized before it is sent and a `ContextOverflow` is raised here
-     * rather than by the endpoint one round trip later. It is opt-in because the number is the
+     * With a limit, the request is sized before it is sent — the prompt plus the reply ceiling
+     * the body carries, since that is what the endpoint weighs — and a `ContextOverflow` is raised
+     * here rather than by the endpoint one round trip later. It is opt-in because the number is the
      * caller's to find: `contextLimitFor` asks the endpoint, an operator's own setting overrides
      * it, and neither is something a turn should be doing network I/O to discover. A limit below
      * `SMALLEST_LIKELY_WINDOW` is not believed — a model with a window that small is rare enough
@@ -57,6 +58,11 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
      * `request` has to know what this model refused before it can build one that avoids it.
      */
     model?: string;
+    /**
+     * The body fields a refusal may take away when the endpoint has never heard of them — the keys
+     * of `extraBody`, ordinarily. See `NegotiateOptions.droppable`; it needs `model` too.
+     */
+    droppable?: Iterable<string>;
 }
 /**
  * `request` is a callback rather than a body because the body has to be rebuilt from whatever
@@ -71,4 +77,4 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
  * @param options Retry budget, context limit, the model to negotiate for, notices, and the
  * stream's own callbacks.
  */
-export declare function runTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming, { maxRetries, onNotice, contextLimit, model, ...stream }?: RunTurnOptions): Promise<Turn>;
+export declare function runTurn(client: OpenAI, supports: Capabilities, request: (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming, { maxRetries, onNotice, contextLimit, model, droppable, ...stream }?: RunTurnOptions): Promise<Turn>;

package/dist/run-turn.js

@@ -15,7 +15,7 @@ import { streamTurn } from "./stream.js";
  * @param options Retry budget, context limit, the model to negotiate for, notices, and the
  * stream's own callbacks.
  */
-export async function runTurn(client, supports, request, { maxRetries = 0, onNotice, contextLimit = 0, model, ...stream } = {}) {
+export async function runTurn(client, supports, request, { maxRetries = 0, onNotice, contextLimit = 0, model, droppable, ...stream } = {}) {
     // Sized once rather than per build. `request` is called again for every downgrade and every
     // retry, but a downgraded body is strictly smaller than the one before it and the transcript
     // does not change between attempts — so the first body is the one worth measuring, and
@@ -26,11 +26,18 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
         if (!sized && contextLimit >= SMALLEST_LIKELY_WINDOW) {
             sized = true;
             const needed = requestTokens(body);
+            // The endpoint refuses on the prompt plus the reply — llama.cpp sizes the slot with
+            // `n_predict` in, OpenAI with the ceiling — so a prompt that fits the window but not the
+            // window less the ceiling was let through here to be refused one round trip later, which
+            // is the trip this guard exists to save. Read off the body under whichever spelling was
+            // chosen. No ceiling reserves nothing: the server then gives the reply what is left.
+            const reserve = Math.max(0, body.max_completion_tokens ?? body.max_tokens ?? 0);
             // Not retried, and deliberately not a capability: `isTransient` refuses it and none of the
             // words below are ones `negotiate` reads as a refusal it can answer, so this leaves both
             // loops on the first attempt instead of being sent again to be refused again.
-            if (needed > contextLimit) {
-                throw new ContextOverflow(`the request is about ${compact(needed)} tokens, over this model's ${compact(contextLimit)}`);
+            if (needed + reserve > contextLimit) {
+                const reserved = reserve ? ` plus ${compact(reserve)} reserved for the reply` : "";
+                throw new ContextOverflow(`the request is about ${compact(needed)} tokens${reserved}, over this model's ${compact(contextLimit)}`);
             }
         }
         return body;
@@ -38,7 +45,7 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
     for (let attempt = 0;; attempt++) {
         const produced = { any: false };
         try {
-            return await negotiate(supports, (capabilities, box, forModel) => streamTurn(client, measured(capabilities, forModel), { ...stream, produced: box }), { produced, onNotice, model });
+            return await negotiate(supports, (capabilities, box, forModel) => streamTurn(client, measured(capabilities, forModel), { ...stream, produced: box }), { produced, onNotice, model, droppable });
         }
         catch (error) {
             // The abort is read before the classification, not after. A run stopped by its operator

package/dist/side-task.d.ts

@@ -1,4 +1,8 @@
 import type { Endpoint } from "./config.ts";
+/** An (endpoint, model) pair as `noHints` holds it: `[endpointId, model]`, stringified. */
+export declare const hintKey: (endpoint: string, model: string) => string;
+/** The pairs that refused the hints, the live set, for `exportCapabilities` and `importCapabilities`. */
+export declare const refusedHints: () => Set<string>;
 /** Test seam, alongside `resetClients` and `resetAll`: forget which models refused the hints. */
 export declare const resetHints: () => void;
 /** What a side task may be given. All optional — one given none of them still runs. */
@@ -32,7 +36,37 @@ export interface SideTaskOptions {
  * @param user The input it applies to.
  * @param options Reply ceiling, temperature, cancellation, notices.
  */
-export declare function ask(config: Endpoint, model: string, system: string, user: string, { maxTokens, temperature, signal, onNotice }?: SideTaskOptions): Promise<string>;
+export declare function ask(config: Endpoint, model: string, system: string, user: string, options?: SideTaskOptions): Promise<string>;
+/** What `askJson` takes besides a side task's options. */
+export interface AskJsonOptions extends SideTaskOptions {
+    /** What the schema is called in the request, `answer` by default. Letters, digits, `_` and `-`. */
+    name?: string;
+    /**
+     * Asks the server to hold the reply to the schema exactly, true by default. OpenAI's strict mode
+     * wants every property required and `additionalProperties: false`; a schema written otherwise
+     * wants this off there.
+     */
+    strict?: boolean;
+}
+/**
+ * A side task whose answer is JSON matching a schema, parsed. Undefined when no JSON came back.
+ * Throws like any request.
+ *
+ * Sends `response_format` with the schema, which a llama.cpp server compiles into a grammar and
+ * vLLM, LM Studio, Ollama and OpenAI each hold the reply to, so a small model that wraps JSON in
+ * prose cannot. The schema is normalised as a tool's parameters are, and relaxed where the endpoint
+ * could not build a grammar, since the same converter reads both. A model that refuses the field
+ * latches it off and is asked in words: the schema rides on the system prompt either way, and
+ * the reply goes through `parseJson`, which finds the JSON in whatever came back.
+ *
+ * @param config Where to send it and how long to wait.
+ * @param model The model to ask.
+ * @param system The instruction. The schema is appended to it.
+ * @param user The input it applies to.
+ * @param schema The JSON Schema of the answer. Its root is held to an object, as a tool's is.
+ * @param options A side task's options, plus the schema's `name` and whether it is `strict`.
+ */
+export declare function askJson<T>(config: Endpoint, model: string, system: string, user: string, schema: Record<string, unknown>, { name, strict, ...options }?: AskJsonOptions): Promise<T | undefined>;
 /**
  * A side task is never worth failing the work it supports. Callers that can carry on without
  * an answer use this and get `undefined` instead of an exception.