@bitbaum/ai-kit 1.1.0 → 1.3.0

package/dist/policy.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Who may spend what, and what to offer when they may not.
+ *
+ * Pure by the same rule as `fair-share`: no database, no clock, no provider.
+ * The caller owns "what has this user done"; this file owns "what are they
+ * entitled to, and what should they be shown next".
+ *
+ * ── WHY THIS IS ONE OBJECT AND NOT TWO ───────────────────────────────────────
+ *
+ * Across this fleet the same feature was built twice, half each. One app
+ * enforces a daily budget with no interface at all — the user is refused and
+ * never learns why, or what their share was. Another shows a quota meter with
+ * its own separate notion of tier, which the enforcement path does not read.
+ * Both are correct in isolation and they cannot agree, because there was no
+ * single statement of the policy for them to agree ABOUT.
+ *
+ * So the policy is data, and the same object answers both questions: the gate
+ * asks `decide()` whether to allow, and the settings page asks `decide()` what
+ * to draw. A number on screen that the gate does not use is decoration; a gate
+ * whose reasoning cannot be rendered is a wall.
+ *
+ * ── WHY FREE CAPACITY IS A LADDER AND NOT A LIMIT ────────────────────────────
+ *
+ * Shared free capacity is a fixed cost carried on behalf of strangers, and its
+ * only job is to be good enough, once, that someone wants more of it. The
+ * moment it runs out is therefore the only moment anybody changes anything —
+ * which makes the refusal the most important screen in the product, not an
+ * error state.
+ *
+ * Hence `Wall`: a refusal always carries the ways out, in order, and the
+ * default order puts the exits that cost the user NOTHING ahead of the one that
+ * costs money. Asking someone to make a free account elsewhere converts far
+ * better than asking them to pay, and it removes them from the shared pool just
+ * as completely.
+ *
+ * And there is always a floor. `wait` is a real rung with a real time on it,
+ * because "come back at 01:00" is a path and "rate limit exceeded" is a dead
+ * end that reads as broken.
+ */
+/** Where the capacity for a turn comes from. */
+export type PoolId = 
+/** Your keys, your cost, shared by everyone. The sample. */
+"platform"
+/** The user's own key. Free to you, uncapped for them. */
+ | "user"
+/** A model on the user's machine. Free to everyone. */
+ | "local";
+/** The ways off the shared pool, and the floor beneath them. */
+export type RungId = "byok" | "local" | "earn" | "paid" | "wait";
+export interface TierPolicy {
+    /** Turns per UTC day. `null` means uncapped — the user is not your cost. */
+    turnsPerDay: number | null;
+    pool: PoolId;
+    /** Present when spending is metered against a balance rather than a count. */
+    meter?: "credits";
+}
+export interface AiPolicy {
+    /** Tier id → what it may do. App-defined; only the shape is fixed here. */
+    tiers: Record<string, TierPolicy>;
+    /**
+     * What to offer at a wall, in order.
+     *
+     * Defaults to free exits first. Overriding it to lead with `paid` is a
+     * product decision this package will not make for you, but it is worth
+     * knowing you are then asking for money from someone who has not yet
+     * finished evaluating the thing.
+     */
+    ladder?: RungId[];
+}
+/** Sensible order: everything that costs the user nothing, then money, then the floor. */
+export declare const DEFAULT_LADDER: RungId[];
+/** What the caller knows about this user right now. */
+export interface UserState {
+    /** Which tier they are on — a key of `policy.tiers`. */
+    tier: string;
+    /** Turns already spent this UTC day. */
+    spentToday: number;
+    /** Credit balance, when the tier meters credits. */
+    credits?: number;
+    /** Rungs this user could actually take. A rung they cannot reach is not offered. */
+    available?: Partial<Record<RungId, boolean>>;
+}
+/** One way out of a wall, ready to render. */
+export interface WallOption {
+    rung: RungId;
+    /** Whether this user can actually take it. */
+    available: boolean;
+}
+/** Everything needed to draw a refusal that is not a dead end. */
+export interface Wall {
+    reason: "day-spent" | "no-credits" | "unknown-tier";
+    /** Ordered, best first. Never empty — `wait` is always last. */
+    options: WallOption[];
+    /** Epoch ms when the allowance refills, when the caller supplied a day boundary. */
+    resetAt: number | null;
+}
+export interface Decision {
+    allowed: boolean;
+    /** The resolved tier policy, or null when the tier is not in the policy. */
+    policy: TierPolicy | null;
+    pool: PoolId | null;
+    /**
+     * Turns left today. `null` means uncapped, which is NOT the same as zero and
+     * must not render as a gauge — there is nothing to draw a level against.
+     */
+    remaining: number | null;
+    /** Present only when `allowed` is false. */
+    wall?: Wall;
+}
+/** Next UTC midnight — when a per-day allowance refills. */
+export declare function nextUtcReset(now?: number): number;
+/**
+ * May this user spend a turn, and if not, what should they be offered?
+ *
+ * The same call answers the gate and the settings page. A caller that only
+ * needs the number reads `remaining`; one drawing a refusal reads `wall`.
+ */
+export declare function decide(policy: AiPolicy, state: UserState, now?: number): Decision;
+/**
+ * Should the remaining count be put in front of the user yet?
+ *
+ * A permanent gauge at 96% trains people to ignore the one at 4%. The indicator
+ * earns attention near the edge and stays quiet before it — so this returns
+ * false for an uncapped tier (nothing to say) and for a user who has barely
+ * started.
+ */
+export declare function shouldSurface(decision: Decision, threshold?: number): boolean;

package/dist/policy.js

@@ -0,0 +1,122 @@
+/**
+ * Who may spend what, and what to offer when they may not.
+ *
+ * Pure by the same rule as `fair-share`: no database, no clock, no provider.
+ * The caller owns "what has this user done"; this file owns "what are they
+ * entitled to, and what should they be shown next".
+ *
+ * ── WHY THIS IS ONE OBJECT AND NOT TWO ───────────────────────────────────────
+ *
+ * Across this fleet the same feature was built twice, half each. One app
+ * enforces a daily budget with no interface at all — the user is refused and
+ * never learns why, or what their share was. Another shows a quota meter with
+ * its own separate notion of tier, which the enforcement path does not read.
+ * Both are correct in isolation and they cannot agree, because there was no
+ * single statement of the policy for them to agree ABOUT.
+ *
+ * So the policy is data, and the same object answers both questions: the gate
+ * asks `decide()` whether to allow, and the settings page asks `decide()` what
+ * to draw. A number on screen that the gate does not use is decoration; a gate
+ * whose reasoning cannot be rendered is a wall.
+ *
+ * ── WHY FREE CAPACITY IS A LADDER AND NOT A LIMIT ────────────────────────────
+ *
+ * Shared free capacity is a fixed cost carried on behalf of strangers, and its
+ * only job is to be good enough, once, that someone wants more of it. The
+ * moment it runs out is therefore the only moment anybody changes anything —
+ * which makes the refusal the most important screen in the product, not an
+ * error state.
+ *
+ * Hence `Wall`: a refusal always carries the ways out, in order, and the
+ * default order puts the exits that cost the user NOTHING ahead of the one that
+ * costs money. Asking someone to make a free account elsewhere converts far
+ * better than asking them to pay, and it removes them from the shared pool just
+ * as completely.
+ *
+ * And there is always a floor. `wait` is a real rung with a real time on it,
+ * because "come back at 01:00" is a path and "rate limit exceeded" is a dead
+ * end that reads as broken.
+ */
+/** Sensible order: everything that costs the user nothing, then money, then the floor. */
+export const DEFAULT_LADDER = ["byok", "local", "earn", "paid", "wait"];
+/** Next UTC midnight — when a per-day allowance refills. */
+export function nextUtcReset(now = Date.now()) {
+    const d = new Date(now);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate() + 1);
+}
+function buildWall(reason, policy, state, now) {
+    const order = policy.ladder ?? DEFAULT_LADDER;
+    const options = order
+        // `wait` is appended below so it can never be configured away.
+        .filter((rung) => rung !== "wait")
+        .map((rung) => ({ rung, available: state.available?.[rung] ?? true }));
+    // The floor. A refusal without a way forward reads as a broken product, and
+    // the honest way forward is always "this refills, here is when".
+    options.push({ rung: "wait", available: true });
+    return { reason, options, resetAt: nextUtcReset(now) };
+}
+/**
+ * May this user spend a turn, and if not, what should they be offered?
+ *
+ * The same call answers the gate and the settings page. A caller that only
+ * needs the number reads `remaining`; one drawing a refusal reads `wall`.
+ */
+export function decide(policy, state, now = Date.now()) {
+    const tier = policy.tiers[state.tier];
+    // An unknown tier is not a licence to spend. It is a configuration error, and
+    // failing closed here is the difference between a typo costing nothing and a
+    // typo handing out the shared pool.
+    if (!tier) {
+        return {
+            allowed: false,
+            policy: null,
+            pool: null,
+            remaining: 0,
+            wall: buildWall("unknown-tier", policy, state, now),
+        };
+    }
+    if (tier.meter === "credits") {
+        const credits = state.credits ?? 0;
+        return credits > 0
+            ? { allowed: true, policy: tier, pool: tier.pool, remaining: null }
+            : {
+                allowed: false,
+                policy: tier,
+                pool: tier.pool,
+                remaining: 0,
+                wall: buildWall("no-credits", policy, state, now),
+            };
+    }
+    // Uncapped: the user is not your cost, so there is no number to police.
+    if (tier.turnsPerDay === null) {
+        return { allowed: true, policy: tier, pool: tier.pool, remaining: null };
+    }
+    const remaining = Math.max(0, tier.turnsPerDay - state.spentToday);
+    return remaining > 0
+        ? { allowed: true, policy: tier, pool: tier.pool, remaining }
+        : {
+            allowed: false,
+            policy: tier,
+            pool: tier.pool,
+            remaining: 0,
+            wall: buildWall("day-spent", policy, state, now),
+        };
+}
+/**
+ * Should the remaining count be put in front of the user yet?
+ *
+ * A permanent gauge at 96% trains people to ignore the one at 4%. The indicator
+ * earns attention near the edge and stays quiet before it — so this returns
+ * false for an uncapped tier (nothing to say) and for a user who has barely
+ * started.
+ */
+export function shouldSurface(decision, threshold = 0.34) {
+    if (decision.remaining === null)
+        return false;
+    if (!decision.allowed)
+        return true;
+    const cap = decision.policy?.turnsPerDay;
+    if (!cap)
+        return false;
+    return decision.remaining / cap <= threshold;
+}

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@bitbaum/ai-kit",
-  "version": "1.1.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.3.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();
+}

package/src/capability/index.ts

@@ -0,0 +1,52 @@
+/**
+ * ai-kit/capability — what a model can do, observed rather than declared.
+ *
+ * Replaces the list every app writes and every app gets wrong:
+ *
+ *   const TOOL_CAPABLE_PROVIDERS = ['groq', 'openrouter'];
+ *
+ * That line is wrong the moment a user brings a model nobody on the team has
+ * heard of, which is every day. It is also wrong in the other direction: it
+ * cannot express that five of nine free models answer tools only in prose, so
+ * a native-only client silently loses most of its chain while believing it is
+ * fine.
+ *
+ * The replacement is not a better list. It is three rules:
+ *
+ *   1. The first real call IS the probe. Send tools, read what comes back,
+ *      write down what it proved. Every model a user brings classifies itself
+ *      on its first message, at no extra cost and with no release from us.
+ *   2. A positive is cheap and a negative is expensive. One `tool_calls`
+ *      proves capability. A 400 proves nothing unless the vendor SAYS it is
+ *      about tools — otherwise a context-length overflow permanently cripples
+ *      a capable model and nothing explains why.
+ *   3. "Never asked" is its own answer. Optimistic on the wire, because asking
+ *      is how we learn; pessimistic in the prompt and the UI, because
+ *      announcing an unproven capability is a promise the model may not keep.
+ *
+ * Storage stays with the app — a table, a KV, a file. This package owns the
+ * shape and the rules, which is the part everyone gets wrong; it does not own
+ * where rows live, which is the part where apps legitimately differ.
+ */
+export type {
+  ToolVerdict,
+  CapabilityKind,
+  Provenance,
+  CapabilityRecord,
+  CapabilityStore,
+  Classification,
+} from "./types.js";
+
+export { classifyToolAttempt, saysToolsUnsupported, type ToolAttempt } from "./classify.js";
+
+export {
+  planToolAttempt,
+  claimableVerdict,
+  currentVerdict,
+  isStale,
+  makeRecord,
+  scopeKey,
+  shouldReplace,
+  DEFAULT_TTL_MS,
+  type ToolPlan,
+} from "./decide.js";