@bitbaum/ai-kit 1.3.0 → 1.4.0

package/dist/complete.d.ts

@@ -72,9 +72,11 @@ export interface ChatMessage {
  * actually answer on.
  *
  * Both exist in the default chain: of nine free models probed live, four
- * answered with native `tool_calls` and five only in text. Callers get the
- * native shape here; parsing the text protocol is the caller's business,
- * because its convention differs per app.
+ * answered with native `tool_calls` and five only in text — and three of the
+ * seven models shipped in the chain today are in that second group. Since 1.4.0
+ * both are read here, so a caller no longer has to know which half of the chain
+ * answered. See `toolProtocol` on CompleteOptions, and tool-protocol.ts for why
+ * a native-only read is a fabrication path rather than a missing feature.
  */
 export interface ToolCall {
     id: string;
@@ -140,6 +142,23 @@ export interface CompleteOptions {
     temperature?: number;
     /** Tool definitions in the OpenAI shape; passed through untouched. */
     tools?: unknown[];
+    /**
+     * Which tool-call protocols to READ from the reply. Default `"both"`.
+     *
+     * `"both"` also parses the `TOOL:` / `ARGS:` line protocol out of ordinary
+     * content and strips those lines from `text`. This matters more than it
+     * sounds: three of the seven models in the default chain cannot emit a native
+     * tool call at all, and a native-only read hands their narration back as a
+     * finished answer. The turn then reports a lookup that never happened.
+     *
+     * Parsing is skipped entirely when no `tools` are supplied — a model does not
+     * narrate a call it was never offered — so this is inert for the callers who
+     * do not use tools, which today is all of them.
+     *
+     * Set `"native"` only if you parse the text protocol yourself and would
+     * otherwise execute each call twice.
+     */
+    toolProtocol?: "both" | "native";
     /** Extra body fields for a vendor-specific parameter. Merged last, so it can override. */
     extraBody?: Record<string, unknown>;
     /**

package/dist/complete.js

@@ -59,6 +59,7 @@ import { chainFrom, freeChain, usableChain } from "./chain.js";
 import { ChainExhaustedError } from "./attempt.js";
 import { classifyRateLimit, retryAfterSeconds } from "./limits.js";
 import { readQuota, readingFromRefusal } from "./meter.js";
+import { parseTextToolCalls, stripToolCallLines, toolNamesFrom } from "./tool-protocol.js";
 /**
  * A link failed in a way that says something about the WALK, not just this link.
  *
@@ -268,10 +269,28 @@ async function callLink(link, options, key) {
     }
     const choice = parsed
         ?.choices?.[0];
-    const content = firstText(choice?.message);
-    const toolCalls = toolCallsFrom(choice?.message);
+    const rawContent = firstText(choice?.message);
+    const native = toolCallsFrom(choice?.message);
+    // Read the line protocol out of the prose as well, unless the caller opted
+    // out or offered no tools. Native wins on a tie: a model that emits BOTH the
+    // real call and a prose echo of it must not run the tool twice — that wastes
+    // a round trip and can double-propose an action.
+    const wantsText = (options.toolProtocol ?? "both") === "both" && (options.tools?.length ?? 0) > 0;
+    const fromText = wantsText
+        ? parseTextToolCalls(rawContent, toolNamesFrom(options.tools)).filter((c) => {
+            const key = `${c.name}:${c.args}`;
+            return !native.some((n) => `${n.name}:${n.args}` === key);
+        })
+        : [];
+    const toolCalls = [...native, ...fromText];
+    // Strip the protocol lines only when they were actually read as calls.
+    // Removing them without parsing would delete the evidence and leave a shorter
+    // hallucination behind, which is worse than either extreme.
+    const content = fromText.length > 0 ? stripToolCallLines(rawContent) : rawContent;
     // A 200 that carries neither text nor a tool call is an outage wearing a
     // success code — see the header. Demote, so the chain gets its chance.
+    // Note the ordering: a reply that was ONLY a narrated call is now empty text
+    // WITH tool calls, which is a valid turn, not an outage.
     if (content.trim() === "" && toolCalls.length === 0) {
         throw new LinkFailure(link, `${linkId(link)}: 200 with empty content — model produced no output`, {
             status: res.status,

package/dist/index.d.ts

@@ -57,5 +57,6 @@ export { type HealthStatus, type Health, type HealthTrackerOptions, type HealthT
 export { type LivenessResult, type LivenessOptions, type LivenessProbe, type AiHealthHandlerOptions, createLivenessProbe, createAiHealthHandler, } from "./liveness.js";
 export { type RateLimitKind, classifyRateLimit, retryAfterSeconds, humanizeWait, rateLimitMessage, } from "./limits.js";
 export { type QuotaScope, type QuotaWindow, type QuotaReading, type HeaderBag, readQuota, readingFromRefusal, parseResetAt, answersRemaining, } from "./meter.js";
+export { type ParsedToolCall, TEXT_TOOL_PROTOCOL_HINT, parseTextToolCalls, stripToolCallLines, safeJsonObject, toolNamesFrom, } from "./tool-protocol.js";
 export { type PoolId, type RungId, type TierPolicy, type AiPolicy, type UserState, type WallOption, type Wall, type Decision, DEFAULT_LADDER, decide, shouldSurface, nextUtcReset, } from "./policy.js";
 export { DAY_SECONDS, DEFAULT_BURST, type ShareInput, type ShareReason, type ShareDecision, fairShare, utcDayElapsed, utcDayKey, } from "./fair-share.js";

package/dist/index.js

@@ -57,6 +57,7 @@ export { createHealthTracker, } from "./health.js";
 export { createLivenessProbe, createAiHealthHandler, } from "./liveness.js";
 export { classifyRateLimit, retryAfterSeconds, humanizeWait, rateLimitMessage, } from "./limits.js";
 export { readQuota, readingFromRefusal, parseResetAt, answersRemaining, } from "./meter.js";
+export { TEXT_TOOL_PROTOCOL_HINT, parseTextToolCalls, stripToolCallLines, safeJsonObject, toolNamesFrom, } from "./tool-protocol.js";
 export { DEFAULT_LADDER, decide, shouldSurface, nextUtcReset, } from "./policy.js";
 export { DAY_SECONDS, DEFAULT_BURST, fairShare, utcDayElapsed, utcDayKey, } from "./fair-share.js";
 // Form filling lives at `ai-kit/forms`, NOT here.

package/dist/tool-protocol.d.ts

@@ -0,0 +1,93 @@
+/**
+ * The other way models ask for a tool: by writing it in the reply.
+ *
+ * ── WHY A NATIVE-ONLY CLIENT LOSES MOST OF THIS PACKAGE'S OWN CHAIN ──────────
+ *
+ * `chain.ts` carries a probe table from nine free models called with a real
+ * tool. Four answered with native `tool_calls`. Five answered only in TEXT.
+ * Of the seven models in the shipped default chain today, three are in that
+ * second group:
+ *
+ *   google/gemma-4-26b-a4b-it:free      text
+ *   cohere/north-mini-code:free         text
+ *   openrouter/free                     text
+ *
+ * A client that reads only `message.tool_calls` gets ZERO tool calls from those
+ * three — and, far worse, gets the model's narration of the call as ordinary
+ * content. So a turn that should have looked up a record instead returns a
+ * confident sentence describing the lookup it did not perform, and every layer
+ * downstream treats it as an answer. That is not a missing feature; it is a
+ * fabrication path, and it is open on nearly half the chain this package ships.
+ *
+ * ── WHY LINE-BASED AND NOT NESTED JSON ───────────────────────────────────────
+ *
+ * The format is chosen for the WEAKEST model expected to run it, not the
+ * strongest. An 8B model reliably reproduces two flat lines:
+ *
+ *     TOOL: search_people
+ *     ARGS: {"query": "Elena"}
+ *
+ * The same model routinely breaks nested-JSON escaping. Every leniency in the
+ * parser below is a shape a small model actually emitted in production — bolded
+ * keys because it was writing markdown, a fenced ARGS block, the parentheses
+ * copied from the example, a missing ARGS line for a no-argument tool. Rejecting
+ * any of them would fail the turn over formatting, which is the exact failure
+ * this protocol exists to avoid.
+ */
+/** The tool-call shape, matching `complete`'s. `args` stays a raw JSON string. */
+export interface ParsedToolCall {
+    id: string;
+    name: string;
+    args: string;
+}
+/**
+ * The convention, as prompt text.
+ *
+ * Exported so apps stop writing their own wording and drifting from the parser
+ * that has to read it back. A prompt and its parser are one contract; keeping
+ * them in separate repos is how they diverge.
+ *
+ * Note what it does NOT say: it never tells the model to use this INSTEAD of
+ * native calling. A model with native support should use it, and this is the
+ * fallback for one that cannot — offering both costs a few tokens and covers
+ * both halves of the chain.
+ */
+export declare const TEXT_TOOL_PROTOCOL_HINT: string;
+/**
+ * Parse a JSON object, tolerating fences and trailing prose. Null if hopeless.
+ *
+ * `null` and `{}` must stay distinguishable. Returning `{}` for "nothing
+ * parseable here" satisfies a caller's `?? {}` fallback and silently discards
+ * arguments the model put on the NEXT line — which is exactly what a model does
+ * when it opens a ```json fence after `ARGS:`. That cost a debugging cycle once
+ * already; it is a test here now.
+ */
+export declare function safeJsonObject(raw: string): Record<string, unknown> | null;
+/**
+ * Extract text-protocol calls from a reply.
+ *
+ * `validNames` is the closed set the model was offered. A line naming anything
+ * else is left alone: without that check, a model writing the words "TOOL:
+ * whatever" in prose would manufacture a call to a tool that does not exist,
+ * and the executor would report a failure the model never asked for.
+ */
+export declare function parseTextToolCalls(text: string, validNames: string[]): ParsedToolCall[];
+/**
+ * Remove protocol lines from prose.
+ *
+ * A narrated call must never reach the user as though it were an answer, which
+ * is the whole failure this module exists to close. Stripping also means a reply
+ * that was ONLY a tool call ends up empty — and an empty reply carrying tool
+ * calls is a valid turn, while an empty reply carrying none is an outage. The
+ * caller has to keep those apart.
+ */
+export declare function stripToolCallLines(text: string): string;
+/**
+ * The tool names inside an OpenAI-shaped `tools` array.
+ *
+ * Derived from what the caller already passed rather than asked for separately:
+ * two lists that must agree are one list that cannot disagree, and the failure
+ * of the split version is silent — a name missing from the second list makes
+ * the parser ignore a real call.
+ */
+export declare function toolNamesFrom(tools: unknown[] | undefined): string[];

package/dist/tool-protocol.js

@@ -0,0 +1,215 @@
+/**
+ * The other way models ask for a tool: by writing it in the reply.
+ *
+ * ── WHY A NATIVE-ONLY CLIENT LOSES MOST OF THIS PACKAGE'S OWN CHAIN ──────────
+ *
+ * `chain.ts` carries a probe table from nine free models called with a real
+ * tool. Four answered with native `tool_calls`. Five answered only in TEXT.
+ * Of the seven models in the shipped default chain today, three are in that
+ * second group:
+ *
+ *   google/gemma-4-26b-a4b-it:free      text
+ *   cohere/north-mini-code:free         text
+ *   openrouter/free                     text
+ *
+ * A client that reads only `message.tool_calls` gets ZERO tool calls from those
+ * three — and, far worse, gets the model's narration of the call as ordinary
+ * content. So a turn that should have looked up a record instead returns a
+ * confident sentence describing the lookup it did not perform, and every layer
+ * downstream treats it as an answer. That is not a missing feature; it is a
+ * fabrication path, and it is open on nearly half the chain this package ships.
+ *
+ * ── WHY LINE-BASED AND NOT NESTED JSON ───────────────────────────────────────
+ *
+ * The format is chosen for the WEAKEST model expected to run it, not the
+ * strongest. An 8B model reliably reproduces two flat lines:
+ *
+ *     TOOL: search_people
+ *     ARGS: {"query": "Elena"}
+ *
+ * The same model routinely breaks nested-JSON escaping. Every leniency in the
+ * parser below is a shape a small model actually emitted in production — bolded
+ * keys because it was writing markdown, a fenced ARGS block, the parentheses
+ * copied from the example, a missing ARGS line for a no-argument tool. Rejecting
+ * any of them would fail the turn over formatting, which is the exact failure
+ * this protocol exists to avoid.
+ */
+/**
+ * The convention, as prompt text.
+ *
+ * Exported so apps stop writing their own wording and drifting from the parser
+ * that has to read it back. A prompt and its parser are one contract; keeping
+ * them in separate repos is how they diverge.
+ *
+ * Note what it does NOT say: it never tells the model to use this INSTEAD of
+ * native calling. A model with native support should use it, and this is the
+ * fallback for one that cannot — offering both costs a few tokens and covers
+ * both halves of the chain.
+ */
+export const TEXT_TOOL_PROTOCOL_HINT = [
+    "If you cannot emit a native tool call, call a tool by writing these two lines in your reply, exactly like this:",
+    "",
+    "TOOL: tool_name",
+    'ARGS: {"argument": "value"}',
+    "",
+    "Write nothing else in a reply that calls tools — you will be given the results and asked again.",
+].join("\n");
+/** Matches a TOOL: line, tolerating list bullets, markdown bold, and `=`. */
+const TOOL_LINE = /^\s*(?:[-*>]\s*)?(?:\*\*)?TOOL(?:\*\*)?\s*[:=]\s*(.+?)\s*$/i;
+/** Matches an ARGS: line, same tolerances. */
+const ARGS_LINE = /^\s*(?:[-*>]\s*)?(?:\*\*)?ARGS(?:\*\*)?\s*[:=]\s*(.*)$/i;
+/** Either key, for the strip pass. */
+const EITHER_LINE = /^\s*(?:[-*>]\s*)?(?:\*\*)?(?:TOOL|ARGS)(?:\*\*)?\s*[:=]/i;
+/** How far past a TOOL: line to look for its ARGS:, and how far to join a multi-line object. */
+const ARGS_SEARCH_LINES = 4;
+const ARGS_JOIN_LINES = 8;
+/**
+ * Parse a JSON object, tolerating fences and trailing prose. Null if hopeless.
+ *
+ * `null` and `{}` must stay distinguishable. Returning `{}` for "nothing
+ * parseable here" satisfies a caller's `?? {}` fallback and silently discards
+ * arguments the model put on the NEXT line — which is exactly what a model does
+ * when it opens a ```json fence after `ARGS:`. That cost a debugging cycle once
+ * already; it is a test here now.
+ */
+export function safeJsonObject(raw) {
+    const cleaned = raw
+        .trim()
+        .replace(/^```(?:json)?/i, "")
+        .replace(/```$/, "")
+        .trim();
+    if (!cleaned)
+        return null;
+    if (cleaned === "{}")
+        return {};
+    const start = cleaned.indexOf("{");
+    if (start === -1)
+        return null;
+    // Walk to the matching brace so trailing commentary does not break the parse.
+    // String-aware: a brace inside a quoted value must not change the depth, or
+    // an argument like {"q": "a } b"} truncates at the wrong place.
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < cleaned.length; i++) {
+        const ch = cleaned[i];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (ch === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (ch === "{")
+            depth++;
+        else if (ch === "}") {
+            depth--;
+            if (depth === 0) {
+                try {
+                    const parsed = JSON.parse(cleaned.slice(start, i + 1));
+                    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                        ? parsed
+                        : null;
+                }
+                catch {
+                    return null;
+                }
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Extract text-protocol calls from a reply.
+ *
+ * `validNames` is the closed set the model was offered. A line naming anything
+ * else is left alone: without that check, a model writing the words "TOOL:
+ * whatever" in prose would manufacture a call to a tool that does not exist,
+ * and the executor would report a failure the model never asked for.
+ */
+export function parseTextToolCalls(text, validNames) {
+    if (!text || validNames.length === 0)
+        return [];
+    const calls = [];
+    const valid = new Set(validNames);
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        const m = TOOL_LINE.exec(line);
+        const rawName = m?.[1];
+        if (!rawName)
+            continue;
+        // Tolerate `name(...)`, backticks, and trailing punctuation copied from prose.
+        const name = rawName
+            .replace(/[`*]/g, "")
+            .replace(/\(.*$/, "")
+            .replace(/[.,;]$/, "")
+            .trim();
+        if (!valid.has(name))
+            continue;
+        let args = "{}";
+        for (let j = i + 1; j < Math.min(i + ARGS_SEARCH_LINES, lines.length); j++) {
+            const next = lines[j] ?? "";
+            const a = ARGS_LINE.exec(next);
+            if (a) {
+                // The object may continue past this line: a model opening a ```json
+                // fence puts the brace on the NEXT line, and a pretty-printed object
+                // spans several. Join forward and let the brace matcher find the end.
+                const rest = lines.slice(j, Math.min(j + ARGS_JOIN_LINES, lines.length)).join("\n");
+                const parsed = safeJsonObject(a[1] ?? "") ?? safeJsonObject(rest.replace(/^[^:=]*[:=]/, ""));
+                if (parsed)
+                    args = JSON.stringify(parsed);
+                break;
+            }
+            // A new TOOL line means this call simply had no arguments.
+            if (TOOL_LINE.test(next))
+                break;
+        }
+        calls.push({ id: `text_${calls.length}_${name}`, name, args });
+    }
+    return calls;
+}
+/**
+ * Remove protocol lines from prose.
+ *
+ * A narrated call must never reach the user as though it were an answer, which
+ * is the whole failure this module exists to close. Stripping also means a reply
+ * that was ONLY a tool call ends up empty — and an empty reply carrying tool
+ * calls is a valid turn, while an empty reply carrying none is an outage. The
+ * caller has to keep those apart.
+ */
+export function stripToolCallLines(text) {
+    return text
+        .split(/\r?\n/)
+        .filter((l) => !EITHER_LINE.test(l))
+        .join("\n")
+        .replace(/```(?:json)?\s*```/g, "")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+/**
+ * The tool names inside an OpenAI-shaped `tools` array.
+ *
+ * Derived from what the caller already passed rather than asked for separately:
+ * two lists that must agree are one list that cannot disagree, and the failure
+ * of the split version is silent — a name missing from the second list makes
+ * the parser ignore a real call.
+ */
+export function toolNamesFrom(tools) {
+    if (!Array.isArray(tools))
+        return [];
+    const names = [];
+    for (const entry of tools) {
+        const fn = entry?.function;
+        if (fn && typeof fn.name === "string" && fn.name)
+            names.push(fn.name);
+    }
+    return names;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "license": "MIT",
   "author": "Mao Nakamoto",
   "homepage": "https://github.com/bitbaum/ai-kit#readme",

package/src/complete.ts

@@ -61,6 +61,7 @@ import { ChainExhaustedError, type ChainAttemptFailure } from "./attempt.js";
 import type { HealthTracker } from "./health.js";
 import { classifyRateLimit, retryAfterSeconds, type RateLimitKind } from "./limits.js";
 import { readQuota, readingFromRefusal, type QuotaReading } from "./meter.js";
+import { parseTextToolCalls, stripToolCallLines, toolNamesFrom } from "./tool-protocol.js";
 
 /** One message in the OpenAI chat-completions shape every provider here speaks. */
 export interface ChatMessage {
@@ -76,9 +77,11 @@ export interface ChatMessage {
  * actually answer on.
  *
  * Both exist in the default chain: of nine free models probed live, four
- * answered with native `tool_calls` and five only in text. Callers get the
- * native shape here; parsing the text protocol is the caller's business,
- * because its convention differs per app.
+ * answered with native `tool_calls` and five only in text — and three of the
+ * seven models shipped in the chain today are in that second group. Since 1.4.0
+ * both are read here, so a caller no longer has to know which half of the chain
+ * answered. See `toolProtocol` on CompleteOptions, and tool-protocol.ts for why
+ * a native-only read is a fabrication path rather than a missing feature.
  */
 export interface ToolCall {
   id: string;
@@ -145,6 +148,23 @@ export interface CompleteOptions {
   temperature?: number;
   /** Tool definitions in the OpenAI shape; passed through untouched. */
   tools?: unknown[];
+  /**
+   * Which tool-call protocols to READ from the reply. Default `"both"`.
+   *
+   * `"both"` also parses the `TOOL:` / `ARGS:` line protocol out of ordinary
+   * content and strips those lines from `text`. This matters more than it
+   * sounds: three of the seven models in the default chain cannot emit a native
+   * tool call at all, and a native-only read hands their narration back as a
+   * finished answer. The turn then reports a lookup that never happened.
+   *
+   * Parsing is skipped entirely when no `tools` are supplied — a model does not
+   * narrate a call it was never offered — so this is inert for the callers who
+   * do not use tools, which today is all of them.
+   *
+   * Set `"native"` only if you parse the text protocol yourself and would
+   * otherwise execute each call twice.
+   */
+  toolProtocol?: "both" | "native";
   /** Extra body fields for a vendor-specific parameter. Merged last, so it can override. */
   extraBody?: Record<string, unknown>;
   /**
@@ -432,11 +452,31 @@ async function callLink(
 
   const choice = (parsed as { choices?: Array<{ message?: Record<string, unknown> }> })
     ?.choices?.[0];
-  const content = firstText(choice?.message);
-  const toolCalls = toolCallsFrom(choice?.message);
+  const rawContent = firstText(choice?.message);
+  const native = toolCallsFrom(choice?.message);
+
+  // Read the line protocol out of the prose as well, unless the caller opted
+  // out or offered no tools. Native wins on a tie: a model that emits BOTH the
+  // real call and a prose echo of it must not run the tool twice — that wastes
+  // a round trip and can double-propose an action.
+  const wantsText = (options.toolProtocol ?? "both") === "both" && (options.tools?.length ?? 0) > 0;
+  const fromText = wantsText
+    ? parseTextToolCalls(rawContent, toolNamesFrom(options.tools)).filter((c) => {
+        const key = `${c.name}:${c.args}`;
+        return !native.some((n) => `${n.name}:${n.args}` === key);
+      })
+    : [];
+
+  const toolCalls = [...native, ...fromText];
+  // Strip the protocol lines only when they were actually read as calls.
+  // Removing them without parsing would delete the evidence and leave a shorter
+  // hallucination behind, which is worse than either extreme.
+  const content = fromText.length > 0 ? stripToolCallLines(rawContent) : rawContent;
 
   // A 200 that carries neither text nor a tool call is an outage wearing a
   // success code — see the header. Demote, so the chain gets its chance.
+  // Note the ordering: a reply that was ONLY a narrated call is now empty text
+  // WITH tool calls, which is a valid turn, not an outage.
   if (content.trim() === "" && toolCalls.length === 0) {
     throw new LinkFailure(
       link,

package/src/index.ts

@@ -128,6 +128,15 @@ export {
   answersRemaining,
 } from "./meter.js";
 
+export {
+  type ParsedToolCall,
+  TEXT_TOOL_PROTOCOL_HINT,
+  parseTextToolCalls,
+  stripToolCallLines,
+  safeJsonObject,
+  toolNamesFrom,
+} from "./tool-protocol.js";
+
 export {
   type PoolId,
   type RungId,

package/src/tool-protocol.ts

@@ -0,0 +1,223 @@
+/**
+ * The other way models ask for a tool: by writing it in the reply.
+ *
+ * ── WHY A NATIVE-ONLY CLIENT LOSES MOST OF THIS PACKAGE'S OWN CHAIN ──────────
+ *
+ * `chain.ts` carries a probe table from nine free models called with a real
+ * tool. Four answered with native `tool_calls`. Five answered only in TEXT.
+ * Of the seven models in the shipped default chain today, three are in that
+ * second group:
+ *
+ *   google/gemma-4-26b-a4b-it:free      text
+ *   cohere/north-mini-code:free         text
+ *   openrouter/free                     text
+ *
+ * A client that reads only `message.tool_calls` gets ZERO tool calls from those
+ * three — and, far worse, gets the model's narration of the call as ordinary
+ * content. So a turn that should have looked up a record instead returns a
+ * confident sentence describing the lookup it did not perform, and every layer
+ * downstream treats it as an answer. That is not a missing feature; it is a
+ * fabrication path, and it is open on nearly half the chain this package ships.
+ *
+ * ── WHY LINE-BASED AND NOT NESTED JSON ───────────────────────────────────────
+ *
+ * The format is chosen for the WEAKEST model expected to run it, not the
+ * strongest. An 8B model reliably reproduces two flat lines:
+ *
+ *     TOOL: search_people
+ *     ARGS: {"query": "Elena"}
+ *
+ * The same model routinely breaks nested-JSON escaping. Every leniency in the
+ * parser below is a shape a small model actually emitted in production — bolded
+ * keys because it was writing markdown, a fenced ARGS block, the parentheses
+ * copied from the example, a missing ARGS line for a no-argument tool. Rejecting
+ * any of them would fail the turn over formatting, which is the exact failure
+ * this protocol exists to avoid.
+ */
+
+/** The tool-call shape, matching `complete`'s. `args` stays a raw JSON string. */
+export interface ParsedToolCall {
+  id: string;
+  name: string;
+  args: string;
+}
+
+/**
+ * The convention, as prompt text.
+ *
+ * Exported so apps stop writing their own wording and drifting from the parser
+ * that has to read it back. A prompt and its parser are one contract; keeping
+ * them in separate repos is how they diverge.
+ *
+ * Note what it does NOT say: it never tells the model to use this INSTEAD of
+ * native calling. A model with native support should use it, and this is the
+ * fallback for one that cannot — offering both costs a few tokens and covers
+ * both halves of the chain.
+ */
+export const TEXT_TOOL_PROTOCOL_HINT = [
+  "If you cannot emit a native tool call, call a tool by writing these two lines in your reply, exactly like this:",
+  "",
+  "TOOL: tool_name",
+  'ARGS: {"argument": "value"}',
+  "",
+  "Write nothing else in a reply that calls tools — you will be given the results and asked again.",
+].join("\n");
+
+/** Matches a TOOL: line, tolerating list bullets, markdown bold, and `=`. */
+const TOOL_LINE = /^\s*(?:[-*>]\s*)?(?:\*\*)?TOOL(?:\*\*)?\s*[:=]\s*(.+?)\s*$/i;
+/** Matches an ARGS: line, same tolerances. */
+const ARGS_LINE = /^\s*(?:[-*>]\s*)?(?:\*\*)?ARGS(?:\*\*)?\s*[:=]\s*(.*)$/i;
+/** Either key, for the strip pass. */
+const EITHER_LINE = /^\s*(?:[-*>]\s*)?(?:\*\*)?(?:TOOL|ARGS)(?:\*\*)?\s*[:=]/i;
+
+/** How far past a TOOL: line to look for its ARGS:, and how far to join a multi-line object. */
+const ARGS_SEARCH_LINES = 4;
+const ARGS_JOIN_LINES = 8;
+
+/**
+ * Parse a JSON object, tolerating fences and trailing prose. Null if hopeless.
+ *
+ * `null` and `{}` must stay distinguishable. Returning `{}` for "nothing
+ * parseable here" satisfies a caller's `?? {}` fallback and silently discards
+ * arguments the model put on the NEXT line — which is exactly what a model does
+ * when it opens a ```json fence after `ARGS:`. That cost a debugging cycle once
+ * already; it is a test here now.
+ */
+export function safeJsonObject(raw: string): Record<string, unknown> | null {
+  const cleaned = raw
+    .trim()
+    .replace(/^```(?:json)?/i, "")
+    .replace(/```$/, "")
+    .trim();
+  if (!cleaned) return null;
+  if (cleaned === "{}") return {};
+
+  const start = cleaned.indexOf("{");
+  if (start === -1) return null;
+
+  // Walk to the matching brace so trailing commentary does not break the parse.
+  // String-aware: a brace inside a quoted value must not change the depth, or
+  // an argument like {"q": "a } b"} truncates at the wrong place.
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = start; i < cleaned.length; i++) {
+    const ch = cleaned[i];
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+    if (ch === "\\") {
+      escaped = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        try {
+          const parsed: unknown = JSON.parse(cleaned.slice(start, i + 1));
+          return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? (parsed as Record<string, unknown>)
+            : null;
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Extract text-protocol calls from a reply.
+ *
+ * `validNames` is the closed set the model was offered. A line naming anything
+ * else is left alone: without that check, a model writing the words "TOOL:
+ * whatever" in prose would manufacture a call to a tool that does not exist,
+ * and the executor would report a failure the model never asked for.
+ */
+export function parseTextToolCalls(text: string, validNames: string[]): ParsedToolCall[] {
+  if (!text || validNames.length === 0) return [];
+  const calls: ParsedToolCall[] = [];
+  const valid = new Set(validNames);
+  const lines = text.split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    const m = TOOL_LINE.exec(line);
+    const rawName = m?.[1];
+    if (!rawName) continue;
+
+    // Tolerate `name(...)`, backticks, and trailing punctuation copied from prose.
+    const name = rawName
+      .replace(/[`*]/g, "")
+      .replace(/\(.*$/, "")
+      .replace(/[.,;]$/, "")
+      .trim();
+    if (!valid.has(name)) continue;
+
+    let args = "{}";
+    for (let j = i + 1; j < Math.min(i + ARGS_SEARCH_LINES, lines.length); j++) {
+      const next = lines[j] ?? "";
+      const a = ARGS_LINE.exec(next);
+      if (a) {
+        // The object may continue past this line: a model opening a ```json
+        // fence puts the brace on the NEXT line, and a pretty-printed object
+        // spans several. Join forward and let the brace matcher find the end.
+        const rest = lines.slice(j, Math.min(j + ARGS_JOIN_LINES, lines.length)).join("\n");
+        const parsed =
+          safeJsonObject(a[1] ?? "") ?? safeJsonObject(rest.replace(/^[^:=]*[:=]/, ""));
+        if (parsed) args = JSON.stringify(parsed);
+        break;
+      }
+      // A new TOOL line means this call simply had no arguments.
+      if (TOOL_LINE.test(next)) break;
+    }
+
+    calls.push({ id: `text_${calls.length}_${name}`, name, args });
+  }
+  return calls;
+}
+
+/**
+ * Remove protocol lines from prose.
+ *
+ * A narrated call must never reach the user as though it were an answer, which
+ * is the whole failure this module exists to close. Stripping also means a reply
+ * that was ONLY a tool call ends up empty — and an empty reply carrying tool
+ * calls is a valid turn, while an empty reply carrying none is an outage. The
+ * caller has to keep those apart.
+ */
+export function stripToolCallLines(text: string): string {
+  return text
+    .split(/\r?\n/)
+    .filter((l) => !EITHER_LINE.test(l))
+    .join("\n")
+    .replace(/```(?:json)?\s*```/g, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+/**
+ * The tool names inside an OpenAI-shaped `tools` array.
+ *
+ * Derived from what the caller already passed rather than asked for separately:
+ * two lists that must agree are one list that cannot disagree, and the failure
+ * of the split version is silent — a name missing from the second list makes
+ * the parser ignore a real call.
+ */
+export function toolNamesFrom(tools: unknown[] | undefined): string[] {
+  if (!Array.isArray(tools)) return [];
+  const names: string[] = [];
+  for (const entry of tools) {
+    const fn = (entry as { function?: { name?: unknown } } | null)?.function;
+    if (fn && typeof fn.name === "string" && fn.name) names.push(fn.name);
+  }
+  return names;
+}