@cubicecho/agent-core 2.3.0 → 2.5.0

package/dist/tool-calls.js

@@ -0,0 +1,346 @@
+/**
+ * Tool arguments that could not be read as an object, with why.
+ *
+ * `truncated` is a call cut off at the reply ceiling, which no repair can finish and the fix for
+ * is a larger `maxTokens`; `malformed` is one the model wrote wrongly, which it can be told about
+ * and try again.
+ */
+export class ToolArgumentsError extends Error {
+    /** Whether the model ran out of room or wrote something unreadable. */
+    kind;
+    /**
+     * @param kind Why the arguments could not be read.
+     * @param message What the model is handed back as the tool's result.
+     */
+    constructor(kind, message) {
+        super(message);
+        this.name = "ToolArgumentsError";
+        this.kind = kind;
+    }
+}
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Rewrites the almost-JSON local models write into JSON, in one pass that knows where strings are.
+ *
+ * Single-quoted strings become double-quoted, Python's `True`, `False` and `None` become their JSON
+ * spellings, bare keys are quoted, and a comma before a closing bracket is dropped. Nothing inside
+ * a string is touched, so an argument that happens to say `True` or `a, }` survives.
+ */
+function repairJson(text) {
+    let out = "";
+    for (let i = 0; i < text.length;) {
+        const char = text[i];
+        if (char === '"' || char === "'") {
+            let body = "";
+            let j = i + 1;
+            for (; j < text.length && text[j] !== char; j++) {
+                if (text[j] === "\\" && j + 1 < text.length) {
+                    // `\'` means nothing in JSON; a quote that needed escaping in single quotes does not.
+                    body += char === "'" && text[j + 1] === "'" ? "'" : text[j] + text[j + 1];
+                    j++;
+                }
+                else {
+                    body += char === "'" && text[j] === '"' ? '\\"' : text[j];
+                }
+            }
+            out += `"${body}"`;
+            i = j + 1;
+            continue;
+        }
+        if (char === ",") {
+            const next = text.slice(i + 1).match(/^\s*([\]}])?/);
+            if (next?.[1]) {
+                i++;
+                continue;
+            }
+        }
+        const word = /[A-Za-z_$]/.test(char)
+            ? text.slice(i).match(/^[A-Za-z_$][\w$]*/)?.[0]
+            : undefined;
+        if (word) {
+            const python = { True: "true", False: "false", None: "null" }[word];
+            if (/^\s*:/.test(text.slice(i + word.length)))
+                out += `"${word}"`;
+            else
+                out += python ?? word;
+            i += word.length;
+            continue;
+        }
+        out += char;
+        i++;
+    }
+    return out;
+}
+/** JSON as it was written, then repaired, then undefined. A string holding JSON is opened once. */
+function looseJson(text) {
+    for (const candidate of [text, repairJson(text)]) {
+        try {
+            const value = JSON.parse(candidate);
+            if (typeof value !== "string")
+                return value;
+            const inner = value.trim();
+            if (!/^[[{]/.test(inner))
+                return value;
+            return looseJson(inner) ?? value;
+        }
+        catch {
+            // The next candidate.
+        }
+    }
+    return undefined;
+}
+/**
+ * A tool call's arguments as the object the tool is handed. Empty is no arguments.
+ *
+ * Lenient where the model's meaning is plain and strict where it is not: an object already
+ * parsed passes through, JSON inside a string is opened, and the almost-JSON local models write —
+ * single quotes, `True`, bare keys, a trailing comma — is repaired. What is still not an object
+ * throws a `ToolArgumentsError`, and the loop hands its message back to the model as the tool's
+ * result so it can try again.
+ *
+ * @param raw The arguments as the model sent them: usually the streamed string, sometimes an
+ * object a server parsed already. Null, absent or blank is no arguments.
+ * @param options `finishReason`, the turn's. A turn that stopped at `"length"` makes a failure
+ * `truncated`, since a call cut off at the ceiling reads exactly like a malformed one.
+ */
+export function parseToolArguments(raw, { finishReason } = {}) {
+    if (isRecord(raw))
+        return raw;
+    if (raw === null || raw === undefined)
+        return {};
+    const text = typeof raw === "string" ? raw.trim() : JSON.stringify(raw);
+    if (!text)
+        return {};
+    const parsed = looseJson(text);
+    if (isRecord(parsed))
+        return parsed;
+    if (finishReason === "length") {
+        throw new ToolArgumentsError("truncated", `the tool call was cut off at the reply ceiling before its arguments were complete; raise maxTokens: ${text.slice(0, 200)}`);
+    }
+    throw new ToolArgumentsError("malformed", parsed === undefined
+        ? `model produced invalid tool arguments: ${text.slice(0, 200)}`
+        : `model produced tool arguments that are not an object: ${text.slice(0, 200)}`);
+}
+/**
+ * Where the JSON value opening at `start` closes, one past its last character, or -1 when it
+ * never does. Brackets inside either kind of string are not counted.
+ */
+function valueEnd(text, start) {
+    let depth = 0;
+    let quote = "";
+    for (let i = start; i < text.length; i++) {
+        const char = text[i];
+        if (quote) {
+            if (char === "\\")
+                i++;
+            else if (char === quote)
+                quote = "";
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+        }
+        else if (char === "{" || char === "[") {
+            depth++;
+        }
+        else if (char === "}" || char === "]") {
+            depth--;
+            if (depth === 0)
+                return i + 1;
+        }
+    }
+    return -1;
+}
+/**
+ * The JSON value opening at or after `at`, past whitespace, and where it ends. An unclosed one
+ * runs to the end of the text; one that does not parse even repaired is undefined.
+ */
+function readValue(text, at) {
+    const start = at + (text.slice(at).match(/^\s*/)?.[0].length ?? 0);
+    if (text[start] !== "{" && text[start] !== "[")
+        return undefined;
+    const closed = valueEnd(text, start);
+    const end = closed < 0 ? text.length : closed;
+    const value = looseJson(text.slice(start, end));
+    return value === undefined ? undefined : { value, end };
+}
+/** One call in any of the shapes templates write: `{name, arguments}`, `{name, parameters}`, `{function: {...}}`. */
+function toCall(entry) {
+    if (!isRecord(entry))
+        return undefined;
+    const inner = isRecord(entry.function) ? entry.function : entry;
+    const name = inner.name;
+    if (typeof name !== "string" || !name)
+        return undefined;
+    const args = inner.arguments ?? inner.parameters ?? inner.args ?? {};
+    return { name, arguments: typeof args === "string" ? args : JSON.stringify(args) };
+}
+/** Every call in a value that is one call or a list of them, or undefined if any entry is not one. */
+function toCalls(value) {
+    const entries = Array.isArray(value) ? value : [value];
+    const calls = entries.map(toCall);
+    return calls.length && calls.every((call) => call)
+        ? calls
+        : undefined;
+}
+/** A value read as text: JSON where it parses, the string where it does not. */
+function scalar(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** `<tool_call>` blocks: Hermes and Qwen's JSON, and Qwen3-Coder's `<function=…>` markup. */
+function taggedCalls(text) {
+    const found = [];
+    for (const match of text.matchAll(/<tool_call>/g)) {
+        const at = match.index + match[0].length;
+        const closing = /\s*<\/tool_call>/y;
+        const xml = text.slice(at).match(/^\s*<function=([^>\s]+)>([\s\S]*?)<\/function>/);
+        if (xml) {
+            const args = {};
+            for (const param of xml[2].matchAll(/<parameter=([^>\s]+)>\n?([\s\S]*?)\n?<\/parameter>/g)) {
+                args[param[1]] = scalar(param[2]);
+            }
+            closing.lastIndex = at + xml[0].length;
+            const end = closing.test(text) ? closing.lastIndex : at + xml[0].length;
+            found.push({
+                start: match.index,
+                end,
+                calls: [{ name: xml[1], arguments: JSON.stringify(args) }],
+            });
+            continue;
+        }
+        const read = readValue(text, at);
+        const calls = read && toCalls(read.value);
+        if (!read || !calls)
+            continue;
+        closing.lastIndex = read.end;
+        found.push({
+            start: match.index,
+            end: closing.test(text) ? closing.lastIndex : read.end,
+            calls,
+        });
+    }
+    return found;
+}
+/** Mistral's `[TOOL_CALLS] [...]`, and the newer `[TOOL_CALLS]name[ARGS]{...}`. */
+function mistralCalls(text) {
+    const found = [];
+    for (const match of text.matchAll(/\[TOOL_CALLS\]/g)) {
+        const at = match.index + match[0].length;
+        const named = text.slice(at).match(/^\s*([\w.-]+)\[ARGS\]/);
+        if (named) {
+            const read = readValue(text, at + named[0].length);
+            if (!read || !isRecord(read.value))
+                continue;
+            found.push({
+                start: match.index,
+                end: read.end,
+                calls: [{ name: named[1], arguments: JSON.stringify(read.value) }],
+            });
+            continue;
+        }
+        const read = readValue(text, at);
+        const calls = read && toCalls(read.value);
+        if (read && calls)
+            found.push({ start: match.index, end: read.end, calls });
+    }
+    return found;
+}
+/** Llama 3's `<|python_tag|>{...}`, several calls separated by semicolons, up to `<|eom_id|>`. */
+function pythonTagCalls(text) {
+    const found = [];
+    for (const match of text.matchAll(/<\|python_tag\|>/g)) {
+        const calls = [];
+        let end = match.index + match[0].length;
+        for (;;) {
+            const read = readValue(text, end);
+            const more = read && toCalls(read.value);
+            if (!read || !more)
+                break;
+            calls.push(...more);
+            end = read.end;
+            const separator = text.slice(end).match(/^\s*;/);
+            if (!separator)
+                break;
+            end += separator[0].length;
+        }
+        const eom = text.slice(end).match(/^\s*<\|eom_id\|>/);
+        if (eom)
+            end += eom[0].length;
+        if (calls.length)
+            found.push({ start: match.index, end, calls });
+    }
+    return found;
+}
+/**
+ * A bare JSON call — the whole reply, or its one fenced block — naming only tools that exist.
+ * Without the names this is too easily an answer that happens to be JSON.
+ */
+function bareCalls(text, names) {
+    if (!names.size)
+        return [];
+    const known = (calls) => calls?.every((call) => names.has(call.name)) ? calls : undefined;
+    const start = text.search(/\S/);
+    if (start >= 0 && (text[start] === "{" || text[start] === "[")) {
+        const read = readValue(text, start);
+        const calls = read && !text.slice(read.end).trim() ? known(toCalls(read.value)) : undefined;
+        if (read && calls)
+            return [{ start, end: read.end, calls }];
+    }
+    const fences = [...text.matchAll(/```(?:json)?[ \t]*\n?([\s\S]*?)```/gi)];
+    if (fences.length !== 1)
+        return [];
+    const [fence] = fences;
+    const body = fence[1].trim();
+    const read = /^[[{]/.test(body) ? readValue(body, 0) : undefined;
+    const calls = read && !body.slice(read.end).trim() ? known(toCalls(read.value)) : undefined;
+    return calls ? [{ start: fence.index, end: fence.index + fence[0].length, calls }] : [];
+}
+/**
+ * Tool calls a model wrote into its reply as text, taken out of it and made into calls.
+ *
+ * A server whose tool-call parser does not match the model's chat template streams the call as
+ * content, and the run ends on what reads like a finished answer. The templates' own markers are
+ * looked for — `<tool_call>` (Hermes, Qwen, Qwen3-Coder's markup included), `[TOOL_CALLS]`
+ * (Mistral, both spellings) and `<|python_tag|>` (Llama 3) — and, failing those, a reply that is
+ * nothing but a JSON call, or holds one fenced one, provided every name in it is in `names`. Only
+ * text after the last `</think>` is searched, since a model deliberating about a call is not making
+ * one.
+ *
+ * @param content The turn's text.
+ * @param options `names`, the tools that exist. Without them only the templates' markers count.
+ * @returns The text with the calls taken out, and the calls, numbered `call_recovered_0` onward.
+ * No calls leaves the text as it was.
+ */
+export function recoverToolCalls(content, { names = [] } = {}) {
+    const thought = content.toLowerCase().lastIndexOf("</think>");
+    const from = thought < 0 ? 0 : thought + "</think>".length;
+    const tail = content.slice(from);
+    let found = [...taggedCalls(tail), ...mistralCalls(tail), ...pythonTagCalls(tail)];
+    if (!found.length)
+        found = bareCalls(tail, new Set(names));
+    if (!found.length)
+        return { content, toolCalls: [] };
+    found.sort((a, b) => a.start - b.start);
+    let rest = "";
+    let cursor = 0;
+    const toolCalls = [];
+    for (const span of found) {
+        if (span.start < cursor)
+            continue;
+        rest += tail.slice(cursor, span.start);
+        cursor = span.end;
+        for (const call of span.calls) {
+            toolCalls.push({
+                id: `call_recovered_${toolCalls.length}`,
+                type: "function",
+                function: call,
+            });
+        }
+    }
+    rest += tail.slice(cursor);
+    return { content: `${content.slice(0, from)}${rest}`.trim(), toolCalls };
+}

package/dist/tool-loading.d.ts

@@ -135,6 +135,25 @@ export declare function requestedNames(args: Record<string, unknown>): string[];
  * same number: this one is what the preselector is told, and that one is what it is held to.
  */
 export declare const preselectSystem: (maxPerLoad?: number) => string;
+/**
+ * The shape a preselector's answer is held to where the server takes a schema: `{ tools: [...] }`.
+ *
+ * An object around the array rather than the array, because a structured answer's root has to be
+ * an object — OpenAI's strict mode and every tool-schema normaliser insist.
+ */
+export declare const PRESELECT_SCHEMA: {
+    type: string;
+    properties: {
+        tools: {
+            type: string;
+            items: {
+                type: string;
+            };
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
 /** The preselection system prompt at the default cap, for a caller that never changes it. */
 export declare const PRESELECT_SYSTEM: string;
 /**
@@ -151,7 +170,8 @@ export declare const preselectInput: (catalog: CatalogServer[], prompt: string,
 /**
  * Resolves a preselection against the catalogue: unknown names dropped, count capped.
  *
- * @param names What the preselector replied. Unvalidated: a non-array gives none, and entries
+ * @param names What the preselector replied: `{ tools: [...] }` as `PRESELECT_SCHEMA` has it, or
+ * the bare array an older prompt asked for. Unvalidated: anything else gives none, and entries
  * that are not strings are dropped.
  * @param catalog The servers to resolve against.
  * @param maxPerLoad The most to keep, defaulting to `MAX_PER_LOAD`. The same number

package/dist/tool-loading.js

@@ -272,9 +272,22 @@ const PRESELECT_PROMPT_CHARS = 2000;
  * same number: this one is what the preselector is told, and that one is what it is held to.
  */
 export const preselectSystem = (maxPerLoad = MAX_PER_LOAD) => "You choose tools. Below is a catalogue of tool names, then a request. Reply with a JSON " +
-    "array of the names the request is likely to need — exact names from the catalogue, at most " +
-    `${maxPerLoad}, and as few as could do the job. Reply with \`[]\` if the request can be ` +
-    "answered without tools. Reply with the array alone — no prose, no explanation.";
+    'object whose "tools" array holds the names the request is likely to need — exact names from ' +
+    `the catalogue, at most ${maxPerLoad}, and as few as could do the job. Reply with ` +
+    '`{"tools": []}` if the request can be answered without tools. Reply with the object alone — ' +
+    "no prose, no explanation.";
+/**
+ * The shape a preselector's answer is held to where the server takes a schema: `{ tools: [...] }`.
+ *
+ * An object around the array rather than the array, because a structured answer's root has to be
+ * an object — OpenAI's strict mode and every tool-schema normaliser insist.
+ */
+export const PRESELECT_SCHEMA = {
+    type: "object",
+    properties: { tools: { type: "array", items: { type: "string" } } },
+    required: ["tools"],
+    additionalProperties: false,
+};
 /** The preselection system prompt at the default cap, for a caller that never changes it. */
 export const PRESELECT_SYSTEM = preselectSystem();
 /**
@@ -291,15 +304,19 @@ export const preselectInput = (catalog, prompt, maxPromptChars = PRESELECT_PROMP
 /**
  * Resolves a preselection against the catalogue: unknown names dropped, count capped.
  *
- * @param names What the preselector replied. Unvalidated: a non-array gives none, and entries
+ * @param names What the preselector replied: `{ tools: [...] }` as `PRESELECT_SCHEMA` has it, or
+ * the bare array an older prompt asked for. Unvalidated: anything else gives none, and entries
  * that are not strings are dropped.
  * @param catalog The servers to resolve against.
  * @param maxPerLoad The most to keep, defaulting to `MAX_PER_LOAD`. The same number
  * `preselectSystem` was given, or the model is being held to a cap it was never told about.
  */
 export function preselection(names, catalog, maxPerLoad = MAX_PER_LOAD) {
-    if (!Array.isArray(names))
+    const list = names && typeof names === "object" && !Array.isArray(names)
+        ? names.tools
+        : names;
+    if (!Array.isArray(list))
         return [];
-    const wanted = names.filter((name) => typeof name === "string");
+    const wanted = list.filter((name) => typeof name === "string");
     return expandNames(wanted, catalog, maxPerLoad).matched.slice(0, maxPerLoad);
 }

package/llms.txt

@@ -9,6 +9,21 @@ Full prose, worked examples and the reasoning behind each seam are in README.md;
 
 ## Exports
 
+### agent-loop
+
+The loop above a turn: send, run the tools the model asked for, send again, until it stops asking.
+
+- `AgentLoopHooks` (type) — The hooks a loop runs around one question.
+- `AgentLoopOptions` (type) — What `runAgentLoop` takes.
+- `AgentLoopResult` (type) — What a finished loop hands back.
+- `buildBody` — The one place a streamed request's body is decided from a config and what the endpoint and the model have refused.
+- `preselect` — The tools a request is likely to need, picked by a small model before the run starts, or none.
+- `preview` — A long tool argument or result cut to what a watcher needs, with the full length said.
+- `resolveApiKey` — The key to send, where an endpoint may inherit one from the settings it overrides.
+- `runAgentLoop` — Runs a question to its answer: one `runTurn` per step, the tools it asks for between them, until a turn asks for none.
+- `ToolCallOutcome` (type) — What one tool call did, in the order the model asked.
+- `ToolCallRequest` (type) — One call the model made, as `dispatch` is handed it.
+
 ### capabilities
 
 What an endpoint turned out not to support, and answering it when it says so.
@@ -37,6 +52,23 @@ The contract between whatever holds the tools and the loop that offers them to a
 - `resetClients` — Forgets every cached client and listing.
 - `timeoutMs` — Zero, less, or absent means no limit, which the SDK spells as `undefined`.
 
+### compaction
+
+Keeping a long run inside its window: stale tool results cleared, and the oldest stretch folded into a summary the model writes itself.
+
+- `COMPACT_AT` — The fraction of the window in use before a summary is worth its own round trip.
+- `CompactionOptions` (type) — What `planCompaction` takes.
+- `CompactionPlan` (type) — Where to cut, as `compactTranscript` takes it.
+- `compactTranscript` — The transcript with the plan's stretch replaced by one system message holding its summary.
+- `KEEP_RATIO` — The fraction of the window the kept tail may fill, leaving room for the run to grow again.
+- `PruneOptions` (type) — What `pruneToolResults` takes.
+- `planCompaction` — Where to fold a transcript that has grown into its window, or `undefined` when it should not be.
+- `pruneToolResults` — The transcript with every tool result but the latest few replaced by a one-line stub.
+- `SUMMARY_LEAD` — How a summary message opens, which is also how `planCompaction` knows one from a system prompt.
+- `SUMMARY_PROMPT` — The summariser's instruction when the caller gives none.
+- `summariser` — A summariser that asks `model` with `SUMMARY_PROMPT`, for `compactTranscript`.
+- `summaryInput` — 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.
+
 ### config
 
 What this package needs to know about a caller's configuration.
@@ -73,19 +105,22 @@ What a run is doing, while it is doing it.
 Lifecycle hooks, from the host's side: what a session looks like to them, where their context lands in a request, and what is said about each one.
 
 - `assembleContext` — Builds the context a set of outcomes adds and the notes that go with it.
+- `configureHooks` — Changes what hooks are held to, for a process whose windows are not the size these defaults were chosen for.
 - `Gathered` (type) — The context a set of outcomes adds to a request, and a note for each hook worth mentioning.
 - `gather` — Runs the hooks ahead of a request and builds what they add to it.
-- `HOOK_CONTEXT_TOKENS` — The most context all of a request's hooks add between them, in estimated tokens.
+- `HOOK_CONTEXT_TOKENS` — The most context all of a request's hooks add between them by default, in estimated tokens.
 - `HOOK_EVENTS` — Every event a hook can be bound to, in the order a session meets them.
 - `HOOK_PREFACE` — Said once, above the blocks, so the model reads them as background rather than instructions.
 - `HookContext` (type) — What a host knows at an event.
 - `HookEvent` (type) — A point in a session a hook can be bound to.
 - `HookMessage` (type) — One message of a session as a hook is handed it.
 - `HookNote` (type) — One hook's line for whoever is watching: the context it added, or why it added none.
+- `HookOptions` (type) — What hooks are held to across a process.
 - `HookOutcome` (type) — What one hook did.
 - `HookRunner` (type) — Runs one event's hooks.
 - `INJECT_EVENTS` — The events whose hooks run before a request, and so the only ones whose output can reach it.
 - `notify` — Runs the hooks for an event that reads what happened and adds nothing to a request.
+- `resetHooks` — Test seam: puts `configureHooks` back to the defaults, so one test's budget is not the next's.
 - `turnIndex` — Which turn of a session begins at a point, from 0: the user messages ahead of it.
 - `turnMessages` — A stretch of a transcript as a hook reads it: what the user and the assistant said, and nothing else.
 - `withContext` — The request, with the hooks' context added to this turn's question.
@@ -104,6 +139,7 @@ Everything about a request failing that is not about what the request said.
 - `EndpointSilent` — The endpoint stopped answering mid-request.
 - `isOverflow` — Whether a refusal means the request was too big, rather than merely refused.
 - `isTransient` — Whether a failed request is worth trying again.
+- `messageTokens` — One message's estimated tokens, by the same count `requestTokens` sums for a whole request.
 - `requestTokens` — What this request will cost the window, in tokens, near enough.
 - `SMALLEST_LIKELY_WINDOW` — The smallest window worth believing in, and the floor under `runTurn`'s guard.
 - `sleep` — A delay an abort cuts short, rejecting rather than resolving early.
@@ -127,7 +163,9 @@ JSON Schema compatibility for llama.cpp-backed servers.
 
 One-shot calls that support a run without being one: picking tools, naming a session, summarising a transcript, proposing follow-ups.
 
+- `AskJsonOptions` (type) — What `askJson` takes besides a side task's options.
 - `ask` — Runs a side task and returns the reply text, thinking stripped.
+- `askJson` — A side task whose answer is JSON matching a schema, parsed.
 - `clean` — Strips the quoting and list punctuation models decorate short answers with.
 - `listLines` — A list-shaped reply, one item per line, cleaned of the bullets and quotes models decorate them with.
 - `parseJson` — Models are asked for JSON and often answer with prose around it, or a fenced block.
@@ -135,6 +173,17 @@ One-shot calls that support a run without being one: picking tools, naming a ses
 - `SideTaskOptions` (type) — What a side task may be given.
 - `tryAsk` — A side task is never worth failing the work it supports.
 
+### snapshot
+
+What endpoints and models refused, carried across a restart.
+
+- `CAPABILITY_SNAPSHOT_VERSION` — The version `importCapabilities` accepts.
+- `CapabilitySnapshot` (type) — Every latched refusal in the process, JSON-safe.
+- `EndpointSnapshot` (type) — What one endpoint refused, and under it what each of its models did.
+- `exportCapabilities` — Every refusal this process has latched, as a JSON-safe blob to store and hand back on boot.
+- `importCapabilities` — Latches what a stored snapshot says was refused, on top of whatever this process has learned.
+- `ModelSnapshot` (type) — What one model on an endpoint refused.
+
 ### stream
 
 Reading one streamed turn back into a message.
@@ -149,6 +198,15 @@ Reading one streamed turn back into a message.
 
 - `estimateTokens` — Rough token count.
 
+### tool-calls
+
+Reading what a model meant by a tool call when it did not write one cleanly.
+
+- `parseToolArguments` — A tool call's arguments as the object the tool is handed.
+- `recoverToolCalls` — Tool calls a model wrote into its reply as text, taken out of it and made into calls.
+- `ToolArgumentsError` — Tool arguments that could not be read as an object, with why.
+- `ToolCall` (type) — A tool call as the loop handles it, recovered or streamed.
+
 ### tool-loading
 
 - `carryOver` — The tools to start the next turn with: recently used, newest last, capped.
@@ -161,6 +219,7 @@ Reading one streamed turn back into a message.
 - `loadResult` — What `load_tools` reports back: the descriptions, now that they are worth their tokens.
 - `MAX_CARRIED` — The most a conversation carries between turns.
 - `MAX_PER_LOAD` — The most a single `load_tools` call may pull in.
+- `PRESELECT_SCHEMA` — The shape a preselector's answer is held to where the server takes a schema: `{ tools: [...] }`.
 - `PRESELECT_SYSTEM` — The preselection system prompt at the default cap, for a caller that never changes it.
 - `preselectInput` — The user message for a preselection call: the catalogue, then the request.
 - `preselection` — Resolves a preselection against the catalogue: unknown names dropped, count capped.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "The endpoint-agnostic half of an OpenAI-compatible agent loop: tool-schema compatibility, on-demand tool loading, one-shot side tasks, run events, and a pooled client.",
   "keywords": [
     "openai",