@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/retry.js

@@ -1,5 +1,6 @@
-import OpenAI from "openai";
-import { CHARS_PER_TOKEN } from "./tokens.js";
+import OpenAI from 'openai';
+import { ABORT_EVENT } from './platform.js';
+import { HttpStatus } from './wire.js';
 /**
  * Everything about a request failing that is not about what the request said.
  *
@@ -10,270 +11,21 @@ import { CHARS_PER_TOKEN } from "./tokens.js";
  */
 /** The endpoint stopped answering mid-request. Its own class so the retry can recognise it. */
 export class EndpointSilent extends Error {
-    name = "EndpointSilent";
+    name = 'EndpointSilent';
 }
 /**
  * The request was bigger than the model will read. Its own class so nothing retries it: sending
  * the same too-large request again is the same refusal, one round trip later.
  *
+ * @remarks
  * `runTurn` raises it from either side of the round trip — its own pre-flight guard, or the
  * endpoint's refusal read back through `isOverflow` — so a caller has one thing to catch whether
  * or not it gave a `contextLimit`. The second carries the endpoint's own message, and the error
  * it was built from as `cause`.
  */
 export class ContextOverflow extends Error {
-    name = "ContextOverflow";
+    name = 'ContextOverflow';
 }
-/**
- * 1234 → "1.2k". The numbers in an overflow message are large and nobody reads the units digit.
- *
- * @param tokens The count to render.
- */
-export const compact = (tokens) => tokens >= 1000 ? `${(tokens / 1000).toFixed(1)}k` : String(tokens);
-/** What `{"role":"","content":""},` costs around a message's own text, in characters. */
-const ENVELOPE = 25;
-/** The same for `{"id":"","type":"function","function":{"name":"","arguments":""}},` in a call. */
-const CALL_ENVELOPE = 66;
-// `ENVELOPE` is the two keys every message has. These are the three that only some do, and each
-// is the key with its punctuation and the comma after the value it holds — the value's own
-// length is counted where the value is read. Applying `ENVELOPE` alone to these shapes left the
-// keys out, which cost 4.5 tokens on every tool result: the message a tool-using run has most
-// of, and short in the direction that lets an overflow through the guard meant to catch it.
-/** What `"name":"",` costs around a message's name. */
-const NAME_KEY = 10;
-/** The same for `"tool_call_id":"",` around a tool result's call id. */
-const TOOL_CALL_ID_KEY = 18;
-/** The same for `"tool_calls":[]` around the calls; each call's own comma is in `CALL_ENVELOPE`. */
-const TOOL_CALLS_KEY = 15;
-// A content part is an object in the body the same way a message is, and its two keys are in the
-// request exactly as `tool_call_id` was. Charging only `part.text` left them out, which is 6.5
-// tokens per part — short in proportion to how finely the content is split rather than to how
-// much it says, so a transcript a client appends block by block is worst hit.
-/** What `{"type":"text","text":""},` costs around a text part. */
-const TEXT_PART = 26;
-/** The same for `{"type":"refusal","refusal":""},` around a refusal part. */
-const REFUSAL_PART = 32;
-/**
- * The same for `"reasoning_content":"",` around an assistant message's scratchpad.
- *
- * Not in the SDK's types, and passed back by the caller who keeps it: gpt-oss and DeepSeek in
- * thinking mode want the analysis behind a tool call on the next request. Left uncounted, the
- * guard came up short by the whole scratchpad on exactly the runs that follow that rule.
- */
-const REASONING_KEY = 23;
-/** The same for `"reasoning":"",`, OpenRouter's spelling of it. */
-const REASONING_ALT_KEY = 15;
-/** The divisor an option asked for, or the fallback when it asked for nothing usable. */
-const divisor = (charsPerToken) => charsPerToken !== undefined && charsPerToken > 0 ? charsPerToken : CHARS_PER_TOKEN;
-/**
- * How many characters one message is worth: its keys, and its content in whichever shape.
- *
- * @param message The message as it will be sent.
- */
-export function messageChars(message) {
-    let chars = message.role.length + ENVELOPE;
-    const { content } = message;
-    if (typeof content === "string")
-        chars += content.length;
-    else if (Array.isArray(content))
-        for (const part of content) {
-            // Text and refusal parts carry their own strings; an image or an audio part carries a URL
-            // or a blob, and neither is priced by its length anyway — a vision model does not charge
-            // an image by its base64 length, so counting the data URL would overshoot by more than
-            // leaving the part out undershoots.
-            if (part.type === "text")
-                chars += TEXT_PART + part.text.length;
-            else if (part.type === "refusal")
-                chars += REFUSAL_PART + part.refusal.length;
-        }
-    if ("name" in message && typeof message.name === "string")
-        chars += NAME_KEY + message.name.length;
-    if ("tool_call_id" in message && typeof message.tool_call_id === "string")
-        chars += TOOL_CALL_ID_KEY + message.tool_call_id.length;
-    const { reasoning_content: reasoning, reasoning: alternate } = message;
-    if (typeof reasoning === "string")
-        chars += REASONING_KEY + reasoning.length;
-    if (typeof alternate === "string")
-        chars += REASONING_ALT_KEY + alternate.length;
-    if ("tool_calls" in message && Array.isArray(message.tool_calls)) {
-        chars += TOOL_CALLS_KEY;
-        for (const call of message.tool_calls) {
-            chars += CALL_ENVELOPE + call.id.length;
-            if (call.type === "function")
-                chars += call.function.name.length + call.function.arguments.length;
-        }
-    }
-    return chars;
-}
-/**
- * The tools half, cached against the array.
- *
- * Serialising two dozen JSON schemas to measure them, on every turn, to get the same number every
- * time, was the more expensive half of this function.
- *
- * The array is the key, so this pays only a caller that hands the same one back. That is not what
- * a turn built through `sanitizeTools` or `relaxTools` does — both are a `map`, so each build
- * allocates a fresh array however stable the tools inside it are, and those builds miss here every
- * time. It is not free to change: keying on the tools instead would hit for them, at the cost of
- * the array-level memoisation `tests/retry.test.ts` pins, which deliberately holds a mutated array
- * to its first reading. Sizing happens once per turn either way, so the miss costs one walk of the
- * schemas rather than a walk per attempt.
- *
- * Characters rather than tokens, so a calibrated divisor applies to the schemas without walking
- * them again.
- */
-const toolLengths = new WeakMap();
-/**
- * How many characters a tool array is worth, measured once per array.
- *
- * @param tools The tool definitions as they will be sent. An empty array is worth nothing.
- */
-export function toolsChars(tools) {
-    if (!tools.length)
-        return 0;
-    const hit = toolLengths.get(tools);
-    if (hit !== undefined)
-        return hit;
-    // Schemas are arbitrarily shaped, so this one really is a serialisation — but it happens once
-    // per tool array rather than once per turn.
-    const length = JSON.stringify(tools).length;
-    toolLengths.set(tools, length);
-    return length;
-}
-/**
- * How many characters a request is worth: the walk `requestTokens` divides, without the division.
- *
- * What calibration reads a reported prompt count against, since a ratio is only as good as the
- * character count it was taken over agreeing with the one it is later applied to.
- *
- * @param body The request as it was sent, tools included.
- */
-export function requestChars(body) {
-    let chars = 0;
-    for (const message of body.messages)
-        chars += messageChars(message);
-    return chars;
-}
-/**
- * What this request will cost the window, in tokens, near enough.
- *
- * See `estimateTokens` for why it is characters over four and which way it is wrong on purpose,
- * and `charsPerTokenFor` for the divisor a model's own reported usage has measured instead.
- *
- * Summed by walking the body rather than by serialising it. `JSON.stringify` on the messages
- * built the entire transcript into a string on every call and threw it away having read nothing
- * but its `.length` — against a transcript that grows by a turn each turn, and one the SDK is
- * about to serialise again to send. What the walk misses is JSON's own punctuation and the keys,
- * which the envelope constants put back — one per key and one per content part, rather than one
- * per message, since the keys only some shapes carry and the parts a client appends block by
- * block are most of what a tool-using transcript is made of. What is left is a message's
- * escaping, which is not a constant and is small against an estimate that is already characters
- * over four.
- *
- * @param body The request as it will be sent, tools included.
- * @param options The divisor, `CHARS_PER_TOKEN` when none is given.
- */
-export const requestTokens = (body, { charsPerToken } = {}) => {
-    // Characters first and the division once at the end, rather than a rounded count per message:
-    // `Math.ceil` on every one of a few hundred messages is a few hundred tokens of pure rounding.
-    // The tools are divided on their own, as they were when their tokens were cached, so the
-    // uncalibrated count is the one it always was.
-    const per = divisor(charsPerToken);
-    return Math.ceil(requestChars(body) / per) + Math.ceil(toolsChars(body.tools ?? []) / per);
-};
-/** The parts, in the order a readout reads them. */
-const PARTS = ["system", "tools", "history", "toolResults"];
-/**
- * What each part of a request is worth in characters, by the same walk `requestTokens` divides.
- *
- * Exact and additive: the parts sum to `total`, which is `requestChars` plus `toolsChars`. The
- * conversion to tokens is `contextTokens`' business, because that is where an estimate and a
- * reported count have to be told apart.
- *
- * @param body The request as it will be sent, tools included.
- */
-export function contextChars(body) {
-    const out = {
-        system: 0,
-        tools: toolsChars(body.tools ?? []),
-        history: 0,
-        toolResults: 0,
-        total: 0,
-    };
-    for (const message of body.messages) {
-        const chars = messageChars(message);
-        // Every system message and not just the leading one: a host that appends guidance, or a
-        // hook that injects a preface, has put more of the window there and wants to be told so.
-        if (message.role === "system" || message.role === "developer")
-            out.system += chars;
-        else if (message.role === "tool")
-            out.toolResults += chars;
-        else
-            out.history += chars;
-    }
-    out.total = out.system + out.tools + out.history + out.toolResults;
-    return out;
-}
-/**
- * Shares `total` out over these parts by their character counts, the largest absorbing the
- * rounding so they add up to it exactly rather than to within a few tokens of it.
- */
-function share(chars, over, total) {
-    const out = { system: 0, tools: 0, history: 0, toolResults: 0, total };
-    const measured = over.reduce((sum, part) => sum + chars[part], 0);
-    if (measured <= 0 || total <= 0)
-        return out;
-    const absorber = over.reduce((a, b) => (chars[b] > chars[a] ? b : a));
-    let assigned = 0;
-    for (const part of over) {
-        if (part === absorber)
-            continue;
-        out[part] = Math.round((chars[part] / measured) * total);
-        assigned += out[part];
-    }
-    out[absorber] = Math.max(0, total - assigned);
-    return out;
-}
-/**
- * What each part of a request costs the window, in tokens, adding up to the whole.
- *
- * Shares rather than four independent estimates, because a readout whose parts do not add up to
- * the total beside them is a readout nobody trusts. Nothing in the round trip reports anything
- * finer than a prompt count — a completion says how many tokens it read and not a word about
- * where they came from — so the proportions are an estimate whatever the total is.
- *
- * Without a reported count the total is `requestTokens`, and the tools are counted the way it and
- * `TurnMetrics.toolSchemaTokens` count them rather than shared out, so the two agree by
- * construction and an operator does not read one number for the tool block in the metrics and a
- * different one here. With a reported count every part is a share of it, the tools included:
- * that number is the server's, and the point of using it is that the parts sum to what was
- * charged.
- *
- * @param body The request as it will be sent, tools included.
- * @param options The divisor, and the reported prompt count when there is one.
- */
-export function contextTokens(body, { charsPerToken, promptTokens } = {}) {
-    const chars = contextChars(body);
-    if (promptTokens !== undefined && promptTokens > 0)
-        return share(chars, PARTS, promptTokens);
-    const per = divisor(charsPerToken);
-    const tools = Math.ceil(chars.tools / per);
-    const rest = Math.ceil((chars.total - chars.tools) / per);
-    const out = share(chars, ["system", "history", "toolResults"], rest);
-    out.tools = tools;
-    out.total = rest + tools;
-    return out;
-}
-/**
- * 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.
- * @param options The divisor, `CHARS_PER_TOKEN` when none is given.
- */
-export const messageTokens = (message, { charsPerToken } = {}) => Math.ceil(messageChars(message) / divisor(charsPerToken));
 /**
  * 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
@@ -288,6 +40,7 @@ const OVERFLOW = [
 /**
  * A rate limit says the same words and means the opposite thing.
  *
+ * @remarks
  * OpenAI refuses a request over the per-minute token budget with "Request too large for gpt-4o
  * ... on tokens per min (TPM)", which is "too large for" beside "tokens" — both halves of the
  * test below. That is a 429, which `isTransient` accepts and which succeeds on the next attempt;
@@ -298,17 +51,19 @@ const RATE_LIMITED = /per (min|hour|day)|rate.?limit|\b[tr]pm\b|quota/i;
 /**
  * Whether a refusal means the request was too big, rather than merely refused.
  *
+ * @param detail - The endpoint's own message.
+ * @returns `true` for an overflow: one of the over-long wordings, beside `token` or `context`.
+ * `false` for anything that reads as a rate limit, whatever else it says.
+ *
+ * @remarks
  * Rate limits are ruled out first: they borrow the same words and mean the opposite, being worth
  * another attempt where an overflow never is.
- *
- * @param detail The endpoint's own message.
  */
-export const isOverflow = (detail) => !RATE_LIMITED.test(detail) &&
-    OVERFLOW.some((pattern) => pattern.test(detail)) &&
-    /token|context/i.test(detail);
+export const isOverflow = (detail) => !RATE_LIMITED.test(detail) && OVERFLOW.some((pattern) => pattern.test(detail)) && /token|context/i.test(detail);
 /**
  * The smallest window worth believing in, and the floor under `runTurn`'s guard.
  *
+ * @remarks
  * `runTurn`'s `contextLimit` reads it as a sanity check on a number it was handed: below this,
  * the limit is taken for a placeholder — an unset column, a listing that said nothing — rather
  * than a window worth refusing a run over. That is the whole of what reads it; `contextLimitFor`
@@ -322,83 +77,115 @@ export const isOverflow = (detail) => !RATE_LIMITED.test(detail) &&
  * guarded wrongly.
  */
 export const SMALLEST_LIKELY_WINDOW = 8192;
+/** The statuses below 500 that say "not now" rather than "not this": a timeout, a conflict, a rate limit. */
+const TRANSIENT_STATUSES = new Set([
+    HttpStatus.RequestTimeout,
+    HttpStatus.Conflict,
+    HttpStatus.TooManyRequests,
+]);
 /**
  * Whether a failed request is worth trying again.
  *
+ * @param error - The rejection, as caught. What is not an SDK error is not transient.
+ * @returns `true` for an `EndpointSilent`, a connection error, a 408, 409 or 429, and any status
+ * of 500 or above; `false` for any other SDK error, one with no status included.
+ *
+ * @remarks
  * The question is whether the request was *refused or lost*, rather than answered with a
  * complaint about its contents: a connection that never landed, a server too busy or too broken
  * to answer, an endpoint that went quiet. A 400 for a malformed tool schema would fail exactly
  * the same way on every attempt, and the two capability cases below are negotiated rather than
  * retried blindly.
- *
- * @param error The rejection, as caught. What is not an SDK error is not transient.
  */
 export function isTransient(error) {
-    if (error instanceof EndpointSilent)
+    if (error instanceof EndpointSilent) {
         return true;
-    if (error instanceof OpenAI.APIConnectionError)
+    }
+    if (error instanceof OpenAI.APIConnectionError) {
         return true;
-    if (!(error instanceof OpenAI.APIError))
+    }
+    if (!(error instanceof OpenAI.APIError)) {
         return false;
+    }
     const { status } = error;
-    return status === 408 || status === 409 || status === 429 || (status ?? 0) >= 500;
+    return status !== undefined && (TRANSIENT_STATUSES.has(status) || status >= HttpStatus.InternalServerError);
 }
 /**
  * Whether a failure is the endpoint refusing the request as written, rather than losing it.
  *
+ * @param error - The rejection, as caught. What is not an SDK error refuses nothing.
+ * @returns `true` for an SDK error whose status is 400 or 422, and for nothing else.
+ *
+ * @remarks
  * 400 and 422 are what a server says when it read the body and disliked it, which makes them the
  * only statuses worth answering by sending something different. Any 4xx is too wide: 401, 404 and
  * 429 are 4xx and none of them is about the fields, and a 429 is one `isTransient` accepts — a
  * caller that re-sent on it at once doubled the rate against a server that had just asked for less.
  * Catching everything is wider still, since an abort or a connection that never landed then
  * latches off whatever the re-send left out.
- *
- * @param error The rejection, as caught. What is not an SDK error refuses nothing.
  */
-export const refusesRequest = (error) => error instanceof OpenAI.APIError && (error.status === 400 || error.status === 422);
+export const refusesRequest = (error) => error instanceof OpenAI.APIError &&
+    (error.status === HttpStatus.BadRequest || error.status === HttpStatus.UnprocessableEntity);
+/** The error type llama.cpp gives a request it cannot serve yet. */
+const UNAVAILABLE_ERROR = 'unavailable_error';
 /**
  * Whether a failure is a local server still loading the model, rather than one failing to serve.
  *
+ * @param error - The rejection, as caught.
+ * @returns `true` for a 503 whose body is of type `unavailable_error`, or whose message says the
+ * model is loading; `false` for any other status and for what is not an SDK error.
+ *
+ * @remarks
  * llama.cpp answers 503 `Loading model` with type `unavailable_error` from the moment it starts
  * until the weights are mapped, and a router build says the same while it swaps models. That is
  * thirty to ninety seconds for a large model from a cold page cache, and `backoffMs` gives up
  * inside fifteen: sized for a busy host, not for one reading a file. A plain 503 is not this.
- *
- * @param error The rejection, as caught.
  */
 export function isModelLoading(error) {
-    if (!(error instanceof OpenAI.APIError) || error.status !== 503)
+    if (!(error instanceof OpenAI.APIError) || error.status !== HttpStatus.ServiceUnavailable) {
         return false;
+    }
     const body = error.error;
-    return (body?.type === "unavailable_error" ||
-        /loading model|model is loading|unavailable_error/i.test(`${error.message} ${body?.message ?? ""}`));
+    return (body?.type === UNAVAILABLE_ERROR ||
+        /loading model|model is loading|unavailable_error/i.test(`${error.message} ${body?.message ?? ''}`));
 }
 /** How long to wait between asking a loading server again. */
 export const LOADING_POLL_MS = 3000;
 /** How long `runTurn` waits for a model to load unless told otherwise. */
 export const LOADING_TIMEOUT_MS = 120_000;
+/** The first backoff, before jitter, which each attempt after it doubles. */
+const BACKOFF_BASE_MS = 500;
+/** The longest a backoff grows to, before jitter. */
+const BACKOFF_CEILING_MS = 8000;
+/** The least of a backoff that jitter leaves: a wait is somewhere between this share of it and all of it. */
+const JITTER_FLOOR = 0.5;
 /**
- * Exponential, with jitter so several tasks failing at once do not return in lockstep.
+ * How long to wait before a retry: exponential, with jitter so several tasks failing at once do
+ * not return in lockstep.
  *
- * @param attempt Zero-based. Doubles from 500ms to a ceiling of eight seconds, before jitter.
+ * @param attempt - Zero-based. Doubles from 500ms to a ceiling of eight seconds, before jitter.
+ * @returns Milliseconds, somewhere between half of that wait and all of it, and not a whole number.
  */
-export const backoffMs = (attempt) => Math.min(8000, 2 ** attempt * 500) * (0.5 + Math.random() / 2);
+export const backoffMs = (attempt) => Math.min(BACKOFF_CEILING_MS, 2 ** attempt * BACKOFF_BASE_MS) * (JITTER_FLOOR + Math.random() * (1 - JITTER_FLOOR));
 /**
  * A delay an abort cuts short, rejecting rather than resolving early.
  *
- * @param ms How long to wait.
- * @param signal Abandons the wait. One already aborted rejects without waiting at all.
+ * @param ms - How long to wait.
+ * @param [signal] - Abandons the wait. One already aborted rejects without waiting at all.
+ * @returns A promise that resolves once `ms` has passed, or rejects with the signal's reason — an
+ * `Error` of its own where the signal carries none.
  */
 export const sleep = (ms, signal) => new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
-        signal?.removeEventListener("abort", onAbort);
+        signal?.removeEventListener(ABORT_EVENT, onAbort);
         resolve();
     }, ms);
     const onAbort = () => {
         clearTimeout(timer);
-        reject(signal?.reason ?? new Error("aborted"));
+        reject(signal?.reason ?? new Error('aborted'));
     };
-    if (signal?.aborted)
+    if (signal?.aborted) {
         return onAbort();
-    signal?.addEventListener("abort", onAbort, { once: true });
+    }
+    signal?.addEventListener(ABORT_EVENT, onAbort, { once: true });
 });

package/dist/run-calls.d.ts

@@ -0,0 +1,123 @@
+import type OpenAI from 'openai';
+import type { CatalogServer } from './catalog.ts';
+import type { RunEventInput } from './events.ts';
+import type { Turn } from './stream.ts';
+import { type ToolCall, type ToolCallOutcome, type ToolCallRequest, type ToolCallResult } from './tool-calls.ts';
+/**
+ * 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 declare const preview: (text: string, limit?: number) => string;
+/** One of a turn's calls with its arguments read, or with the reason they could not be. */
+export interface ReadCall {
+    call: ToolCall;
+    /** Absent where the arguments could not be read. */
+    args?: Record<string, unknown>;
+    /** Why they could not, which is then the call's answer. */
+    error?: unknown;
+    /** The arguments as every later request replays them: the repaired JSON, or `{}` for none. */
+    normal: string;
+}
+/**
+ * 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 declare const readCalls: (calls: ToolCall[], finishReason: Turn['finishReason']) => ReadCall[];
+/**
+ * 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 declare const assistantMessage: (content: string, parsed: ReadCall[]) => OpenAI.ChatCompletionAssistantMessageParam;
+/**
+ * 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 declare const definedAs: (definitions: ReadonlyMap<string, OpenAI.ChatCompletionTool>, names: Iterable<string>) => (OpenAI.ChatCompletionCustomTool | OpenAI.ChatCompletionFunctionTool)[];
+/** Runs one tool call and resolves to what the model reads; what it throws, the model reads too. */
+export type ToolDispatch = (call: ToolCallRequest, signal?: AbortSignal) => Promise<string>;
+/**
+ * What running a step's calls reads of the run and writes back into it. One per run, shared by
+ * every step: the sets and counts here are the run's own, not copies.
+ */
+export interface Calling {
+    catalog: CatalogServer[];
+    /** Whether tools are loaded from the catalogue, behind a moving tool array or a fixed one. */
+    onDemand: boolean;
+    /** Whether the tool array is the fixed one, so a definition lives in the history. */
+    proxied: boolean;
+    /** Whether a `call_tool` is looked through, which it is unless the host has a tool by that name. */
+    proxies: boolean;
+    definitions: ReadonlyMap<string, OpenAI.ChatCompletionTool>;
+    loaded: Set<string>;
+    loads: {
+        toolsLoaded: number;
+        redundantLoads: number;
+        unknownToolNames: number;
+    };
+    used: Set<string>;
+    toolCalls: ToolCallOutcome[];
+    dedupable: (call: ToolCallRequest) => boolean;
+    dispatch: ToolDispatch;
+    parallel: boolean;
+    signal: AbortSignal | undefined;
+    onEvent: (input: RunEventInput) => void;
+    onToolCall: ((call: ToolCallRequest) => void) | undefined;
+    onToolResult: ((result: ToolCallResult) => void) | undefined;
+    /** Offers a message just written into the transcript to the host. */
+    announce: (message: OpenAI.ChatCompletionMessageParam, step: number) => Promise<void>;
+}
+/**
+ * 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 declare function runCalls(run: Calling, parsed: ReadCall[], messages: OpenAI.ChatCompletionMessageParam[], step: number): Promise<void>;
+/**
+ * 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 declare function loadShortlist(run: Calling, shortlist: OpenAI.ChatCompletionTool[], messages: OpenAI.ChatCompletionMessageParam[]): Promise<void>;