@cubicecho/agent-core 2.24.0 → 2.25.0

package/dist/thinking.d.ts

@@ -17,6 +17,7 @@ export declare const THINK_FENCE: Fence;
 /**
  * The fences nobody writes by accident, and so the ones `streamTurn` reads by default.
  *
+ * @remarks
  * `<think>` opening a reply is never meant as output, and the other two are made of tokens that
  * only a model's template produces: gpt-oss's harmony analysis channel, served raw, and Kimi's.
  */
@@ -27,9 +28,13 @@ export declare const DEFAULT_FENCES: readonly Fence[];
  * and on for a side task, whose answer is too short to be quoting anything.
  */
 export declare const ALL_FENCES: readonly Fence[];
+/** What a `Split` is called when it was inside a fence. */
+export declare const SPLIT_REASONING: 'reasoning';
+/** What a `Split` is called when it was not. */
+export declare const SPLIT_OUTPUT: 'output';
 /** A piece of `content`, said to be one or the other. */
 export interface Split {
-    kind: "reasoning" | "output";
+    kind: typeof SPLIT_REASONING | typeof SPLIT_OUTPUT;
     text: string;
 }
 /** What `FenceSplitter` takes besides its fences. */
@@ -37,6 +42,7 @@ export interface FenceSplitterOptions {
     /**
      * The template already opened the first fence in the prompt, so the reply starts inside it.
      *
+     * @remarks
      * Several chat templates end the prompt with `<think>` rather than leaving the model to write
      * it. Without this the splitter still catches it once `</think>` arrives, and moves what came
      * before into `reasoning`, but a watcher will have been shown it as output by then.
@@ -46,6 +52,7 @@ export interface FenceSplitterOptions {
 /**
  * A state machine over a stream of `content` that routes fenced text to reasoning.
  *
+ * @remarks
  * The reference shape is Vercel's `extractReasoningMiddleware`. A tag can be split across chunks,
  * so the tail of each push that could be the start of one is held until the next push settles
  * it; `finish` releases it. A reply cut off mid-scratchpad ends with the fence still open and its
@@ -62,24 +69,32 @@ export declare class FenceSplitter {
     /** Everything that was inside a fence so far. */
     reasoning: string;
     /**
-     * @param fences The fences to read, `DEFAULT_FENCES` unless given; an empty list passes
-     *   everything through as output.
-     * @param options Whether the reply starts inside the first fence.
+     * @param [fences] - The fences to read; an empty list passes everything through as output.
+     * @param [options] - Whether the reply starts inside the first fence.
      */
     constructor(fences?: readonly Fence[], { startInside }?: FenceSplitterOptions);
     /**
      * Reads one more piece of content, returning what it settled, in order.
      *
-     * @param text The next delta.
+     * @param text - The next delta.
+     * @returns The pieces now settled, neighbours of one kind merged, and added to `output` and
+     * `reasoning` already. Empty where the delta was all markers or all held back as a possible one.
      */
     push(text: string): Split[];
-    /** Releases whatever was held back as a possible tag, now that no more is coming. */
+    /**
+     * Releases whatever was held back as a possible tag, now that no more is coming.
+     *
+     * @returns The held text as one piece — reasoning where the reply ended inside a fence, output
+     * otherwise — or nothing where none was held.
+     */
     finish(): Split[];
 }
 /**
  * What is left of a complete reply once every scratchpad is taken out of it.
  *
- * @param text The whole reply.
- * @param fences The fences to read, every known one unless given.
+ * @param text - The whole reply.
+ * @param [fences] - The fences to read.
+ * @returns The answer alone, untrimmed. A fence left open takes everything after it, and a close
+ * with no open before any other fence takes everything before it.
  */
 export declare function stripThinking(text: string, fences?: readonly Fence[]): string;

package/dist/thinking.js

@@ -8,17 +8,18 @@
  * keep doing it. This is the one table of fences both the stream and the side tasks read.
  */
 /** DeepSeek, Qwen3, QwQ and most distills. */
-export const THINK_FENCE = { open: "<think>", close: "</think>" };
+export const THINK_FENCE = { open: '<think>', close: '</think>' };
 /**
  * The fences nobody writes by accident, and so the ones `streamTurn` reads by default.
  *
+ * @remarks
  * `<think>` opening a reply is never meant as output, and the other two are made of tokens that
  * only a model's template produces: gpt-oss's harmony analysis channel, served raw, and Kimi's.
  */
 export const DEFAULT_FENCES = [
     THINK_FENCE,
-    { open: "<|channel|>analysis<|message|>", close: "<|end|>" },
-    { open: "◁think▷", close: "◁/think▷" },
+    { open: '<|channel|>analysis<|message|>', close: '<|end|>' },
+    { open: '◁think▷', close: '◁/think▷' },
 ];
 /**
  * Every fence known, including the two plain-word ones some fine-tunes and prompt-instructed
@@ -27,25 +28,27 @@ export const DEFAULT_FENCES = [
  */
 export const ALL_FENCES = [
     ...DEFAULT_FENCES,
-    { open: "<thinking>", close: "</thinking>" },
-    { open: "<reasoning>", close: "</reasoning>" },
+    { open: '<thinking>', close: '</thinking>' },
+    { open: '<reasoning>', close: '</reasoning>' },
 ];
 /**
  * Framing that is neither scratchpad nor answer, dropped wherever it turns up outside a fence.
  *
+ * @remarks
  * Only harmony has any: after the analysis channel closes, raw gpt-oss output announces the final
  * channel before the answer and ends with a return token.
  */
 const FRAMING = {
-    "<|channel|>analysis<|message|>": [
-        "<|start|>assistant",
-        "<|channel|>final<|message|>",
-        "<|return|>",
-    ],
+    '<|channel|>analysis<|message|>': ['<|start|>assistant', '<|channel|>final<|message|>', '<|return|>'],
 };
+/** What a `Split` is called when it was inside a fence. */
+export const SPLIT_REASONING = 'reasoning';
+/** What a `Split` is called when it was not. */
+export const SPLIT_OUTPUT = 'output';
 /**
  * A state machine over a stream of `content` that routes fenced text to reasoning.
  *
+ * @remarks
  * The reference shape is Vercel's `extractReasoningMiddleware`. A tag can be split across chunks,
  * so the tail of each push that could be the start of one is held until the next push settles
  * it; `finish` releases it. A reply cut off mid-scratchpad ends with the fence still open and its
@@ -57,86 +60,117 @@ const FRAMING = {
  */
 export class FenceSplitter {
     /** The answer so far, with every fence taken out. */
-    output = "";
+    output = '';
     /** Everything that was inside a fence so far. */
-    reasoning = "";
+    reasoning = '';
     #fences;
     #markers;
     #inside;
     #seenFence;
-    #held = "";
+    #held = '';
     /**
-     * @param fences The fences to read, `DEFAULT_FENCES` unless given; an empty list passes
-     *   everything through as output.
-     * @param options Whether the reply starts inside the first fence.
+     * @param [fences] - The fences to read; an empty list passes everything through as output.
+     * @param [options] - Whether the reply starts inside the first fence.
      */
     constructor(fences = DEFAULT_FENCES, { startInside } = {}) {
         this.#fences = fences;
-        this.#markers = fences.flatMap((fence) => [
-            fence.open,
-            fence.close,
-            ...(FRAMING[fence.open] ?? []),
-        ]);
+        this.#markers = fences.flatMap((fence) => [fence.open, fence.close, ...(FRAMING[fence.open] ?? [])]);
         this.#inside = startInside ? fences[0] : undefined;
         this.#seenFence = this.#inside !== undefined;
     }
     /**
      * Reads one more piece of content, returning what it settled, in order.
      *
-     * @param text The next delta.
+     * @param text - The next delta.
+     * @returns The pieces now settled, neighbours of one kind merged, and added to `output` and
+     * `reasoning` already. Empty where the delta was all markers or all held back as a possible one.
      */
     push(text) {
         const parts = [];
         let rest = this.#held + text;
-        this.#held = "";
+        this.#held = '';
         while (rest) {
             const found = this.#next(rest);
             if (!found) {
                 const keep = this.#partialTail(rest);
-                this.#emit(parts, rest.slice(0, rest.length - keep));
+                this.#emitInto(parts, rest.slice(0, rest.length - keep));
                 this.#held = rest.slice(rest.length - keep);
                 break;
             }
-            this.#emit(parts, rest.slice(0, found.at));
+            this.#emitInto(parts, rest.slice(0, found.at));
             rest = rest.slice(found.at + found.marker.length);
             this.#take(found.marker);
         }
         return parts;
     }
-    /** Releases whatever was held back as a possible tag, now that no more is coming. */
+    /**
+     * Releases whatever was held back as a possible tag, now that no more is coming.
+     *
+     * @returns The held text as one piece — reasoning where the reply ended inside a fence, output
+     * otherwise — or nothing where none was held.
+     */
     finish() {
         const parts = [];
-        this.#emit(parts, this.#held);
-        this.#held = "";
+        this.#emitInto(parts, this.#held);
+        this.#held = '';
         return parts;
     }
-    /** The markers worth looking for: only the close inside a fence, every one outside it. */
+    /**
+     * The markers worth looking for: only the close inside a fence, every one outside it.
+     *
+     * @returns Outside a fence, the splitter's own list of opens, closes and framing — not a copy.
+     */
     #candidates() {
         return this.#inside ? [this.#inside.close] : this.#markers;
     }
-    /** The earliest marker that means something in the current state. */
+    /**
+     * The earliest marker that means something in the current state.
+     *
+     * @param text - What is left of this push to read.
+     * @returns The marker and where in `text` it starts — the longer of two that start at one place —
+     * or `undefined` where none is whole in it.
+     */
     #next(text) {
         let best;
         for (const marker of this.#candidates()) {
             const at = text.indexOf(marker);
-            if (at === -1)
+            if (at === -1) {
                 continue;
-            if (!best || at < best.at || (at === best.at && marker.length > best.marker.length))
+            }
+            const earlier = !best || at < best.at;
+            const longerAtTheSamePlace = best && at === best.at && marker.length > best.marker.length;
+            if (earlier || longerAtTheSamePlace) {
                 best = { at, marker };
+            }
         }
         return best;
     }
-    /** How much of the end of `text` could be the beginning of a marker. */
+    /**
+     * How much of the end of `text` could be the beginning of a marker.
+     *
+     * @param text - Text with no whole marker in it.
+     * @returns The length of the longest such tail over every marker worth looking for, zero where
+     * there is none. Always short of a whole marker.
+     */
     #partialTail(text) {
         let keep = 0;
-        for (const marker of this.#candidates())
-            for (let length = Math.min(marker.length - 1, text.length); length > keep; length--)
+        for (const marker of this.#candidates()) {
+            for (let length = Math.min(marker.length - 1, text.length); length > keep; length--) {
                 if (text.endsWith(marker.slice(0, length))) {
                     keep = length;
                     break;
                 }
+            }
+        }
         return keep;
     }
+    /**
+     * Moves the state past a marker just read: out of a fence, into one, or nowhere.
+     *
+     * @param marker - The marker found. Inside a fence any marker leaves it, since only its close is
+     * looked for there. Outside, an open enters its fence, framing changes nothing, and a close met
+     * before any fence was seen moves all of `output` so far into `reasoning`.
+     */
     #take(marker) {
         if (this.#inside) {
             this.#inside = undefined;
@@ -153,28 +187,42 @@ export class FenceSplitter {
         const closes = this.#fences.some((fence) => fence.close === marker);
         if (closes && !this.#seenFence) {
             this.reasoning += this.output;
-            this.output = "";
+            this.output = '';
         }
-        if (closes)
+        if (closes) {
             this.#seenFence = true;
+        }
     }
-    #emit(parts, text) {
-        if (!text)
+    /**
+     * Files text under the side the state is on: in `output` or `reasoning`, and in the pieces a call
+     * is returning.
+     *
+     * @param parts - The pieces settled so far. Written to — the text joins the last piece where
+     * that is of the same kind, and is pushed as a new one where it is not.
+     * @param text - What to file. Empty files nothing.
+     */
+    #emitInto(parts, text) {
+        if (!text) {
             return;
-        const kind = this.#inside ? "reasoning" : "output";
+        }
+        const kind = this.#inside ? SPLIT_REASONING : SPLIT_OUTPUT;
         this[kind] += text;
         const last = parts.at(-1);
-        if (last?.kind === kind)
+        if (last?.kind === kind) {
             last.text += text;
-        else
+        }
+        else {
             parts.push({ kind, text });
+        }
     }
 }
 /**
  * What is left of a complete reply once every scratchpad is taken out of it.
  *
- * @param text The whole reply.
- * @param fences The fences to read, every known one unless given.
+ * @param text - The whole reply.
+ * @param [fences] - The fences to read.
+ * @returns The answer alone, untrimmed. A fence left open takes everything after it, and a close
+ * with no open before any other fence takes everything before it.
  */
 export function stripThinking(text, fences = ALL_FENCES) {
     const splitter = new FenceSplitter(fences);

package/dist/tokens.d.ts

@@ -1,6 +1,8 @@
+import type OpenAI from 'openai';
 /**
  * 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,172 @@ export declare 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 declare const estimateTokens: (text: string) => number;
+/**
+ * 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 declare const compact: (tokens: number) => string;
+/** What the two token estimates below take besides what they measure. */
+export interface TokenEstimateOptions {
+    /**
+     * The divisor — `charsPerTokenFor` for a model whose reported usage has calibrated it. A value
+     * that is not a number above zero is ignored.
+     *
+     * @defaultValue `CHARS_PER_TOKEN`
+     */
+    charsPerToken?: number;
+}
+/**
+ * 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 declare function messageChars(message: OpenAI.ChatCompletionMessageParam): number;
+/**
+ * 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 declare function toolsChars(tools: OpenAI.ChatCompletionTool[]): number;
+/**
+ * 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 declare function requestChars(body: OpenAI.ChatCompletionCreateParamsStreaming): number;
+/**
+ * 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 declare const requestTokens: (body: OpenAI.ChatCompletionCreateParamsStreaming, { charsPerToken }?: TokenEstimateOptions) => number;
+/**
+ * What a request is made of, by the part of it a consumer can actually do something about.
+ *
+ * @remarks
+ * The question an operator asks is not how big the request is — the total already answers that —
+ * but what is filling the window, and the only useful answer names a lever: a system prompt to
+ * shorten, a tool list to load on demand instead of declaring whole, a transcript to compact,
+ * results to prune. So the cut follows the levers rather than the roles: `toolResults` is exactly
+ * what `pruneToolResults` can shrink, and `history` is everything `planCompaction` folds, the
+ * arguments of the calls in it included.
+ */
+export interface ContextBreakdown {
+    /** Every system and developer message, wherever it sits in the transcript. */
+    system: number;
+    /** The declared tool schemas, which a chat template renders ahead of the system prompt. */
+    tools: number;
+    /** What was said: the user and assistant messages, and the calls the assistant asked for. */
+    history: number;
+    /** What the tools handed back — the `tool` messages, and nothing else. */
+    toolResults: number;
+    /** The four above, summed. */
+    total: number;
+}
+/**
+ * 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 declare function contextChars(body: OpenAI.ChatCompletionCreateParamsStreaming): ContextBreakdown;
+/** What `contextTokens` takes besides the request. */
+export interface ContextBreakdownOptions extends TokenEstimateOptions {
+    /**
+     * The prompt count the endpoint reported for this request, if it has answered. Given one, the
+     * parts are shares of it and the breakdown sums to what was actually charged rather than to an
+     * estimate; left out, they are shares of `requestTokens`.
+     */
+    promptTokens?: number;
+}
+/**
+ * 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 declare function contextTokens(body: OpenAI.ChatCompletionCreateParamsStreaming, { charsPerToken, promptTokens }?: ContextBreakdownOptions): ContextBreakdown;
+/**
+ * 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 declare const messageTokens: (message: OpenAI.ChatCompletionMessageParam, { charsPerToken }?: TokenEstimateOptions) => number;