@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/run-calls.js

@@ -0,0 +1,351 @@
+import { errorMessage } from './errors.js';
+import { RunEventKind } from './events.js';
+import { parseToolArguments, } from './tool-calls.js';
+import { CALL_TOOL, expandNames, inCatalog, LOAD_TOOLS, loadResult, proxiedCall, proxyLoadResult, requestedNames, shownCall, toolName, } from './tool-loading.js';
+import { FUNCTION_TOOL, Role } from './wire.js';
+/**
+ * The tools between two turns: a step's calls read, run and written into the transcript.
+ *
+ * Apart from the loop because it is a different job with its own rules — a call is announced
+ * before it runs and answered whatever happens, `load_tools` and `call_tool` are answered here
+ * rather than dispatched, and a failure part-way has to leave a transcript an endpoint will take
+ * back — and none of them is about when to send the next request.
+ */
+/**
+ * A long tool argument or result cut to what a watcher needs, with the full length said.
+ *
+ * @param text - What to show.
+ * @param [limit] - Characters kept. Text at or under it comes back as it was.
+ * @returns The text to show. Cut, it ends in an ellipsis and the whole length, `… (N chars)`.
+ *
+ * @remarks
+ * For events, never for the transcript: the model reads the whole of what a tool returned.
+ */
+export const preview = (text, limit = 2000) => text.length > limit ? `${text.slice(0, limit)}… (${text.length} chars)` : text;
+/** What a tool call the run was stopped during is answered with, in place of a result. */
+const STOPPED_CALL = 'Stopped before this call finished.';
+/** The same for a call of that step the loop never got to. */
+const UNRUN_CALL = 'Not run: the run stopped first.';
+/**
+ * One call with its arguments read, or with why they could not be.
+ *
+ * @param call - The call as the turn carried it.
+ * @param finishReason - Why the turn ended, which tells a call cut off from one written wrongly.
+ * @returns The call beside its arguments and their repaired JSON, or beside the error and `{}`.
+ */
+function readCall(call, finishReason) {
+    try {
+        const args = parseToolArguments(call.function.arguments, { finishReason });
+        return { call, args, normal: JSON.stringify(args) };
+    }
+    catch (error) {
+        return { call, error, normal: '{}' };
+    }
+}
+/**
+ * A turn's calls with their arguments read.
+ *
+ * @param calls - The turn's calls, in the order the model made them.
+ * @param finishReason - Why the turn ended, which tells a call cut off from one written wrongly.
+ * @returns One entry per call, in the same order. Unreadable arguments do not throw: the entry
+ * carries the error in place of them.
+ *
+ * @remarks
+ * A server that parses replayed arguments refuses the almost-JSON a model wrote, so each is
+ * normalised here, and one that could not be read at all is replayed as no arguments.
+ */
+export const readCalls = (calls, finishReason) => calls.map((call) => readCall(call, finishReason));
+/**
+ * The assistant message a turn is written into the transcript as, its calls' arguments repaired.
+ *
+ * @param content - The turn's text. Empty is written as `null`.
+ * @param parsed - The turn's calls as `readCalls` read them. Not written to. None leaves
+ * `tool_calls` off the message rather than empty.
+ * @returns A new message, each call on it a copy with `normal` for its arguments.
+ */
+export const assistantMessage = (content, parsed) => ({
+    role: Role.Assistant,
+    content: content || null,
+    ...(parsed.length
+        ? {
+            tool_calls: parsed.map(({ call, normal }) => ({
+                ...call,
+                function: { ...call.function, arguments: normal },
+            })),
+        }
+        : {}),
+});
+/**
+ * The definitions the host gave for these names, in the order the names are given.
+ *
+ * @param definitions - The host's definitions by name.
+ * @param names - The names wanted. One the host gave no definition for is left out, and one given
+ * twice is answered twice.
+ * @returns A new array of the definitions themselves, not copies.
+ */
+export const definedAs = (definitions, names) => [...names].flatMap((name) => definitions.get(name) ?? []);
+/**
+ * What a call is shown, counted and dispatched as: a `call_tool` as the tool it names.
+ *
+ * @param run - The run, read for whether a `call_tool` is looked through.
+ * @param entry - The call, with its arguments read.
+ * @returns The name, and the arguments as JSON text under `input`: the inner tool's for a
+ * `call_tool` that names one, and otherwise the call's own, as the model wrote them.
+ *
+ * @remarks
+ * Read from the repaired arguments where there are any, since the model's own may be almost-JSON.
+ */
+const shownAs = (run, { call, args, normal }) => run.proxies && call.function.name === CALL_TOOL
+    ? shownCall(CALL_TOOL, args ? normal : call.function.arguments)
+    : { name: call.function.name, input: call.function.arguments };
+/**
+ * Answers a `load_tools`, counting what it loaded.
+ *
+ * @param run - The run. Written to: the names this call loads are added to `loaded`, and `loads`
+ * counts the new ones, the ones already loaded and the ones not in the catalogue.
+ * @param args - The call's arguments, read as `requestedNames` reads them.
+ * @returns The text the model reads, and `ok`: false where nothing it named was loadable, true
+ * where it named even one tool that was loaded already.
+ */
+function answerLoad(run, args) {
+    const { catalog, proxied, definitions, loaded, loads } = run;
+    const resolved = expandNames(requestedNames(args), catalog);
+    const content = proxied
+        ? proxyLoadResult(resolved, catalog, definedAs(definitions, resolved.matched), loaded)
+        : loadResult(resolved, catalog, loaded);
+    // Proxied, a load is only of what the result could define: a catalogued name the host
+    // gave no definition for was not loaded, and is not counted or remembered as though it was.
+    const hits = proxied ? resolved.matched.filter((hit) => definitions.has(hit)) : resolved.matched;
+    for (const hit of hits) {
+        loads[loaded.has(hit) ? 'redundantLoads' : 'toolsLoaded']++;
+    }
+    loads.unknownToolNames += resolved.unknown.length;
+    for (const hit of hits) {
+        loaded.add(hit);
+    }
+    return { content, ok: hits.length > 0 };
+}
+/**
+ * Makes a call at most once per key, sharing the in-flight promise so two identical calls in one
+ * step make one request between them whether they run together or one after the other.
+ *
+ * @param answered - The step's calls so far, by key. Written to.
+ * @param key - What makes two calls the same one.
+ * @param make - Makes the call. Not called where the key has an answer, or one on its way.
+ * @returns The answer, which for a repeat is the first call's. Rejects with what the call did, for
+ * every caller waiting on it.
+ *
+ * @remarks
+ * A call that rejected is forgotten, so asking again is a real retry rather than a replayed
+ * failure.
+ */
+async function once(answered, key, make) {
+    const previous = answered.get(key);
+    if (previous) {
+        return previous;
+    }
+    const pending = make();
+    answered.set(key, pending);
+    try {
+        return await pending;
+    }
+    catch (error) {
+        if (answered.get(key) === pending) {
+            answered.delete(key);
+        }
+        throw error;
+    }
+}
+/**
+ * Runs one call to its result, telling the host of both. A tool that throws is that call's answer
+ * rather than the run's end, unless the run was stopped.
+ *
+ * @param run - The run the call belongs to.
+ * @param entry - The call, with its arguments read.
+ * @param answered - The step's calls already made, by tool and arguments, for `dedupeToolCalls`.
+ * @returns The call's id, the name it was shown under, whether it worked, and the whole of what
+ * the model reads. Rejects where the run was stopped or a host callback threw.
+ */
+async function runCall(run, entry, answered) {
+    const { catalog, onDemand, proxied, signal } = run;
+    const { call, args, error: unreadable, normal } = entry;
+    const proxy = run.proxies && call.function.name === CALL_TOOL;
+    const { name, input: raw } = shownAs(run, entry);
+    // Looked through before the call is announced, so a host is told of the tool it names with
+    // that tool's arguments. A name outside the catalogue is refused here, so `call_tool` reaches
+    // nothing a load could not, and the refusal is the call's answer below.
+    let inner = args ?? {};
+    let refused;
+    if (proxy && args) {
+        try {
+            inner = proxiedCall(args, catalog).input;
+        }
+        catch (error) {
+            inner = {};
+            refused = { error };
+        }
+    }
+    // Built for every call rather than only the dispatched ones, so a host hears of the calls
+    // the loop answers itself in the same shape. Arguments that could not be read are none.
+    const request = { id: call.id, name, args: inner, raw };
+    run.onEvent({ kind: RunEventKind.ToolCall, id: call.id, name, text: preview(raw) });
+    run.onToolCall?.(request);
+    let content;
+    let ok = true;
+    try {
+        if (!args) {
+            throw unreadable;
+        }
+        // By the name the model called, not the one a `call_tool` wraps: `load_tools` is not in
+        // the catalogue, and one reached through `call_tool` is refused below like any other.
+        if (onDemand && call.function.name === LOAD_TOOLS) {
+            ({ content, ok } = answerLoad(run, args));
+        }
+        else {
+            if (refused) {
+                throw refused.error;
+            }
+            // A model that skips `load_tools` and calls a catalogued tool by name is right about
+            // what it wants; load it and run it rather than refusing. Not proxied, where loaded
+            // means its definition is in the history, and this call put none there.
+            if (onDemand && !proxied && inCatalog(catalog, name)) {
+                run.loaded.add(name);
+            }
+            run.used.add(name);
+            // Keyed on the inner call, so one made through `call_tool` and one made natively share.
+            const key = `${name}\0${proxy ? JSON.stringify(inner) : normal}`;
+            content = run.dedupable(request)
+                ? await once(answered, key, () => run.dispatch(request, signal))
+                : await run.dispatch(request, signal);
+        }
+    }
+    catch (error) {
+        if (signal?.aborted) {
+            throw error;
+        }
+        content = errorMessage(error);
+        ok = false;
+    }
+    run.onEvent({ kind: RunEventKind.ToolResult, id: call.id, name, ok, text: preview(content) });
+    const result = { id: call.id, name, ok, content };
+    run.onToolResult?.(result);
+    return result;
+}
+/**
+ * Runs a step's calls and writes each result into the transcript, in the order asked.
+ *
+ * @param run - The run the step belongs to.
+ * @param parsed - The step's calls, with their arguments read.
+ * @param messages - The transcript the results are written into.
+ * @param step - Which step this is, for the host told of each result.
+ *
+ * @remarks
+ * A failure part-way leaves the transcript well-formed before it is rethrown: a call with no
+ * result is a transcript no endpoint takes back, so every call of the step is answered — with what
+ * it returned where it had, and otherwise with a line saying it was stopped, or never run.
+ */
+export async function runCalls(run, parsed, messages, step) {
+    const { signal, toolCalls } = run;
+    // Per step, not per run: the answer to a call made two steps ago was true before the tools in
+    // between ran, and the file the model read may be the file it has since written.
+    const answered = new Map();
+    // By position, so a call that came back while another was being stopped is still found.
+    const outcomes = parsed.map(() => undefined);
+    // How many of the step's calls were handed off, and how many have their result in the
+    // transcript. Both count from the front, since results are written in the order asked.
+    let begun = 0;
+    let kept = 0;
+    const keep = async (id, content) => {
+        const result = {
+            role: Role.Tool,
+            tool_call_id: id,
+            content,
+        };
+        messages.push(result);
+        kept++;
+        await run.announce(result, step);
+    };
+    try {
+        if (run.parallel) {
+            signal?.throwIfAborted();
+            begun = parsed.length;
+            await Promise.all(parsed.map(async (call, at) => {
+                outcomes[at] = await runCall(run, call, answered);
+            }));
+            for (const { id, name, ok, content } of outcomes.flatMap((outcome) => outcome ?? [])) {
+                toolCalls.push({ id, name, ok });
+                await keep(id, content);
+            }
+        }
+        else {
+            for (const [at, call] of parsed.entries()) {
+                signal?.throwIfAborted();
+                begun = at + 1;
+                const { id, name, ok, content } = await runCall(run, call, answered);
+                toolCalls.push({ id, name, ok });
+                await keep(id, content);
+            }
+        }
+    }
+    catch (error) {
+        // Only a call that was made counts in `toolCalls`.
+        for (const [at, entry] of parsed.entries()) {
+            const { call } = entry;
+            if (at < kept) {
+                continue;
+            }
+            const outcome = outcomes[at];
+            // Under the name it was announced by, which for a `call_tool` is the tool it names.
+            if (at < begun) {
+                toolCalls.push({ id: call.id, name: shownAs(run, entry).name, ok: outcome?.ok ?? false });
+            }
+            // The run is already ending on `error`; a host that cannot take this result does not
+            // get to replace it.
+            await keep(call.id, outcome?.content ?? (at < begun ? STOPPED_CALL : UNRUN_CALL)).catch(() => { });
+        }
+        throw error;
+    }
+}
+/**
+ * Writes a proxied preselection into the transcript as a `load_tools` exchange: the tool array is
+ * fixed, so a shortlist has nowhere else to go, and it is answered as though the model had loaded
+ * it. Told to the host as a call the model made would be, so one pairing calls with results by id
+ * shows this one like the rest.
+ *
+ * @param run - The run it opens.
+ * @param shortlist - The definitions preselected, each of them in the catalogue.
+ * @param messages - The transcript, which the exchange is appended to.
+ */
+export async function loadShortlist(run, shortlist, messages) {
+    const { catalog } = run;
+    const names = shortlist.map((tool) => toolName(tool) ?? '');
+    // Numbered by where the call lands, so two questions in one transcript do not share an id.
+    const id = `preselect-${messages.length}`;
+    const args = JSON.stringify({ names });
+    // Held to its own length rather than `MAX_PER_LOAD`: that cap is for a model choosing, and a
+    // host that shortlisted more has already chosen.
+    const content = proxyLoadResult(expandNames(names, catalog, names.length), catalog, shortlist);
+    run.onEvent({ kind: RunEventKind.ToolCall, id, name: LOAD_TOOLS, text: preview(args) });
+    run.onToolCall?.({ id, name: LOAD_TOOLS, args: { names }, raw: args });
+    run.onEvent({ kind: RunEventKind.ToolResult, id, name: LOAD_TOOLS, ok: true, text: preview(content) });
+    run.onToolResult?.({ id, name: LOAD_TOOLS, ok: true, content });
+    run.toolCalls.push({ id, name: LOAD_TOOLS, ok: true });
+    run.loads.toolsLoaded += names.length;
+    for (const name of names) {
+        run.loaded.add(name);
+    }
+    const exchange = [
+        {
+            role: Role.Assistant,
+            content: null,
+            tool_calls: [{ id, type: FUNCTION_TOOL, function: { name: LOAD_TOOLS, arguments: args } }],
+        },
+        { role: Role.Tool, tool_call_id: id, content },
+    ];
+    // Both written before either is announced, so a host that throws on the first leaves a call
+    // with its result. Told as step zero's, with no turn: no request was made for them.
+    messages.push(...exchange);
+    for (const message of exchange) {
+        await run.announce(message, 0);
+    }
+}

package/dist/run-turn.d.ts

@@ -1,6 +1,6 @@
-import type OpenAI from "openai";
-import { type Capabilities, type ModelCapabilities } from "./capabilities.ts";
-import { type StreamTurnOptions, type Turn } from "./stream.ts";
+import type OpenAI from 'openai';
+import { type Capabilities, type ModelCapabilities, type OnNotice } from './capabilities.ts';
+import { type StreamTurnOptions, type Turn } from './stream.ts';
 /**
  * One turn, given as many attempts as the caller allows.
  *
@@ -28,7 +28,7 @@ import { type StreamTurnOptions, type Turn } from "./stream.ts";
  * with. See `calibrate`.
  */
 /** A retry is not the same event as a downgrade, but a watcher wants to be told about both. */
-export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
+export interface RunTurnOptions extends Omit<StreamTurnOptions, 'produced'> {
     /**
      * How many times a lost request is worth sending again. Zero is one attempt, which is the
      * default because a caller with no retry budget in its settings should not inherit one.
@@ -39,10 +39,13 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
      * Told what was given up on and what is being waited out, for a watcher who would otherwise
      * see an unexplained pause. Carries both the capability notices and the retry notices.
      */
-    onNotice?: (message: string) => void;
+    onNotice?: OnNotice;
     /**
-     * What the model will read, in tokens. Zero — the default — sends whatever it is given.
+     * What the model will read, in tokens. Zero sends whatever it is given.
      *
+     * @defaultValue `0`
+     *
+     * @remarks
      * 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
@@ -58,6 +61,7 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
      * are negotiated too — a reasoning effort it does not take, a token ceiling it spells the
      * other way, a temperature that is not ours to pick. Left out, only the endpoint's own are.
      *
+     * @remarks
      * It is given here rather than read off the body because the body is built from the answer:
      * `request` has to know what this model refused before it can build one that avoids it.
      */
@@ -68,33 +72,50 @@ export interface RunTurnOptions extends Omit<StreamTurnOptions, "produced"> {
      */
     droppable?: Iterable<string>;
     /**
-     * How long to wait on a server answering that the model is still loading, `LOADING_TIMEOUT_MS`
-     * unless given; zero gives up on the first such answer like any other 503.
+     * How long to wait on a server answering that the model is still loading; zero gives up on the
+     * first such answer like any other 503.
+     *
+     * @defaultValue `LOADING_TIMEOUT_MS`
      *
+     * @remarks
      * Polled every `LOADING_POLL_MS` without spending `maxRetries`, and announced once rather than
      * per poll. A consumer that starts alongside its llama.cpp, or asks a router for a model it
      * has to swap in, meets this on its first request every time.
      */
     loadingTimeoutMs?: number;
 }
+/**
+ * What a notice calls the model, where the caller did not say which one it is.
+ *
+ * @param model - The model's name. Absent reads as "the model", which is all there is to say.
+ * @returns The name as given, an empty one included, or the stand-in.
+ */
+export declare const modelLabel: (model: string | undefined) => string;
 /**
  * Builds a turn's request body from what the endpoint and the model have refused so far.
  *
+ * @remarks
  * A function rather than a body because a downgrade changes what is sent, so it is called again
  * per attempt. Its second argument is absent where no model was named.
  */
 export type RequestBuilder = (supports: Capabilities, model: ModelCapabilities | undefined) => OpenAI.ChatCompletionCreateParamsStreaming;
 /**
+ * One turn seen through to an answer: negotiated with the endpoint, retried where the failure is
+ * transient, and waited for where the model is still loading.
+ *
+ * @param client - The pooled client for this endpoint.
+ * @param supports - What the endpoint has already refused, threaded through the negotiation.
+ * @param request - Builds the body. Called again per attempt, since a downgrade changes it. Its
+ * second argument is what the model named in `options.model` has refused, absent when none was.
+ * @param [options] - Retry budget, context limit, the model to negotiate for, notices, and the
+ * stream's own callbacks.
+ * @returns The turn the attempt that got through produced, its usage carrying what every attempt
+ * together cost: `wallMs`, `retries` and `timeouts`.
+ *
+ * @remarks
  * `request` is a callback rather than a body because the body has to be rebuilt from whatever
  * the last attempt latched off: the tools it sends depend on `strictSchemas`, and `relaxTools`
  * has to apply to the schemas that were just sanitised. It is handed the same `Capabilities`
  * object throughout, and a caller that reads those from its own closure can ignore the argument.
- *
- * @param client The pooled client for this endpoint.
- * @param supports What the endpoint has already refused, threaded through the negotiation.
- * @param request Builds the body. Called again per attempt, since a downgrade changes it. Its
- * second argument is what the model named in `options.model` has refused, absent when none was.
- * @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: RequestBuilder, { maxRetries, onNotice, contextLimit, model, droppable, loadingTimeoutMs, ...stream }?: RunTurnOptions): Promise<Turn>;

package/dist/run-turn.js

@@ -1,20 +1,71 @@
-import { calibrate, charsPerTokenFor } from "./calibration.js";
-import { negotiate } from "./capabilities.js";
-import { errorMessage } from "./errors.js";
-import { backoffMs, ContextOverflow, compact, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, requestTokens, SMALLEST_LIKELY_WINDOW, sleep, } from "./retry.js";
-import { streamTurn } from "./stream.js";
+import { calibrate, charsPerTokenFor } from './calibration.js';
+import { negotiate } from './capabilities.js';
+import { errorMessage } from './errors.js';
+import { MS_PER_SECOND } from './platform.js';
+import { backoffMs, ContextOverflow, EndpointSilent, isModelLoading, isOverflow, isTransient, LOADING_POLL_MS, LOADING_TIMEOUT_MS, SMALLEST_LIKELY_WINDOW, sleep, } from './retry.js';
+import { streamTurn } from './stream.js';
+import { compact, requestTokens } from './tokens.js';
 /**
+ * What a notice calls the model, where the caller did not say which one it is.
+ *
+ * @param model - The model's name. Absent reads as "the model", which is all there is to say.
+ * @returns The name as given, an empty one included, or the stand-in.
+ */
+export const modelLabel = (model) => model ?? 'the model';
+/**
+ * Throws `ContextOverflow` for a request that will not fit its window, before it is sent.
+ *
+ * @param body - The request about to go out. Its prompt is estimated, and its reply ceiling read
+ * from `max_completion_tokens`, or failing that `max_tokens`.
+ * @param contextLimit - The model's window, in tokens. A request of exactly that many is let
+ * through.
+ * @param charsPerToken - The ratio the prompt is estimated at.
+ *
+ * @remarks
+ * 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. The reserve is read off the body under whichever spelling was chosen, and no
+ * ceiling reserves nothing: the server then gives the reply what is left.
+ */
+function refuseOversized(body, contextLimit, charsPerToken) {
+    const needed = requestTokens(body, { charsPerToken });
+    const reserve = Math.max(0, body.max_completion_tokens ?? body.max_tokens ?? 0);
+    if (needed + reserve <= contextLimit) {
+        return;
+    }
+    // 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.
+    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)}`);
+}
+/**
+ * A backoff in whatever unit reads as a number: the first is under a second, and "retrying in
+ * 0s" is what rounding it to seconds says.
+ *
+ * @param ms - The wait, in milliseconds.
+ * @returns Whole milliseconds, as `250ms`, under a second, and whole seconds, as `4s`, from there.
+ */
+const shownDelay = (ms) => (ms < MS_PER_SECOND ? `${Math.round(ms)}ms` : `${Math.round(ms / MS_PER_SECOND)}s`);
+/**
+ * One turn seen through to an answer: negotiated with the endpoint, retried where the failure is
+ * transient, and waited for where the model is still loading.
+ *
+ * @param client - The pooled client for this endpoint.
+ * @param supports - What the endpoint has already refused, threaded through the negotiation.
+ * @param request - Builds the body. Called again per attempt, since a downgrade changes it. Its
+ * second argument is what the model named in `options.model` has refused, absent when none was.
+ * @param [options] - Retry budget, context limit, the model to negotiate for, notices, and the
+ * stream's own callbacks.
+ * @returns The turn the attempt that got through produced, its usage carrying what every attempt
+ * together cost: `wallMs`, `retries` and `timeouts`.
+ *
+ * @remarks
  * `request` is a callback rather than a body because the body has to be rebuilt from whatever
  * the last attempt latched off: the tools it sends depend on `strictSchemas`, and `relaxTools`
  * has to apply to the schemas that were just sanitised. It is handed the same `Capabilities`
  * object throughout, and a caller that reads those from its own closure can ignore the argument.
- *
- * @param client The pooled client for this endpoint.
- * @param supports What the endpoint has already refused, threaded through the negotiation.
- * @param request Builds the body. Called again per attempt, since a downgrade changes it. Its
- * second argument is what the model named in `options.model` has refused, absent when none was.
- * @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, droppable, loadingTimeoutMs = LOADING_TIMEOUT_MS, ...stream } = {}) {
     // Sized once rather than per build. `request` is called again for every downgrade and every
@@ -29,22 +80,7 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
         sent = body;
         if (!sized && contextLimit >= SMALLEST_LIKELY_WINDOW) {
             sized = true;
-            const needed = requestTokens(body, {
-                charsPerToken: charsPerTokenFor(supports, body.model),
-            });
-            // 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 + 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)}`);
-            }
+            refuseOversized(body, contextLimit, charsPerTokenFor(supports, body.model));
         }
         return body;
     };
@@ -58,8 +94,9 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
         const produced = { any: false };
         try {
             const turn = await negotiate(supports, (capabilities, box, forModel) => streamTurn(client, measured(capabilities, forModel), { ...stream, produced: box }), { produced, onNotice, model, droppable });
-            if (sent)
+            if (sent) {
                 calibrate(supports, sent, turn.usage.prompt);
+            }
             Object.assign(turn.usage, { wallMs: Date.now() - started, retries, timeouts });
             return turn;
         }
@@ -67,8 +104,9 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
             // The abort is read before the classification, not after. A run stopped by its operator
             // can trip the idle watchdog on the way out, and `EndpointSilent` is transient by the
             // rules in `retry.ts` — so classifying first brings a cancelled run back from the dead.
-            if (produced.any || stream.signal?.aborted)
+            if (produced.any || stream.signal?.aborted) {
                 throw error;
+            }
             // The endpoint's own refusal, classified here rather than left to the caller. One failure
             // had two error types depending on an option about something else: a caller that gave a
             // `contextLimit` got `ContextOverflow` from the guard above, and one that did not — the
@@ -86,7 +124,7 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
                 const now = Date.now();
                 if (loadingSince === undefined) {
                     loadingSince = now;
-                    onNotice?.(`${model ?? "the model"} is still loading — waiting up to ${compact(loadingTimeoutMs / 1000)}s`);
+                    onNotice?.(`${modelLabel(model)} is still loading — waiting up to ${compact(loadingTimeoutMs / MS_PER_SECOND)}s`);
                 }
                 if (now - loadingSince < loadingTimeoutMs) {
                     // Not an attempt: the request was never looked at, and a two-minute load would
@@ -96,16 +134,15 @@ export async function runTurn(client, supports, request, { maxRetries = 0, onNot
                     continue;
                 }
             }
-            if (attempt >= maxRetries || !isTransient(error))
+            if (attempt >= maxRetries || !isTransient(error)) {
                 throw error;
+            }
             retries++;
-            if (error instanceof EndpointSilent)
+            if (error instanceof EndpointSilent) {
                 timeouts++;
+            }
             const wait = backoffMs(attempt);
-            // Reported in whatever unit reads as a number: the first backoff is under a second, and
-            // "retrying in 0s" is what rounding it to seconds says.
-            const delay = wait < 1000 ? `${Math.round(wait)}ms` : `${Math.round(wait / 1000)}s`;
-            onNotice?.(`${errorMessage(error)} — retrying in ${delay} (${attempt + 1}/${maxRetries})`);
+            onNotice?.(`${errorMessage(error)} — retrying in ${shownDelay(wait)} (${attempt + 1}/${maxRetries})`);
             await sleep(wait, stream.signal);
         }
     }