@bitbaum/ai-kit 1.3.0 → 1.4.1

package/dist/capability/classify.d.ts

@@ -23,9 +23,10 @@ import type { Classification } from "./types.js";
 /**
  * Does this error body explicitly say the model cannot do tools?
  *
- * Conservative on purpose — see the header. A false positive here is a model
- * permanently downgraded for a reason nobody can see; a false negative just
- * means we ask again next time, which costs one request.
+ * Conservative on purpose — see the header. Both failures are real and neither
+ * is free: a false positive downgrades a working model for a reason nobody can
+ * see, and a false negative leaves the caller repeating a request it will
+ * never learn from. Match on "names tools AND negates support", nothing looser.
  */
 export declare function saysToolsUnsupported(body: string): boolean;
 export type ToolAttempt = {

package/dist/capability/classify.js

@@ -4,29 +4,50 @@
  * Every entry names tools or functions explicitly. Deliberately absent:
  * "invalid request", "bad parameter", "unsupported" on its own — each of those
  * appears in vendor 400s for a dozen unrelated reasons, and a match on one of
- * them would silently disable a working model. When in doubt the answer is to
- * record nothing; an unobserved model gets asked again on the next message,
- * whereas a wrongly-negative one does not.
+ * them would silently disable a working model.
+ *
+ * But "when in doubt, record nothing" is only cheap for a caller that can
+ * retry freely, and the real caller cannot. A caller that sends definitions
+ * ALSO drops whatever prose fallback it has, because definitions are supposed
+ * to replace it — so a refusal this list fails to recognise costs a whole turn
+ * in which the model can neither call a tool nor be told how to act without
+ * one, and it costs that turn EVERY turn, forever, because nothing is ever
+ * learned. A missed phrasing is not one wasted request; it is a permanently
+ * mute model.
+ *
+ * So the bar is: does the vendor NAME tools or functions, and NEGATE support?
+ * Both halves, explicitly. Everything meeting that bar belongs here, including
+ * the boring grammatical variants — plural, `are`, `cannot use` — which is
+ * where the first real gap was found (`tools are not supported by this model`
+ * matched nothing at all).
  */
 const TOOLS_UNSUPPORTED_PATTERNS = [
-    /tool[\s_-]?(use|call|calls|calling)\s+(is\s+)?(not|un)[\s_-]?support/i,
+    /tool[\s_-]?(use|call|calls|calling)\s+(is\s+|are\s+)?(not|un)[\s_-]?support/i,
     /does\s+not\s+support\s+tool/i,
     /doesn'?t\s+support\s+tool/i,
     /no\s+support\s+for\s+tool/i,
-    /function[\s_-]?call(ing)?\s+(is\s+)?(not|un)[\s_-]?support/i,
+    /function[\s_-]?call(ing)?\s+(is\s+|are\s+)?(not|un)[\s_-]?support/i,
     /does\s+not\s+support\s+function/i,
     /doesn'?t\s+support\s+function/i,
     /model\s+.{0,60}?\s+does\s+not\s+support\s+(the\s+)?(`?tools`?|`?functions`?)/i,
     /unsupported\s+parameter:?\s*'?"?tools?"?'?/i,
     /unknown\s+(field|parameter):?\s*'?"?tools?"?'?/i,
-    /`?tools`?\s+is\s+not\s+(a\s+)?(valid|supported|allowed)/i,
+    // "tools are not supported", "tool is not valid", "functions are unsupported".
+    // The singular-and-`is` form of this was already here; the plural-and-`are`
+    // form is the one vendors actually write, and it matched nothing.
+    /`?(tools?|functions?)`?\s+(is|are)\s+(not\s+(a\s+)?(valid|supported|allowed|available)|unsupported)/i,
+    // "this model cannot use tools" / "can't call functions".
+    /(cannot|can'?t|is\s+unable\s+to)\s+(use|call|handle|execute)\s+(`?tools?`?|`?functions?`?)/i,
+    // "no tool support", "without function support".
+    /no\s+(`?tools?`?|`?functions?`?)\s+support/i,
 ];
 /**
  * Does this error body explicitly say the model cannot do tools?
  *
- * Conservative on purpose — see the header. A false positive here is a model
- * permanently downgraded for a reason nobody can see; a false negative just
- * means we ask again next time, which costs one request.
+ * Conservative on purpose — see the header. Both failures are real and neither
+ * is free: a false positive downgrades a working model for a reason nobody can
+ * see, and a false negative leaves the caller repeating a request it will
+ * never learn from. Match on "names tools AND negates support", nothing looser.
  */
 export function saysToolsUnsupported(body) {
     if (!body)

package/dist/complete.d.ts

@@ -59,10 +59,38 @@ import { type Env, type Link, type Provider } from "./chain.js";
 import type { HealthTracker } from "./health.js";
 import { type RateLimitKind } from "./limits.js";
 import { type QuotaReading } from "./meter.js";
-/** One message in the OpenAI chat-completions shape every provider here speaks. */
+/**
+ * A piece of a message, for the models that accept more than text.
+ *
+ * The same shape every provider here already speaks, because it is OpenAI's —
+ * `image_url.url` takes a `data:` URL or an `https:` one.
+ */
+export type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: "auto" | "low" | "high";
+    };
+};
+/**
+ * One message in the OpenAI chat-completions shape every provider here speaks.
+ *
+ * `content` accepts parts as well as a string because the implementation
+ * always carried them: `callLink` forwards `messages` into the request body
+ * untouched, so a multimodal message has worked at runtime since the first
+ * release while the type insisted it could not. A consumer that needed to send
+ * a screenshot therefore had to cast around our own type — and a cast written
+ * to work around a library is a thing the next consumer copies.
+ *
+ * Backward compatible by construction: every existing caller passes a string,
+ * and a string is still a `ChatMessage["content"]`.
+ */
 export interface ChatMessage {
     role: "system" | "user" | "assistant" | "tool";
-    content: string;
+    content: string | ContentPart[];
     /** Present on `role: "tool"` replies; passed through untouched. */
     tool_call_id?: string;
     name?: string;
@@ -72,9 +100,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 +170,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

@@ -52,10 +52,11 @@
 export { type Provider, type Env, type Link, type CostVerdict, providerModels, withEnvPrefix, freeChain, modelCost, modelCostAt, paidModelsIn, dayCapacityTokens, usableChain, chainFrom, } from "./chain.js";
 export { type CatalogVerdict, type CheckCatalogOptions, checkCatalog, hasRot, deadProviders, catalogReport, } from "./catalog.js";
 export { type ChainAttemptFailure, type TryChainOptions, ChainExhaustedError, tryChain, } from "./attempt.js";
-export { type ChatMessage, type ToolCall, type CompleteOptions, type CompleteResult, LinkFailure, complete, linkId, } from "./complete.js";
+export { type ChatMessage, type ContentPart, type ToolCall, type CompleteOptions, type CompleteResult, LinkFailure, complete, linkId, } from "./complete.js";
 export { type HealthStatus, type Health, type HealthTrackerOptions, type HealthTracker, createHealthTracker, } from "./health.js";
 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.1",
   "license": "MIT",
   "author": "Mao Nakamoto",
   "homepage": "https://github.com/bitbaum/ai-kit#readme",
@@ -90,12 +90,12 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/node": "^26.4.1",
-    "eslint": "^10.9.1",
+    "@types/node": "^26.5.0",
+    "eslint": "^10.10.0",
     "globals": "^17.12.0",
     "prettier": "3.9.6",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.69.0"
+    "typescript-eslint": "^8.70.0"
   },
   "dependencies": {
     "ai-forms": "^0.1.2"

package/src/capability/classify.ts

@@ -27,30 +27,51 @@ import type { Classification } from "./types.js";
  * Every entry names tools or functions explicitly. Deliberately absent:
  * "invalid request", "bad parameter", "unsupported" on its own — each of those
  * appears in vendor 400s for a dozen unrelated reasons, and a match on one of
- * them would silently disable a working model. When in doubt the answer is to
- * record nothing; an unobserved model gets asked again on the next message,
- * whereas a wrongly-negative one does not.
+ * them would silently disable a working model.
+ *
+ * But "when in doubt, record nothing" is only cheap for a caller that can
+ * retry freely, and the real caller cannot. A caller that sends definitions
+ * ALSO drops whatever prose fallback it has, because definitions are supposed
+ * to replace it — so a refusal this list fails to recognise costs a whole turn
+ * in which the model can neither call a tool nor be told how to act without
+ * one, and it costs that turn EVERY turn, forever, because nothing is ever
+ * learned. A missed phrasing is not one wasted request; it is a permanently
+ * mute model.
+ *
+ * So the bar is: does the vendor NAME tools or functions, and NEGATE support?
+ * Both halves, explicitly. Everything meeting that bar belongs here, including
+ * the boring grammatical variants — plural, `are`, `cannot use` — which is
+ * where the first real gap was found (`tools are not supported by this model`
+ * matched nothing at all).
  */
 const TOOLS_UNSUPPORTED_PATTERNS: RegExp[] = [
-  /tool[\s_-]?(use|call|calls|calling)\s+(is\s+)?(not|un)[\s_-]?support/i,
+  /tool[\s_-]?(use|call|calls|calling)\s+(is\s+|are\s+)?(not|un)[\s_-]?support/i,
   /does\s+not\s+support\s+tool/i,
   /doesn'?t\s+support\s+tool/i,
   /no\s+support\s+for\s+tool/i,
-  /function[\s_-]?call(ing)?\s+(is\s+)?(not|un)[\s_-]?support/i,
+  /function[\s_-]?call(ing)?\s+(is\s+|are\s+)?(not|un)[\s_-]?support/i,
   /does\s+not\s+support\s+function/i,
   /doesn'?t\s+support\s+function/i,
   /model\s+.{0,60}?\s+does\s+not\s+support\s+(the\s+)?(`?tools`?|`?functions`?)/i,
   /unsupported\s+parameter:?\s*'?"?tools?"?'?/i,
   /unknown\s+(field|parameter):?\s*'?"?tools?"?'?/i,
-  /`?tools`?\s+is\s+not\s+(a\s+)?(valid|supported|allowed)/i,
+  // "tools are not supported", "tool is not valid", "functions are unsupported".
+  // The singular-and-`is` form of this was already here; the plural-and-`are`
+  // form is the one vendors actually write, and it matched nothing.
+  /`?(tools?|functions?)`?\s+(is|are)\s+(not\s+(a\s+)?(valid|supported|allowed|available)|unsupported)/i,
+  // "this model cannot use tools" / "can't call functions".
+  /(cannot|can'?t|is\s+unable\s+to)\s+(use|call|handle|execute)\s+(`?tools?`?|`?functions?`?)/i,
+  // "no tool support", "without function support".
+  /no\s+(`?tools?`?|`?functions?`?)\s+support/i,
 ];
 
 /**
  * Does this error body explicitly say the model cannot do tools?
  *
- * Conservative on purpose — see the header. A false positive here is a model
- * permanently downgraded for a reason nobody can see; a false negative just
- * means we ask again next time, which costs one request.
+ * Conservative on purpose — see the header. Both failures are real and neither
+ * is free: a false positive downgrades a working model for a reason nobody can
+ * see, and a false negative leaves the caller repeating a request it will
+ * never learn from. Match on "names tools AND negates support", nothing looser.
  */
 export function saysToolsUnsupported(body: string): boolean {
   if (!body) return false;

package/src/complete.ts

@@ -61,11 +61,34 @@ 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. */
+/**
+ * A piece of a message, for the models that accept more than text.
+ *
+ * The same shape every provider here already speaks, because it is OpenAI's —
+ * `image_url.url` takes a `data:` URL or an `https:` one.
+ */
+export type ContentPart =
+  | { type: "text"; text: string }
+  | { type: "image_url"; image_url: { url: string; detail?: "auto" | "low" | "high" } };
+
+/**
+ * One message in the OpenAI chat-completions shape every provider here speaks.
+ *
+ * `content` accepts parts as well as a string because the implementation
+ * always carried them: `callLink` forwards `messages` into the request body
+ * untouched, so a multimodal message has worked at runtime since the first
+ * release while the type insisted it could not. A consumer that needed to send
+ * a screenshot therefore had to cast around our own type — and a cast written
+ * to work around a library is a thing the next consumer copies.
+ *
+ * Backward compatible by construction: every existing caller passes a string,
+ * and a string is still a `ChatMessage["content"]`.
+ */
 export interface ChatMessage {
   role: "system" | "user" | "assistant" | "tool";
-  content: string;
+  content: string | ContentPart[];
   /** Present on `role: "tool"` replies; passed through untouched. */
   tool_call_id?: string;
   name?: string;
@@ -76,9 +99,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 +170,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 +474,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

@@ -84,6 +84,7 @@ export {
 
 export {
   type ChatMessage,
+  type ContentPart,
   type ToolCall,
   type CompleteOptions,
   type CompleteResult,
@@ -128,6 +129,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;
+}