@cubicecho/agent-core 2.7.0 → 2.8.0

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
 

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";

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";

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/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.

package/package.json

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