@cubicecho/agent-core 2.7.0 → 2.8.1

package/README.md

@@ -22,8 +22,9 @@ only, Node >=22.
 | --- | --- |
 | `schema-compat` | Makes an MCP tool schema something a strict or grammar-constrained server will accept. `sanitizeTools`, `relaxTools`, `isGrammarError`. |
 | `tool-loading` | On-demand tool discovery: a name-only catalogue plus a `load_tools` meta-tool, so a run pays for the schemas it asks for instead of all of them. |
-| `stream` | Reads one streamed turn back into a message: token callbacks, tool-call reassembly, and the idle watchdog that turns a silent endpoint into `EndpointSilent`. |
+| `stream` | Reads one streamed turn back into a message: token callbacks, tool-call reassembly, fenced reasoning taken out of the answer, and the idle watchdog that turns a silent endpoint into `EndpointSilent`. |
 | `capabilities` | What an endpoint turned out not to support — and, under it, what one model on that endpoint did not — plus the loop that answers either when it says so. `capabilitiesFor`, `modelCapabilitiesFor`, `negotiate`. |
+| `thinking` | Tells a scratchpad fenced inside `content` from the answer: `FenceSplitter` for a stream, `stripThinking` for a whole reply, and the fence tables both read. |
 | `side-task` | One-shot calls that support a run without being one — small prompt, short answer, no tools, never worth failing the run over. `askJson` holds the answer to a schema where the server can. |
 | `hooks` | The host's side of lifecycle hooks: `gather` before a request and `notify` after, the shared context budget, `withContext` to put what they add on the turn's question, `untrusted` to fence text nobody vouched for, and `turnMessages` to hand them a transcript. Running a hook is a runner the caller passes. |
 | `events` | The in-memory bus a watcher reads while a run happens: `emit`, `watch`, `history`, `fold`. A watcher's backlog is capped and reports its own gaps. |
@@ -80,11 +81,28 @@ for: a router is free to send two keys to two different backends, and then what
 refused is not a fact about the other. Absent and empty read the same, so a local server with no
 key is one entry however its caller spells it.
 
-`Turn` is `content`, `toolCalls`, `usage` and `finishReason`. The last is worth reading: a turn
-cut off at the token ceiling comes back looking exactly like a finished one, with truncated prose
-or — the case that bites — a tool call whose `arguments` stop mid-JSON, so the caller meets a
-parse failure with nothing to attribute it to. `finishReason` is `"length"` there, `""` where the
-endpoint never said.
+`Turn` is `content`, `toolCalls`, `usage`, `finishReason` and `reasoning`. The fourth is worth
+reading: a turn cut off at the token ceiling comes back looking exactly like a finished one, with
+truncated prose or — the case that bites — a tool call whose `arguments` stop mid-JSON, so the
+caller meets a parse failure with nothing to attribute it to. `finishReason` is `"length"` there,
+`""` where the endpoint never said.
+
+`reasoning` is the scratchpad `onThinking` was told, kept because two common families want it
+back. gpt-oss and DeepSeek in thinking mode read the analysis behind a tool call off the assistant
+message on the next request: store it as `reasoning_content` on that message while it ends in a
+tool call, and drop it once the model has answered. Any other model is better off without it,
+since it is context paid for on every turn. `requestTokens` counts it either way.
+
+A server without a reasoning parser leaves the scratchpad in `content`, fenced, and then it is shown
+as output, stored and sent back. `streamTurn` routes text inside a fence to `onThinking` and
+`reasoning` instead, holding back the tail of a chunk that could be half a tag. `DEFAULT_FENCES` is
+`<think>`, gpt-oss harmony's analysis channel served raw, and Kimi's `◁think▷`, none of which a
+model writes as an answer; `ALL_FENCES` adds `<thinking>` and `<reasoning>`, which it can be
+quoting, and is what the side tasks use. Pass `fences: []` to read `content` as all answer. A reply
+cut off inside a fence has an empty `content`, not the deliberation promoted to one. A template that
+opens `<think>` in the prompt leaves only the closing tag, so everything before it is moved to
+`reasoning` when it arrives; `startInReasoning: true` says so up front, so `onOutput` is never told
+it at all.
 
 ## What the model refuses, rather than the server
 
@@ -289,7 +307,10 @@ Found calls are run as `call_recovered_0` onward, the text is what is left, `onT
 result see the turn that way, and a notice says so, since the real fix is the server's parser.
 
 With `toolDiscovery: "ondemand"` and a catalogue, the request declares `load_tools` and what has
-been loaded, and the catalogue rides on the system prompt marked with what is. A model that calls
+been loaded, appended in the order it was loaded, and the catalogue rides on the system prompt
+unmarked, the same text on every step. Marking loads there rewrote the head of the prompt and lost
+the prompt cache for the whole transcript on each one; a model that loads a tool twice is told in
+the `load_tools` result that it already has it. A model that calls
 a catalogued tool without loading it first is right about what it wants, and gets it loaded and
 run. A preselection shapes the first step alone: those tools, no catalogue, no `load_tools` —
 a model with the menu still in front of it shops, reloading what it has or picking a sibling —

package/dist/agent-loop.d.ts

@@ -192,9 +192,10 @@ export interface AgentLoopResult {
  * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
  *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
- * prompt and marks what is loaded, a catalogued tool called without being loaded is loaded and
- * run rather than refused, and a preselection shapes the first step. A turn cut off at
- * `maxTokens` is said so as a notice, because it otherwise reads exactly like a finished one.
+ * prompt unchanged from step to step, loaded tools are appended to the tool array in load order,
+ * a catalogued tool called without being loaded is loaded and run rather than refused, and a
+ * preselection shapes the first step. A turn cut off at `maxTokens` is said so as a notice,
+ * because it otherwise reads exactly like a finished one.
  *
  * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.

package/dist/agent-loop.js

@@ -6,7 +6,7 @@ import { runTurn } from "./run-turn.js";
 import { relaxTools, sanitizeTools } from "./schema-compat.js";
 import { askJson, tryAsk } from "./side-task.js";
 import { parseToolArguments, recoverToolCalls } from "./tool-calls.js";
-import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_PER_LOAD, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+import { catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_PER_LOAD, PRESELECT_SCHEMA, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
 /**
  * The loop above a turn: send, run the tools the model asked for, send again, until it stops
  * asking.
@@ -130,9 +130,10 @@ const accumulate = (total, turn) => {
  * whatever `runTurn` throws — `ContextOverflow` among them, however it was found out.
  *
  * On-demand loading is handled here, `load_tools` and all: the catalogue rides on the system
- * prompt and marks what is loaded, a catalogued tool called without being loaded is loaded and
- * run rather than refused, and a preselection shapes the first step. A turn cut off at
- * `maxTokens` is said so as a notice, because it otherwise reads exactly like a finished one.
+ * prompt unchanged from step to step, loaded tools are appended to the tool array in load order,
+ * a catalogued tool called without being loaded is loaded and run rather than refused, and a
+ * preselection shapes the first step. A turn cut off at `maxTokens` is said so as a notice,
+ * because it otherwise reads exactly like a finished one.
  *
  * @param options The config, transcript, tools and dispatcher, plus the optional hooks, events
  * and cancellation. See `AgentLoopOptions`.
@@ -150,7 +151,15 @@ export async function runAgentLoop(options) {
     for (const name of preselected)
         loaded.add(name);
     const used = new Set();
-    const byName = (names) => tools.filter((tool) => tool.type === "function" && names.has(tool.function.name));
+    const definitions = new Map();
+    for (const tool of tools) {
+        if (tool.type === "function" && !definitions.has(tool.function.name)) {
+            definitions.set(tool.function.name, tool);
+        }
+    }
+    // In the order the names are given, not the order of `tools`: `loaded` is a set, which iterates
+    // in the order things were added, so a load appends and never reshuffles what went before.
+    const byName = (names) => [...names].flatMap((name) => definitions.get(name) ?? []);
     let messages = [...options.messages];
     // Held by reference rather than by index, so a `beforeStep` that folds the head into a summary
     // moves the question without losing it — and one that summarises the question away takes the
@@ -176,9 +185,12 @@ export async function runAgentLoop(options) {
         const declared = routed
             ? byName(new Set(preselected))
             : onDemand
-                ? [LOAD_TOOLS_DEFINITION, ...byName(loaded)]
+                ? loadedTools([LOAD_TOOLS_DEFINITION], byName(loaded))
                 : tools;
-        const prompt = onDemand && !routed ? `${system}\n\n${catalogPrompt(catalog, loaded)}`.trim() : system;
+        // Unmarked, so the system prompt is the same text on every step and a load does not throw
+        // away the cache for the whole transcript. What is loaded is said in `declared` and in the
+        // `load_tools` result instead. The preselected first step is the one exception, by design.
+        const prompt = onDemand && !routed ? `${system}\n\n${catalogPrompt(catalog)}`.trim() : system;
         const request = [
             ...(prompt ? [{ role: "system", content: prompt }] : []),
             ...withContext(messages, question ? messages.indexOf(question) : -1, gathered.context, hooks?.preface),
@@ -293,9 +305,9 @@ export async function runAgentLoop(options) {
                     throw unreadable;
                 if (onDemand && name === LOAD_TOOLS) {
                     const resolved = expandNames(requestedNames(args), catalog);
+                    content = loadResult(resolved, catalog, loaded);
                     for (const hit of resolved.matched)
                         loaded.add(hit);
-                    content = loadResult(resolved, catalog);
                     ok = resolved.matched.length > 0;
                 }
                 else {

package/dist/index.d.ts

@@ -25,6 +25,7 @@ export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.ts";
 export { type AskJsonOptions, ask, askJson, clean, listLines, parseJson, resetHints, type SideTaskOptions, tryAsk, } from "./side-task.ts";
 export { CAPABILITY_SNAPSHOT_VERSION, type CapabilitySnapshot, type EndpointSnapshot, exportCapabilities, importCapabilities, type ModelSnapshot, } from "./snapshot.ts";
 export { type Produced, type StreamTurnOptions, streamTurn, type Turn, type TurnUsage, } from "./stream.ts";
+export { ALL_FENCES, DEFAULT_FENCES, type Fence, FenceSplitter, type FenceSplitterOptions, type Split, stripThinking, THINK_FENCE, } from "./thinking.ts";
 export { estimateTokens } from "./tokens.ts";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, type ToolCall, } from "./tool-calls.ts";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.ts";

package/dist/index.js

@@ -23,6 +23,7 @@ export { isGrammarError, relaxTools, sanitizeTools } from "./schema-compat.js";
 export { ask, askJson, clean, listLines, parseJson, resetHints, tryAsk, } from "./side-task.js";
 export { CAPABILITY_SNAPSHOT_VERSION, exportCapabilities, importCapabilities, } from "./snapshot.js";
 export { streamTurn, } from "./stream.js";
+export { ALL_FENCES, DEFAULT_FENCES, FenceSplitter, stripThinking, THINK_FENCE, } from "./thinking.js";
 export { estimateTokens } from "./tokens.js";
 export { parseToolArguments, recoverToolCalls, ToolArgumentsError, } from "./tool-calls.js";
-export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";
+export { carryOver, catalogList, catalogPrompt, expandNames, inCatalog, LOAD_TOOLS, LOAD_TOOLS_DEFINITION, loadedTools, loadResult, MAX_CARRIED, MAX_PER_LOAD, PRESELECT_SCHEMA, PRESELECT_SYSTEM, preselectInput, preselection, preselectSystem, requestedNames, } from "./tool-loading.js";

package/dist/retry.js

@@ -53,6 +53,16 @@ const TOOL_CALLS_KEY = 15;
 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 behind `estimateTokens`, applied here to a character count rather than a string. */
 const CHARS_PER_TOKEN = 4;
 /** How many characters one message is worth: its keys, and its content in whichever shape. */
@@ -76,6 +86,11 @@ function messageChars(message) {
         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) {

package/dist/side-task.js

@@ -4,6 +4,7 @@ import { endpointId, getClient } from "./client.js";
 import { errorMessage } from "./errors.js";
 import { isTransient } from "./retry.js";
 import { relaxTools, sanitizeTools } from "./schema-compat.js";
+import { stripThinking } from "./thinking.js";
 /**
  * One-shot calls that support a run without being one: picking tools, naming a session,
  * summarising a transcript, proposing follow-ups. They share a shape — small prompt, short
@@ -64,23 +65,6 @@ function rejectedTheRequest(error) {
         return false;
     return error.status === 400 || error.status === 422;
 }
-/**
- * Reasoning models that ignore the hints still fence their scratchpad; drop it.
- *
- * Including the fence that never closes. A side task answers under a small `max_tokens`, so a
- * model that spends it deliberating is cut off mid-scratchpad and the closing tag never
- * arrives — and the whole deliberation was then returned to the caller as the answer.
- */
-const stripThinking = (text) => text
-    .replace(/<think>[\s\S]*?<\/think>/gi, "")
-    .replace(/<think>[\s\S]*$/i, "")
-    // And the fence that never opens. Several chat templates put the opening tag at the end of
-    // the prompt rather than leaving the model to write it, so what comes back is deliberation
-    // first and only the closing tag to mark where it stops. Neither pattern above matches that,
-    // and the whole scratchpad went to the caller as the answer — a session title, a tool
-    // preselection, a suggestion list. Every real `<think>` is gone by this point, so a `</think>`
-    // still here opened in the prompt; the first one is taken, which keeps the most text.
-    .replace(/^[\s\S]*?<\/think>/i, "");
 /**
  * Runs a side task and returns the reply text, thinking stripped. Throws like any request.
  *
@@ -159,6 +143,9 @@ async function complete(config, model, system, user, { maxTokens = 512, temperat
             modelCapabilitiesFor(supports, model).reasoningEffort = false;
     }
     const message = response.choices[0]?.message;
+    // Reasoning models that ignore the hints still fence their scratchpad. A side task answers
+    // under a small ceiling, so the fence often never closes, and a template that opened it in
+    // the prompt leaves only the close; either way the deliberation used to come back as the answer.
     const answer = stripThinking(message?.content ?? "").trim();
     // Nothing but scratchpad. Some servers put the deliberation in its own field and leave the
     // content genuinely empty, in which case there is no answer to find anywhere else.

package/dist/stream.d.ts

@@ -1,4 +1,5 @@
 import type OpenAI from "openai";
+import { type Fence } from "./thinking.ts";
 /**
  * Reading one streamed turn back into a message.
  *
@@ -46,6 +47,17 @@ export interface Turn {
      * handed over rather than raised.
      */
     finishReason: string;
+    /**
+     * The model's scratchpad, as `onThinking` was told it, `""` where it deliberated in silence or
+     * not at all.
+     *
+     * Kept because some models want it back. gpt-oss and DeepSeek in thinking mode read the
+     * analysis behind a tool call off the assistant message on the next request, so a caller
+     * talking to one stores it as `reasoning_content` on that message for as long as the message
+     * ends in a tool call, and drops it once the model has given a final answer. A model that
+     * does not ask for it is better off without it: it is context, paid for on every turn.
+     */
+    reasoning: string;
 }
 /**
  * Whether the model has said anything a second attempt would say twice.
@@ -84,7 +96,21 @@ export interface StreamTurnOptions {
     firstChunkMs?: number;
     /** Set by the first chunk that carries anything, so a failed call knows if it can be retried. */
     produced?: Produced;
-    /** The model's scratchpad, as it arrives. */
+    /**
+     * The fences that mark a scratchpad written into `content`, `DEFAULT_FENCES` unless given.
+     *
+     * Text inside one goes to `onThinking` and `reasoning` rather than `onOutput` and `content`.
+     * `ALL_FENCES` adds `<thinking>` and `<reasoning>`, which a model can also be quoting; an
+     * empty list reads `content` as all answer.
+     */
+    fences?: readonly Fence[];
+    /**
+     * The chat template opened the first fence in the prompt, so the reply starts inside it.
+     * Without this the scratchpad is still moved out of `content` once the closing tag arrives,
+     * but `onOutput` will have been told it first.
+     */
+    startInReasoning?: boolean;
+    /** The model's scratchpad, as it arrives, from its own field or from a fence in `content`. */
     onThinking?: (delta: string) => void;
     /** The model's answer, as it arrives. */
     onOutput?: (delta: string) => void;
@@ -105,4 +131,4 @@ export interface StreamTurnOptions {
  * @param body The request, which must set `stream: true`.
  * @param options Cancellation, the idle watchdog, and the token callbacks.
  */
-export declare function streamTurn(client: OpenAI, body: OpenAI.ChatCompletionCreateParamsStreaming, { signal, idleMs, firstChunkMs, produced, onThinking, onOutput }?: StreamTurnOptions): Promise<Turn>;
+export declare function streamTurn(client: OpenAI, body: OpenAI.ChatCompletionCreateParamsStreaming, { signal, idleMs, firstChunkMs, produced, fences, startInReasoning, onThinking, onOutput, }?: StreamTurnOptions): Promise<Turn>;

package/dist/stream.js

@@ -1,4 +1,5 @@
 import { EndpointSilent } from "./retry.js";
+import { DEFAULT_FENCES, FenceSplitter } from "./thinking.js";
 /** The largest delay a timer takes, which is as close to none as the SDK's timeout option goes. */
 const NO_SDK_TIMEOUT = 2 ** 31 - 1;
 /**
@@ -17,7 +18,7 @@ const NO_SDK_TIMEOUT = 2 ** 31 - 1;
  * @param body The request, which must set `stream: true`.
  * @param options Cancellation, the idle watchdog, and the token callbacks.
  */
-export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, produced, onThinking, onOutput } = {}) {
+export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, produced, fences = DEFAULT_FENCES, startInReasoning, onThinking, onOutput, } = {}) {
     // Silence, not duration: the timer is rearmed on every chunk, so a model that is still
     // talking is never cut off however long it takes, and one that has stopped talking does not
     // hang the run until someone notices. A request that never answers at all is the same case
@@ -65,8 +66,17 @@ export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, p
             signal: linked,
             ...(watched ? { timeout: NO_SDK_TIMEOUT } : {}),
         });
-        const content = [];
-        const calls = new Map();
+        // The field's reasoning here, the fenced kind in the splitter, which can still move text
+        // already read as answer into reasoning when a closing tag turns up with no opening one.
+        const reasoning = [];
+        const splitter = new FenceSplitter(fences, { startInside: startInReasoning });
+        const report = (parts) => {
+            for (const part of parts)
+                (part.kind === "reasoning" ? onThinking : onOutput)?.(part.text);
+        };
+        // In arrival order, sorted by index at the end; a call from a server that sent none keeps
+        // its place in the order they arrived.
+        const calls = [];
         const usage = { prompt: 0, completion: 0, total: 0, cached: 0 };
         let finishReason = "";
         for await (const chunk of stream) {
@@ -110,42 +120,82 @@ export async function streamTurn(client, body, { signal, idleMs, firstChunkMs, p
                 rearm(true);
             if (produced && carried)
                 produced.any = true;
-            if (thinking)
+            if (thinking) {
+                reasoning.push(thinking);
                 onThinking?.(thinking);
-            if (delta.content) {
-                content.push(delta.content);
-                onOutput?.(delta.content);
             }
+            if (delta.content)
+                report(splitter.push(delta.content));
             // Tool calls arrive in pieces, keyed by position: the id in one chunk, the name in
             // another, the arguments spread across the next several.
             for (const part of delta.tool_calls ?? []) {
-                const call = calls.get(part.index) ?? { id: "", name: "", arguments: "" };
+                const call = fragmentOf(part);
                 if (part.id)
                     call.id = part.id;
                 if (part.function?.name)
                     call.name += part.function.name;
                 if (part.function?.arguments)
                     call.arguments += part.function.arguments;
-                calls.set(part.index, call);
             }
         }
+        /**
+         * The call a fragment belongs to.
+         *
+         * By `index` where the server sent a number, which the SDK types as required and servers have
+         * nonetheless left out: keyed on `undefined`, every call joined into one whose name and
+         * arguments were all of theirs run together. Without one, by `id`; failing that, a fragment
+         * naming a function opens a call and a bare run of arguments continues the latest. A server
+         * that sends whole calls one per chunk at index `0` makes the same mistake the other way, so
+         * a different id, or a name after arguments have begun, opens a new call under that index.
+         */
+        function fragmentOf(part) {
+            const index = typeof part.index === "number" ? part.index : undefined;
+            const name = part.function?.name;
+            const known = index !== undefined
+                ? calls.findLast((call) => call.index === index)
+                : part.id
+                    ? calls.find((call) => call.id === part.id)
+                    : name
+                        ? undefined
+                        : calls.at(-1);
+            const another = known && ((part.id && known.id && part.id !== known.id) || (name && known.arguments));
+            if (known && !another)
+                return known;
+            const call = { index, id: "", name: "", arguments: "" };
+            calls.push(call);
+            return call;
+        }
         // An aborted stream ends its iteration rather than throwing, so without this a turn cut off
         // halfway — by the watchdog or by someone stopping the run — comes back looking like a
         // complete one, and a truncated answer is recorded as the output. Nothing about the API
         // says you have to know this.
         linked.throwIfAborted();
+        // What was held back as a possible tag. A reply that ended inside a fence stays reasoning:
+        // cut off at the ceiling mid-scratchpad, it has no answer, and promoting the deliberation to
+        // one is how a truncated turn gets recorded as output.
+        report(splitter.finish());
+        const minted = new Set();
         return {
-            content: content.join(""),
-            toolCalls: [...calls.entries()]
-                .sort(([a], [b]) => a - b)
-                .map(([index, call]) => ({
-                // A server that streams a call without an id still needs one for the result to answer.
-                id: call.id || `call_${index}`,
-                type: "function",
-                function: { name: call.name, arguments: call.arguments },
-            })),
+            content: splitter.output,
+            toolCalls: calls
+                .map((call, order) => ({ call, order }))
+                .sort((a, b) => (a.call.index ?? a.order) - (b.call.index ?? b.order) || a.order - b.order)
+                .map(({ call }, position) => {
+                // A server that streams a call without an id still needs one for the result to answer,
+                // and two calls it put under one index must not be answered as one.
+                let id = call.id || `call_${call.index ?? position}`;
+                if (minted.has(id))
+                    id = `call_${position}_${minted.size}`;
+                minted.add(id);
+                return {
+                    id,
+                    type: "function",
+                    function: { name: call.name, arguments: call.arguments },
+                };
+            }),
             usage,
             finishReason,
+            reasoning: reasoning.join("") + splitter.reasoning,
         };
     }
 }

package/dist/thinking.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Telling a model's scratchpad from its answer when both arrive in `content`.
+ *
+ * A server with a reasoning parser puts the deliberation in a field of its own. One without — a
+ * llama.cpp started with `--reasoning-format none`, a model whose template has no parser, most
+ * distills on any server — leaves it fenced inline, and then it is shown as output, stored in
+ * the transcript and sent back on the next turn, where it costs context and teaches the model to
+ * keep doing it. This is the one table of fences both the stream and the side tasks read.
+ */
+/** One way a model marks off its scratchpad inside `content`. */
+export interface Fence {
+    open: string;
+    close: string;
+}
+/** DeepSeek, Qwen3, QwQ and most distills. */
+export declare const THINK_FENCE: Fence;
+/**
+ * The fences nobody writes by accident, and so the ones `streamTurn` reads by default.
+ *
+ * `<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 declare const DEFAULT_FENCES: readonly Fence[];
+/**
+ * Every fence known, including the two plain-word ones some fine-tunes and prompt-instructed
+ * models use. Those can also be text the model is quoting, so they are opt-in for a stream,
+ * and on for a side task, whose answer is too short to be quoting anything.
+ */
+export declare const ALL_FENCES: readonly Fence[];
+/** A piece of `content`, said to be one or the other. */
+export interface Split {
+    kind: "reasoning" | "output";
+    text: string;
+}
+/** What `FenceSplitter` takes besides its fences. */
+export interface FenceSplitterOptions {
+    /**
+     * The template already opened the first fence in the prompt, so the reply starts inside it.
+     *
+     * 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.
+     */
+    startInside?: boolean;
+}
+/**
+ * A state machine over a stream of `content` that routes fenced text to reasoning.
+ *
+ * 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
+ * text still reasoning, rather than promoted to the answer.
+ *
+ * A closing tag with no opening one is the template having opened it in the prompt. When no
+ * fence has been seen yet, everything before it becomes reasoning retroactively in `output` and
+ * `reasoning`, though what was already handed out as output cannot be taken back.
+ */
+export declare class FenceSplitter {
+    #private;
+    /** The answer so far, with every fence taken out. */
+    output: string;
+    /** 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.
+     */
+    constructor(fences?: readonly Fence[], { startInside }?: FenceSplitterOptions);
+    /**
+     * Reads one more piece of content, returning what it settled, in order.
+     *
+     * @param text The next delta.
+     */
+    push(text: string): Split[];
+    /** Releases whatever was held back as a possible tag, now that no more is coming. */
+    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.
+ */
+export declare function stripThinking(text: string, fences?: readonly Fence[]): string;

package/dist/thinking.js

@@ -0,0 +1,182 @@
+/**
+ * Telling a model's scratchpad from its answer when both arrive in `content`.
+ *
+ * A server with a reasoning parser puts the deliberation in a field of its own. One without — a
+ * llama.cpp started with `--reasoning-format none`, a model whose template has no parser, most
+ * distills on any server — leaves it fenced inline, and then it is shown as output, stored in
+ * the transcript and sent back on the next turn, where it costs context and teaches the model to
+ * 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>" };
+/**
+ * The fences nobody writes by accident, and so the ones `streamTurn` reads by default.
+ *
+ * `<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▷" },
+];
+/**
+ * Every fence known, including the two plain-word ones some fine-tunes and prompt-instructed
+ * models use. Those can also be text the model is quoting, so they are opt-in for a stream,
+ * and on for a side task, whose answer is too short to be quoting anything.
+ */
+export const ALL_FENCES = [
+    ...DEFAULT_FENCES,
+    { open: "<thinking>", close: "</thinking>" },
+    { open: "<reasoning>", close: "</reasoning>" },
+];
+/**
+ * Framing that is neither scratchpad nor answer, dropped wherever it turns up outside a fence.
+ *
+ * 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|>",
+    ],
+};
+/**
+ * A state machine over a stream of `content` that routes fenced text to reasoning.
+ *
+ * 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
+ * text still reasoning, rather than promoted to the answer.
+ *
+ * A closing tag with no opening one is the template having opened it in the prompt. When no
+ * fence has been seen yet, everything before it becomes reasoning retroactively in `output` and
+ * `reasoning`, though what was already handed out as output cannot be taken back.
+ */
+export class FenceSplitter {
+    /** The answer so far, with every fence taken out. */
+    output = "";
+    /** Everything that was inside a fence so far. */
+    reasoning = "";
+    #fences;
+    #markers;
+    #inside;
+    #seenFence;
+    #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.
+     */
+    constructor(fences = DEFAULT_FENCES, { startInside } = {}) {
+        this.#fences = fences;
+        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.
+     */
+    push(text) {
+        const parts = [];
+        let rest = this.#held + text;
+        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.#held = rest.slice(rest.length - keep);
+                break;
+            }
+            this.#emit(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. */
+    finish() {
+        const parts = [];
+        this.#emit(parts, this.#held);
+        this.#held = "";
+        return parts;
+    }
+    /** The earliest marker that means something in the current state. */
+    #next(text) {
+        const candidates = this.#inside ? [this.#inside.close] : this.#markers;
+        let best;
+        for (const marker of candidates) {
+            const at = text.indexOf(marker);
+            if (at === -1)
+                continue;
+            if (!best || at < best.at || (at === best.at && marker.length > best.marker.length))
+                best = { at, marker };
+        }
+        return best;
+    }
+    /** How much of the end of `text` could be the beginning of a marker. */
+    #partialTail(text) {
+        const candidates = this.#inside ? [this.#inside.close] : this.#markers;
+        let keep = 0;
+        for (const marker of 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;
+    }
+    #take(marker) {
+        if (this.#inside) {
+            this.#inside = undefined;
+            return;
+        }
+        const opened = this.#fences.find((fence) => fence.open === marker);
+        if (opened) {
+            this.#inside = opened;
+            this.#seenFence = true;
+            return;
+        }
+        // A close with no open. The first time, the template opened it in the prompt; after a fence
+        // has been read, it is a stray tag and only dropped.
+        const closes = this.#fences.some((fence) => fence.close === marker);
+        if (closes && !this.#seenFence) {
+            this.reasoning += this.output;
+            this.output = "";
+        }
+        if (closes)
+            this.#seenFence = true;
+    }
+    #emit(parts, text) {
+        if (!text)
+            return;
+        const kind = this.#inside ? "reasoning" : "output";
+        this[kind] += text;
+        const last = parts.at(-1);
+        if (last?.kind === kind)
+            last.text += text;
+        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.
+ */
+export function stripThinking(text, fences = ALL_FENCES) {
+    const splitter = new FenceSplitter(fences);
+    splitter.push(text);
+    splitter.finish();
+    return splitter.output;
+}

package/dist/tool-loading.d.ts

@@ -23,28 +23,49 @@ export declare const LOAD_TOOLS = "load_tools";
  */
 export declare const LOAD_TOOLS_DEFINITION: OpenAI.ChatCompletionTool;
 /**
- * The catalogue as a plain grouped listing of names, loaded ones marked.
+ * The catalogue as a plain grouped listing of names, loaded ones marked if asked.
  *
  * A server with no tools is dropped rather than titled: a pool hands one over whenever a
  * server is connected but has nothing to offer, and a label with nothing under it reads as a
  * listing that got cut off.
  *
  * @param catalog The connected servers. Ones with no tools are dropped.
- * @param loaded Names already loaded, marked in the listing rather than removed from it.
+ * @param loaded Names to mark `(loaded)` rather than remove. Absent marks nothing, which keeps the
+ * listing the same text for the whole run.
  */
 export declare function catalogList(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
 /**
  * The catalogue block appended to the system prompt. Names only — descriptions arrive on load.
  *
- * Loaded tools stay in the list, marked. Removing them reads as the tool having vanished the
- * moment it was loaded, and the model loads again to get it back; hoisting them into a separate
- * "already loaded" section splits a server's tools apart, and the model picks a sibling from
- * the longer list instead.
+ * `runAgentLoop` passes no `loaded`, so the block is the same text on every step. The system
+ * prompt is the head of the request, and marking each load there threw away the prompt cache for
+ * the whole transcript on every `load_tools` call. What is loaded is said where it does not move
+ * the prefix instead: in the tool array, appended in load order (`loadedTools`), and in the
+ * `load_tools` result, which answers a repeat load with "already loaded" (`loadResult`).
+ *
+ * Loaded tools are never removed from the list. That reads as the tool having vanished the moment
+ * it was loaded, and the model loads again to get it back; hoisting them into a separate "already
+ * loaded" section splits a server's tools apart, and the model picks a sibling from the longer
+ * list instead.
  *
  * @param catalog The connected servers. A catalogue with no tools in it produces an empty string.
- * @param loaded Names already loaded, marked in the listing.
+ * @param loaded Names to mark `(loaded)`, for a caller that rebuilds its prompt per load and does
+ * not mind the cache. Absent marks nothing.
  */
 export declare function catalogPrompt(catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
+/**
+ * A tool array with newly loaded definitions appended, in the order they were loaded.
+ *
+ * Never re-sorted and never rebuilt from a set. A template renders the tool array into the
+ * prompt near its head, and a load that moved an earlier definition moved everything after it,
+ * so the cache was lost from there on every load; appended, the definitions already sent stay
+ * a prefix of the new array.
+ *
+ * @param previous What the last request declared, `load_tools` included. Not written to.
+ * @param matched The definitions to add. Ones whose name is already declared, here or earlier in
+ * this list, are skipped rather than moved.
+ */
+export declare function loadedTools(previous: readonly OpenAI.ChatCompletionTool[], matched: readonly OpenAI.ChatCompletionTool[]): OpenAI.ChatCompletionTool[];
 /**
  * The most a single `load_tools` call may pull in.
  *
@@ -103,10 +124,15 @@ export declare function expandNames(requested: string[], catalog: CatalogServer[
 /**
  * What `load_tools` reports back: the descriptions, now that they are worth their tokens.
  *
+ * A name that was loaded before this call is reported as already loaded rather than loaded
+ * again. The catalogue no longer marks what is loaded — see `catalogPrompt` — so this is where a
+ * model that asks twice finds out it need not have, and is told to call the tool instead.
+ *
  * @param expanded What `expandNames` resolved: the matches, the misses, and the over-broad asks.
  * @param catalog The servers, read for the descriptions now worth their tokens.
+ * @param loaded What was loaded before this call. Absent reports every match as newly loaded.
  */
-export declare function loadResult({ matched, unknown, overBroad, deferred, maxPerLoad }: ReturnType<typeof expandNames>, catalog: CatalogServer[]): string;
+export declare function loadResult({ matched, unknown, overBroad, deferred, maxPerLoad }: ReturnType<typeof expandNames>, catalog: CatalogServer[], loaded?: ReadonlySet<string>): string;
 /**
  * Whether the catalogue holds a tool by this name.
  *

package/dist/tool-loading.js

@@ -49,14 +49,15 @@ export const LOAD_TOOLS_DEFINITION = deepFreeze({
     },
 });
 /**
- * The catalogue as a plain grouped listing of names, loaded ones marked.
+ * The catalogue as a plain grouped listing of names, loaded ones marked if asked.
  *
  * A server with no tools is dropped rather than titled: a pool hands one over whenever a
  * server is connected but has nothing to offer, and a label with nothing under it reads as a
  * listing that got cut off.
  *
  * @param catalog The connected servers. Ones with no tools are dropped.
- * @param loaded Names already loaded, marked in the listing rather than removed from it.
+ * @param loaded Names to mark `(loaded)` rather than remove. Absent marks nothing, which keeps the
+ * listing the same text for the whole run.
  */
 export function catalogList(catalog, loaded) {
     return catalog
@@ -70,13 +71,20 @@ export function catalogList(catalog, loaded) {
 /**
  * The catalogue block appended to the system prompt. Names only — descriptions arrive on load.
  *
- * Loaded tools stay in the list, marked. Removing them reads as the tool having vanished the
- * moment it was loaded, and the model loads again to get it back; hoisting them into a separate
- * "already loaded" section splits a server's tools apart, and the model picks a sibling from
- * the longer list instead.
+ * `runAgentLoop` passes no `loaded`, so the block is the same text on every step. The system
+ * prompt is the head of the request, and marking each load there threw away the prompt cache for
+ * the whole transcript on every `load_tools` call. What is loaded is said where it does not move
+ * the prefix instead: in the tool array, appended in load order (`loadedTools`), and in the
+ * `load_tools` result, which answers a repeat load with "already loaded" (`loadResult`).
+ *
+ * Loaded tools are never removed from the list. That reads as the tool having vanished the moment
+ * it was loaded, and the model loads again to get it back; hoisting them into a separate "already
+ * loaded" section splits a server's tools apart, and the model picks a sibling from the longer
+ * list instead.
  *
  * @param catalog The connected servers. A catalogue with no tools in it produces an empty string.
- * @param loaded Names already loaded, marked in the listing.
+ * @param loaded Names to mark `(loaded)`, for a caller that rebuilds its prompt per load and does
+ * not mind the cache. Absent marks nothing.
  */
 export function catalogPrompt(catalog, loaded) {
     const list = catalogList(catalog, loaded);
@@ -88,14 +96,39 @@ export function catalogPrompt(catalog, loaded) {
         "# Tool catalogue",
         "",
         "These tools exist but are not loaded. Call `load_tools` with the names you need, then call",
-        "them on the step after. Names are descriptive; load a tool to see its parameters. A name",
-        "marked `(loaded)` is already in your tool list — call it directly, do not load it again. Do",
-        "not load tools the task does not need, and do not mention this mechanism in your answer.",
+        "them on the step after. Names are descriptive; load a tool to see its parameters. A tool",
+        "already in your tool list is loaded — call it directly, do not load it again. Do not load",
+        "tools the task does not need, and do not mention this mechanism in your answer.",
         "",
         list,
     ].join("\n");
 }
 const flatten = (catalog) => catalog.flatMap((server) => server.tools);
+/**
+ * A tool array with newly loaded definitions appended, in the order they were loaded.
+ *
+ * Never re-sorted and never rebuilt from a set. A template renders the tool array into the
+ * prompt near its head, and a load that moved an earlier definition moved everything after it,
+ * so the cache was lost from there on every load; appended, the definitions already sent stay
+ * a prefix of the new array.
+ *
+ * @param previous What the last request declared, `load_tools` included. Not written to.
+ * @param matched The definitions to add. Ones whose name is already declared, here or earlier in
+ * this list, are skipped rather than moved.
+ */
+export function loadedTools(previous, matched) {
+    const nameOf = (tool) => tool.type === "function" ? tool.function.name : undefined;
+    const declared = new Set(previous.map(nameOf));
+    const tools = [...previous];
+    for (const tool of matched) {
+        const name = nameOf(tool);
+        if (name !== undefined && declared.has(name))
+            continue;
+        declared.add(name);
+        tools.push(tool);
+    }
+    return tools;
+}
 /**
  * The most a single `load_tools` call may pull in.
  *
@@ -201,17 +234,29 @@ export function expandNames(requested, catalog, maxPerLoad = MAX_PER_LOAD) {
 /**
  * What `load_tools` reports back: the descriptions, now that they are worth their tokens.
  *
+ * A name that was loaded before this call is reported as already loaded rather than loaded
+ * again. The catalogue no longer marks what is loaded — see `catalogPrompt` — so this is where a
+ * model that asks twice finds out it need not have, and is told to call the tool instead.
+ *
  * @param expanded What `expandNames` resolved: the matches, the misses, and the over-broad asks.
  * @param catalog The servers, read for the descriptions now worth their tokens.
+ * @param loaded What was loaded before this call. Absent reports every match as newly loaded.
  */
-export function loadResult({ matched, unknown, overBroad, deferred, maxPerLoad }, catalog) {
+export function loadResult({ matched, unknown, overBroad, deferred, maxPerLoad }, catalog, loaded) {
     const byName = new Map(flatten(catalog).map((tool) => [tool.name, tool.description]));
     const lines = [];
-    if (matched.length) {
-        lines.push(`Loaded ${matched.length} tool(s); they are callable on your next step.`, "");
-        for (const name of matched)
+    const fresh = matched.filter((name) => !loaded?.has(name));
+    const again = matched.filter((name) => loaded?.has(name));
+    if (fresh.length) {
+        lines.push(`Loaded ${fresh.length} tool(s); they are callable on your next step.`, "");
+        for (const name of fresh)
             lines.push(`${name}: ${byName.get(name) ?? ""}`.trim());
     }
+    if (again.length) {
+        if (lines.length)
+            lines.push("");
+        lines.push(`Already loaded and in your tool list: ${again.join(", ")}. Call them directly; do not load them again.`);
+    }
     for (const { name, hits } of overBroad) {
         if (lines.length)
             lines.push("");

package/llms.txt

@@ -202,6 +202,19 @@ Reading one streamed turn back into a message.
 - `Turn` (type) — One streamed turn, put back together into the shape a loop and a transcript work with.
 - `TurnUsage` (type) — What a turn cost.
 
+### thinking
+
+Telling a model's scratchpad from its answer when both arrive in `content`.
+
+- `ALL_FENCES` — Every fence known, including the two plain-word ones some fine-tunes and prompt-instructed models use.
+- `DEFAULT_FENCES` — The fences nobody writes by accident, and so the ones `streamTurn` reads by default.
+- `Fence` (type) — One way a model marks off its scratchpad inside `content`.
+- `FenceSplitter` — A state machine over a stream of `content` that routes fenced text to reasoning.
+- `FenceSplitterOptions` (type) — What `FenceSplitter` takes besides its fences.
+- `Split` (type) — A piece of `content`, said to be one or the other.
+- `stripThinking` — What is left of a complete reply once every scratchpad is taken out of it.
+- `THINK_FENCE` — DeepSeek, Qwen3, QwQ and most distills.
+
 ### tokens
 
 - `estimateTokens` — Rough token count.
@@ -218,12 +231,13 @@ Reading what a model meant by a tool call when it did not write one cleanly.
 ### tool-loading
 
 - `carryOver` — The tools to start the next turn with: recently used, newest last, capped.
-- `catalogList` — The catalogue as a plain grouped listing of names, loaded ones marked.
+- `catalogList` — The catalogue as a plain grouped listing of names, loaded ones marked if asked.
 - `catalogPrompt` — The catalogue block appended to the system prompt.
 - `expandNames` — Resolves requested names against the catalogue, expanding trailing `*` wildcards.
 - `inCatalog` — Whether the catalogue holds a tool by this name.
 - `LOAD_TOOLS` — On-demand tool loading.
 - `LOAD_TOOLS_DEFINITION` — One object for the life of the process — the agent loop asks for it on every iteration.
+- `loadedTools` — A tool array with newly loaded definitions appended, in the order they were loaded.
 - `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cubicecho/agent-core",
-  "version": "2.7.0",
+  "version": "2.8.1",
   "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",