@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/tokens.js

@@ -1,6 +1,8 @@
+import { FUNCTION_TOOL, PartType, Role } from './wire.js';
 /**
  * The characters one token is taken to be, where nothing has measured it.
  *
+ * @remarks
  * The fallback, not the rule: once a turn has come back with a reported prompt count, `runTurn`
  * divides by what that endpoint's model was measured at instead. See `charsPerTokenFor`.
  */
@@ -10,16 +12,327 @@ export const CHARS_PER_TOKEN = 4;
  * going to be one: a server that will not say how big its window is will not lend us its
  * vocabulary either.
  *
+ * @param text - Prose or serialised JSON — both counted the same way, which is why JSON reads low.
+ * @returns The length over `CHARS_PER_TOKEN`, rounded up: zero for an empty string, and one for
+ * anything shorter than a token.
+ *
+ * @remarks
  * The estimate runs low on tool schemas — JSON packs more tokens into a character than prose
  * does — and that is the side to be wrong on wherever it guards a window, since the cost of
  * guessing high is a run refused that would have worked, and the cost of guessing low is the
  * endpoint's own refusal, which is where we were before the guard existed.
  *
- * Its own module because it is the one number several of these agree on, and the module that
- * owns it should not be one that also does something. It was extracted from `side-task` to
- * break a cycle with `retry`; neither reads it now, but `hooks` does to cap a context block, as
- * does any consumer sizing its own prompt, and a leaf with no imports is the right home for it.
- *
- * @param text Prose or serialised JSON — both counted the same way, which is why JSON reads low.
+ * Its own module because it is the one number several of these agree on. It was extracted from
+ * `side-task` to break a cycle with `retry`; neither reads it now, but `hooks` does to cap a
+ * context block, as does any consumer sizing its own prompt. Everything else that sizes a request
+ * is below it — a message's characters, a tool block's, a request's, and the breakdown of a
+ * window — so the module imports nothing but the SDK's types and anything may read it.
  */
 export const estimateTokens = (text) => Math.ceil(text.length / CHARS_PER_TOKEN);
+/** Where `compact` starts counting in thousands. */
+const THOUSAND = 1000;
+/**
+ * A token count as a message shows it: 1234 → "1.2k".
+ *
+ * @param tokens - The count to render.
+ * @returns The count in thousands to one decimal place with a `k`, or the number as it is below a
+ * thousand.
+ *
+ * @remarks
+ * The numbers in an overflow message are large and nobody reads the units digit.
+ */
+export const compact = (tokens) => (tokens >= THOUSAND ? `${(tokens / THOUSAND).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.
+ *
+ * @remarks
+ * 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.
+ *
+ * @param charsPerToken - What the caller gave. Absent, zero, negative or `NaN` is nothing usable.
+ * @returns `charsPerToken` when it is above zero, otherwise `CHARS_PER_TOKEN`.
+ */
+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.
+ * @returns The characters of its role, its content — a string, or the text and refusal parts of a
+ * list — and its name, call id, reasoning and tool calls, plus a constant for each key and part
+ * that carries them. An image or audio part adds nothing.
+ */
+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 === PartType.Text) {
+                chars += TEXT_PART + part.text.length;
+            }
+            else if (part.type === PartType.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_TOOL) {
+                chars += call.function.name.length + call.function.arguments.length;
+            }
+        }
+    }
+    return chars;
+}
+/**
+ * The tools half, cached against the array.
+ *
+ * @remarks
+ * 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.
+ * @returns The length of the array serialised as JSON, as it was the first time this array was
+ * asked about — a change made to it since is not seen.
+ */
+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.
+ *
+ * @param body - The request as it was sent, tools included.
+ * @returns The sum of `messageChars` over the messages. The tools are not in it, whether or not
+ * the body carries them; `toolsChars` counts those.
+ *
+ * @remarks
+ * 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.
+ */
+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.
+ *
+ * @param body - The request as it will be sent, tools included.
+ * @param [options] - The divisor, `CHARS_PER_TOKEN` when none is given.
+ * @returns Whole tokens: the messages' and the tools', each rounded up on its own and added.
+ *
+ * @remarks
+ * 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.
+ */
+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.
+ *
+ * @param body - The request as it will be sent, tools included.
+ * @returns A new breakdown in characters. A `developer` message counts as `system`, and anything
+ * that is neither that nor a `tool` message as `history`.
+ *
+ * @remarks
+ * 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.
+ */
+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 === Role.System || message.role === Role.Developer) {
+            out.system += chars;
+        }
+        else if (message.role === 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.
+ *
+ * @param chars - What each part measured, in characters. Not written to.
+ * @param over - The parts to share between. One left out stays zero in the result.
+ * @param total - What to share out, in tokens.
+ * @returns A new breakdown whose `total` is `total` as given. Every part is zero where the parts
+ * measured nothing or `total` is not above zero.
+ */
+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.
+ *
+ * @param body - The request as it will be sent, tools included.
+ * @param [options] - The divisor, and the reported prompt count when there is one.
+ * @returns A new breakdown in tokens. Its `total` is the reported count when one above zero was
+ * given, and `requestTokens` of the same body otherwise.
+ *
+ * @remarks
+ * 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.
+ */
+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.
+ *
+ * @param message - The message as it will be sent.
+ * @param [options] - The divisor, `CHARS_PER_TOKEN` when none is given.
+ * @returns `messageChars` over the divisor, rounded up per message, where `requestTokens` rounds
+ * once over them all.
+ *
+ * @remarks
+ * 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.
+ */
+export const messageTokens = (message, { charsPerToken } = {}) => Math.ceil(messageChars(message) / divisor(charsPerToken));

package/dist/tool-calls.d.ts

@@ -1,4 +1,4 @@
-import type OpenAI from "openai";
+import type OpenAI from 'openai';
 /**
  * Reading what a model meant by a tool call when it did not write one cleanly.
  *
@@ -8,46 +8,60 @@ import type OpenAI from "openai";
  * but as text, in the model's own template, because the server's tool-call parser was written for
  * a different one. Both were being handled in every consumer, differently, or not at all.
  */
+/** How much of a call's unreadable arguments an error quotes back. */
+export declare const ARGUMENT_PREVIEW_CHARS = 200;
+/** The `ToolArgumentsError` kind for a call cut off at the reply ceiling. */
+export declare const ARGUMENTS_TRUNCATED: 'truncated';
+/** The `ToolArgumentsError` kind for a call the model wrote wrongly. */
+export declare const ARGUMENTS_MALFORMED: 'malformed';
 /** A tool call as the loop handles it, recovered or streamed. */
 export type ToolCall = OpenAI.ChatCompletionMessageFunctionToolCall;
 /**
  * Tool arguments that could not be read as an object, with why.
  *
+ * @remarks
  * `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 declare class ToolArgumentsError extends Error {
+    readonly name = "ToolArgumentsError";
     /** Whether the model ran out of room or wrote something unreadable. */
-    readonly kind: "truncated" | "malformed";
+    readonly kind: typeof ARGUMENTS_TRUNCATED | typeof ARGUMENTS_MALFORMED;
     /**
-     * @param kind Why the arguments could not be read.
-     * @param message What the model is handed back as the tool's result.
+     * @param kind - Why the arguments could not be read.
+     * @param message - What the model is handed back as the tool's result.
      */
-    constructor(kind: "truncated" | "malformed", message: string);
+    constructor(kind: typeof ARGUMENTS_TRUNCATED | typeof ARGUMENTS_MALFORMED, message: string);
 }
 /**
  * JSON as it was written, then repaired, then undefined. A string holding JSON is opened once.
  *
+ * @param text - What a model wrote where JSON was asked for, with no prose around it.
+ * @returns The value — `null` for a JSON `null` — or `undefined` where neither the text nor its
+ * repair parses. A string holding an object or array that does not parse stays the string.
+ *
+ * @remarks
  * Read as written first, so the repair can only ever add to what parses: nothing valid is
  * reinterpreted on its way through.
- *
- * @param text What a model wrote where JSON was asked for, with no prose around it.
  */
 export declare function looseJson(text: string): unknown;
 /**
  * A tool call's arguments as the object the tool is handed. Empty is no arguments.
  *
+ * @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.
+ * @returns `raw` itself where it was already an object, otherwise what its text parsed to, and a
+ * new empty object for no arguments.
+ *
+ * @remarks
  * 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 declare function parseToolArguments(raw: unknown, { finishReason }?: {
     finishReason?: string | null;
@@ -55,6 +69,12 @@ export declare function parseToolArguments(raw: unknown, { finishReason }?: {
 /**
  * Tool calls a model wrote into its reply as text, taken out of it and made into calls.
  *
+ * @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.
+ *
+ * @remarks
  * 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]`
@@ -62,11 +82,6 @@ export declare function parseToolArguments(raw: unknown, { finishReason }?: {
  * 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 declare function recoverToolCalls(content: string, { names }?: {
     names?: Iterable<string>;
@@ -74,3 +89,53 @@ export declare function recoverToolCalls(content: string, { names }?: {
     content: string;
     toolCalls: ToolCall[];
 };
+/**
+ * One call the model made, as `dispatch` and `onToolCall` are handed it.
+ *
+ * @remarks
+ * A `call_tool` arrives as the tool it names — that tool's name and arguments, under the
+ * `call_tool`'s id — so a dispatcher is the same in every discovery mode.
+ */
+export interface ToolCallRequest {
+    id: string;
+    name: string;
+    /**
+     * Parsed by `parseToolArguments`, repairs and all. Empty for a call whose arguments could not be
+     * read, which only `onToolCall` is ever handed.
+     */
+    args: Record<string, unknown>;
+    /**
+     * The arguments as the model wrote them, before any repair. Through `call_tool`, the inner
+     * arguments as JSON text.
+     */
+    raw: string;
+}
+/** What one tool call did, in the order the model asked. */
+export interface ToolCallOutcome {
+    /**
+     * The id the model's reply gave the call, which is what tells two calls to one tool apart.
+     * Distinct within a step — `streamTurn` mints one where the server sent none or repeated one —
+     * but nothing stops a server using the same id again in a later step. `runAgentLoop` always
+     * sets it; optional so an outcome built before it existed still compiles.
+     */
+    id?: string;
+    /** The tool that was called. For a `call_tool`, the tool it named. */
+    name: string;
+    /** False when the arguments did not parse, the tool threw, or `load_tools` loaded nothing. */
+    ok: boolean;
+}
+/**
+ * One call's whole answer, as `onToolResult` is handed it.
+ *
+ * @remarks
+ * The `tool-result` event carries the same answer cut by `preview`, which is right for a readout
+ * and wrong for a host that renders or stores the result: this is the text the model reads.
+ */
+export interface ToolCallResult extends ToolCallOutcome {
+    id: string;
+    /**
+     * What went into the transcript for this call, uncut: what the tool returned, what it threw, the
+     * `load_tools` answer, or why the arguments could not be read.
+     */
+    content: string;
+}