@bitbaum/ai-kit 1.2.0 → 1.4.0

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,7 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "1.2.0",
-  "description": "One install for the AI layer of an app: which model to call, what to do when the vendor retires it, how to walk the fallback chain and know when none of it worked, how to read the three kinds of 429, a fair daily budget across users, headless AI form filling \u2014 and now the model registry (one SSOT for every callable id, with the paid/free boundary as a field) and the grounding harness (facts, contract, deterministic fabrication check).",
+  "version": "1.4.0",
   "license": "MIT",
   "author": "Mao Nakamoto",
   "homepage": "https://github.com/bitbaum/ai-kit#readme",
@@ -67,6 +66,10 @@
       "types": "./dist/web/index.d.ts",
       "default": "./dist/web/index.js"
     },
+    "./capability": {
+      "types": "./dist/capability/index.d.ts",
+      "default": "./dist/capability/index.js"
+    },
     "./grounding": {
       "types": "./dist/grounding/index.d.ts",
       "require": "./dist-cjs/grounding/index.js",

package/src/capability/classify.ts

@@ -0,0 +1,149 @@
+/**
+ * Reading a real response for what it proves about capability.
+ *
+ * The whole design rests on one asymmetry:
+ *
+ *   A POSITIVE is cheap. One response carrying `tool_calls` proves, beyond
+ *   argument, that this model on this provider with this key can call tools.
+ *   Write it down immediately.
+ *
+ *   A NEGATIVE is expensive and sticky. If a 400 gets recorded as "this model
+ *   has no tools", that model is crippled until the record expires — and the
+ *   user sees a capable model behaving like a toy with nothing explaining why.
+ *   So a negative requires the vendor to SAY it is about tools. A 400 for a
+ *   context-length overflow, a malformed parameter, a content filter or a
+ *   billing problem proves nothing about tools and must be recorded as
+ *   nothing at all.
+ *
+ * That asymmetry is why `record: false` exists. Most failures are
+ * uninformative, and the correct response to an uninformative failure is to
+ * learn nothing, not to guess.
+ */
+import type { Classification } from "./types.js";
+
+/**
+ * Phrases that mean "this model does not do tools", conservatively.
+ *
+ * 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.
+ */
+const TOOLS_UNSUPPORTED_PATTERNS: RegExp[] = [
+  /tool[\s_-]?(use|call|calls|calling)\s+(is\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,
+  /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,
+];
+
+/**
+ * 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.
+ */
+export function saysToolsUnsupported(body: string): boolean {
+  if (!body) return false;
+  return TOOLS_UNSUPPORTED_PATTERNS.some((re) => re.test(body));
+}
+
+/** Shape of an OpenAI-compatible chat completion, as far as we care. */
+type ChatBody = {
+  choices?: Array<{
+    finish_reason?: unknown;
+    message?: { content?: unknown; tool_calls?: unknown };
+  }>;
+};
+
+export type ToolAttempt = {
+  /** HTTP status. 0 or undefined for a transport failure. */
+  status?: number;
+  /** Parsed JSON body, when there was one. */
+  parsed?: unknown;
+  /** Raw body text. Used only for error classification. */
+  bodyText?: string;
+  /**
+   * Did the caller's own text-protocol parser find a usable tool call in the
+   * assistant's prose? Only the app knows its envelope, so it answers this.
+   * Absent means "not checked", which is not the same as "no".
+   */
+  textProtocolFound?: boolean;
+};
+
+/**
+ * What does this attempt prove?
+ *
+ * Call it after EVERY request that carried tool definitions. Real traffic then
+ * classifies every model a user brings, on its first message, at no extra cost
+ * — which is the property that makes this scale to models nobody has heard of.
+ */
+export function classifyToolAttempt(attempt: ToolAttempt): Classification {
+  const { status, parsed, bodyText = "", textProtocolFound } = attempt;
+
+  // ── transport failures prove nothing ────────────────────────────────────
+  if (!status) {
+    return { verdict: "unobserved", record: false, evidence: "no response" };
+  }
+
+  // ── the vendor refused, and we must be careful about why ────────────────
+  if (status >= 400) {
+    if (saysToolsUnsupported(bodyText)) {
+      return {
+        verdict: "none",
+        record: true,
+        evidence: `${status}: the vendor says this model does not support tools`,
+      };
+    }
+    // Everything else — 429, 401, 500, a 400 about context length or a bad
+    // parameter — says nothing about tools. Learning nothing is correct.
+    return {
+      verdict: "unobserved",
+      record: false,
+      evidence: `${status}: not a statement about tool support`,
+    };
+  }
+
+  // ── a success: did it actually call a tool? ─────────────────────────────
+  const body = (parsed ?? {}) as ChatBody;
+  const choice = body.choices?.[0];
+  const toolCalls = choice?.message?.tool_calls;
+
+  if (Array.isArray(toolCalls) && toolCalls.length > 0) {
+    return { verdict: "native", record: true, evidence: "returned tool_calls" };
+  }
+  if (choice?.finish_reason === "tool_calls") {
+    return { verdict: "native", record: true, evidence: "finish_reason was tool_calls" };
+  }
+
+  // The app's own envelope parser found a call in the prose. That is the text
+  // protocol, and it is a real capability — five of nine free models probed in
+  // this fleet answer only this way.
+  if (textProtocolFound === true) {
+    return {
+      verdict: "text",
+      record: true,
+      evidence: "no tool_calls, but a tool call was parsed from the text",
+    };
+  }
+
+  // A successful answer with no tool call is the ambiguous case, and the
+  // ambiguity is real: the model may be incapable, or it may simply have
+  // decided no tool was needed — which is the correct behaviour for most
+  // messages. Treating this as evidence of incapacity would mark almost every
+  // model `none` within a few turns of ordinary chat.
+  return {
+    verdict: "unobserved",
+    record: false,
+    evidence: "answered without calling a tool, which is not evidence either way",
+  };
+}

package/src/capability/decide.ts

@@ -0,0 +1,183 @@
+/**
+ * What to send this time, and what to tell the user we can do.
+ *
+ * Two different questions, deliberately separated:
+ *
+ *   `planToolAttempt` decides what to PUT ON THE WIRE. It is optimistic about
+ *   an unobserved model, because the only way to learn is to ask, and the cost
+ *   of asking is one request that may ignore the tools.
+ *
+ *   `claimableVerdict` decides what to SAY. It is pessimistic about an
+ *   unobserved model, because promising a capability we have never seen is how
+ *   an assistant comes to announce an action it cannot perform.
+ *
+ * Those two pulling in opposite directions is the whole point. A single
+ * "supportsTools" boolean cannot express it, and every app that has tried has
+ * either refused to learn or lied to its users.
+ */
+import { createHash } from "node:crypto";
+import type { CapabilityKind, CapabilityRecord, ToolVerdict } from "./types.js";
+
+/**
+ * How long an observation stands before it must be re-earned.
+ *
+ * Models change under their own names — a vendor updates the weights behind an
+ * alias, an org enables a feature, a local user swaps a quantization. A record
+ * with no expiry is a hardcoded list again, just one we wrote ourselves.
+ *
+ * Negatives expire sooner than positives: a model that gained tool support and
+ * is still marked `none` is invisibly crippled, while a model that lost it
+ * announces itself loudly on the next call.
+ */
+export const DEFAULT_TTL_MS = {
+  native: 30 * 24 * 60 * 60 * 1000,
+  text: 30 * 24 * 60 * 60 * 1000,
+  none: 7 * 24 * 60 * 60 * 1000,
+  unobserved: 0,
+} as const;
+
+export function isStale(
+  record: Pick<CapabilityRecord, "verdict" | "observedAt">,
+  now: Date = new Date(),
+  ttl: Partial<Record<ToolVerdict, number>> = {},
+): boolean {
+  const limit = ttl[record.verdict] ?? DEFAULT_TTL_MS[record.verdict];
+  if (!limit) return true;
+  const age = now.getTime() - new Date(record.observedAt).getTime();
+  return !Number.isFinite(age) || age > limit;
+}
+
+/** The verdict a record still supports, or `unobserved` once it has expired. */
+export function currentVerdict(
+  record: CapabilityRecord | null | undefined,
+  now: Date = new Date(),
+  ttl: Partial<Record<ToolVerdict, number>> = {},
+): ToolVerdict {
+  if (!record) return "unobserved";
+  return isStale(record, now, ttl) ? "unobserved" : record.verdict;
+}
+
+export type ToolPlan = {
+  /** Put tool definitions on the request? */
+  sendTools: boolean;
+  /** Parse the prose for a tool envelope as well? */
+  expectTextProtocol: boolean;
+  /** True when this request is also the thing that will teach us. */
+  isLearning: boolean;
+  reason: string;
+};
+
+/**
+ * What to send. Optimistic about the unknown, because asking is how we learn
+ * and a declared prior is only a guess about where to start.
+ */
+export function planToolAttempt(input: {
+  observed: ToolVerdict;
+  /** What a registry or the vendor's docs claim. A prior, never a fact. */
+  declared?: ToolVerdict;
+}): ToolPlan {
+  const { observed, declared } = input;
+
+  if (observed === "native") {
+    return {
+      sendTools: true,
+      expectTextProtocol: false,
+      isLearning: false,
+      reason: "observed to return tool_calls",
+    };
+  }
+  if (observed === "text") {
+    return {
+      sendTools: false,
+      expectTextProtocol: true,
+      isLearning: false,
+      reason: "observed to answer tools only in prose",
+    };
+  }
+  if (observed === "none") {
+    return {
+      sendTools: false,
+      expectTextProtocol: false,
+      isLearning: false,
+      reason: "the vendor said this model does not support tools",
+    };
+  }
+
+  // Unobserved. Ask — and accept EITHER answer, because a model that ignores
+  // the definitions and writes the envelope in prose is capable, just not
+  // natively, and a native-only client silently loses most of a free chain.
+  return {
+    sendTools: declared !== "none",
+    expectTextProtocol: true,
+    isLearning: true,
+    reason:
+      declared === "none"
+        ? "never observed, and the registry says no — asking in prose only"
+        : "never observed — this request is also the probe",
+  };
+}
+
+/**
+ * What we may TELL the user, and what the prompt may claim.
+ *
+ * Pessimistic about the unknown. `unobserved` returns `none` here on purpose:
+ * until a model has demonstrated a capability, an assistant that announces it
+ * is writing a cheque the model may not honour, and the user discovers that as
+ * a broken promise rather than as a missing feature.
+ */
+export function claimableVerdict(observed: ToolVerdict): Exclude<ToolVerdict, "unobserved"> {
+  return observed === "unobserved" ? "none" : observed;
+}
+
+/**
+ * A stable, non-reversible handle for the credential an observation was made
+ * through. Capability differs per key, so observations must not leak across
+ * keys — and the key itself must never be stored to achieve that.
+ */
+export function scopeKey(secret: string | undefined | null): string {
+  if (!secret) return "anonymous";
+  return createHash("sha256").update(secret).digest("hex").slice(0, 16);
+}
+
+/** Build a record from a classification. Keeps `observedAt` in one place. */
+export function makeRecord(input: {
+  provider: string;
+  model: string;
+  scope: string;
+  capability: CapabilityKind;
+  verdict: ToolVerdict;
+  via: CapabilityRecord["via"];
+  evidence?: string;
+  now?: Date;
+}): CapabilityRecord {
+  return {
+    provider: input.provider,
+    model: input.model,
+    scope: input.scope,
+    capability: input.capability,
+    verdict: input.verdict,
+    via: input.via,
+    observedAt: (input.now ?? new Date()).toISOString(),
+    ...(input.evidence ? { evidence: input.evidence } : {}),
+  };
+}
+
+/**
+ * Should a new observation overwrite the stored one?
+ *
+ * Strength beats age, and `live` beats `declared`, so a real call always
+ * overrules a registry guess. Between two observations of equal provenance the
+ * newer wins — including a `none` replacing a `native`, because a model really
+ * can lose a capability and refusing to believe that is how a chain keeps
+ * calling something that no longer works.
+ */
+export function shouldReplace(
+  existing: CapabilityRecord | null | undefined,
+  incoming: CapabilityRecord,
+): boolean {
+  if (!existing) return true;
+  const rank = { declared: 0, probe: 1, live: 2 } as const;
+  if (rank[incoming.via] > rank[existing.via]) return true;
+  if (rank[incoming.via] < rank[existing.via]) return false;
+  return new Date(incoming.observedAt).getTime() >= new Date(existing.observedAt).getTime();
+}