@zerotal/ai 1.11.0 → 1.11.2

package/CHANGELOG.md

@@ -4,10 +4,101 @@ All notable changes to this package are documented here. The format is
 based on [Keep a Changelog](https://keepachangelog.com/); this package
 follows the Zerotal monorepo's unified versioning.
 
-**Maturity: `experimental`**
+**Maturity: `stable`**
 
 ## [Unreleased]
 
+## [1.11.2] — 2026-08-31
+
+### Changed
+
+- **Promoted to `stable`.** The public API now follows the compatibility promise in
+  [the support policy](https://zerotal.dev/docs/support-policy): anything importable
+  without an `@internal` marker is covered.
+
+  The precondition was met rather than waived. This package shipped `experimental`
+  with a stated one — _it graduates in the release after its first real users_ — and
+  its first production users sent a field review of the driver running against
+  Anthropic. Five bugs came back with it, all fixed below. A `stable` promise about an
+  API that nothing has pushed against is a promise nobody has tested.
+
+  **The surface was narrowed first**, because narrowing after `stable` is itself a
+  breaking change. `toSchema`, `strippedConstraints`, `resetSpend` and `resetStats` are
+  `@internal` — still exported, so nothing breaks at runtime, but no longer promised.
+  `translateSchema` stayed public despite having no caller outside this package, for
+  the same reason `AiDriver` is public: the point of a driver contract is that someone
+  else implements it, and implementing structured output means translating a schema.
+  `AiDelivery` stayed too — it is the element type of `recentGenerations()`, and
+  marking the return type of a public function internal would be the exact lie the
+  review is meant to prevent.
+
+  Then the two modules it would have been embarrassing to freeze untested: the SSE
+  parser, which reads a remote provider's framing off the network, and prompt
+  redaction, which is the only thing between a user's prompt and a log that outlives
+  the request.
+
+- **An app with no AI configured now boots.** `AiConfig` threw when no driver was
+  declared, and threw again on an empty `apiKey`, so a deployment with no key could
+  not express itself either way — one app declared an Ollama server it did not run
+  purely to satisfy the validator, with a comment explaining that the config was lying.
+  Declaring no driver is now legal and means AI is off; the first call raises
+  `AiDriverUnavailableError`, whose `transient` is already `false`, so a caller that
+  latches itself off on a permanent error gets the right behaviour for free. Declaring
+  a driver still means you want it, so an incomplete one is still refused at boot.
+
+- **`countTokens` returns `null` where a provider cannot count**, rather than `0`. Only
+  Anthropic has a counting endpoint; `0` is also a real count for an empty prompt, so
+  the old return value was a number you could divide by and budget against without ever
+  being told it meant "unsupported".
+
+### Fixed
+
+- **Sonnet 5 was priced as Sonnet 4.6** — 3/15 instead of 2/10, 50% high. The same
+  table feeds `limits.perRequestUsd` and `perDayUsd`, so a Sonnet 5 app was refused
+  requests comfortably inside its budget and the daily ceiling tripped a third early.
+  The error said "spend limit", which sends someone to their config rather than to the
+  row that is wrong. `AiSpendLimitError` now quotes the rate it used and names
+  `registerModelPrice()`, so a bad table is legible from the refusal and correctable
+  without waiting for a release.
+
+- **`effort` and `thinking` are model-aware.** Both were sent on every call. `effort`
+  is a 400 on the 4.5 generation, and those models want an explicit thinking budget
+  rather than `{ type: "adaptive" }` — so the package advertised `claude-haiku-4-5` in
+  its pricing table while the driver could not successfully call it. `modelCapabilities()`
+  now answers what a model takes, and the driver builds the request that model accepts.
+
+  The table lists the models that _differ_ and treats anything unrecognised as current
+  generation. An allowlist would need an edit every time a model ships and would treat
+  each new one as legacy until that edit landed; the models that differ are a closed
+  set that ages out.
+
+- **`temperature` never reached the API, on any model.** The driver warned about
+  dropping it and had no branch that set it, so `AiRequest.temperature` and the
+  configured default were both inert everywhere — including on the 4.6 models, which
+  accept it. The old sampling predicate hid this by warning for almost every model,
+  which made the silence look deliberate on the few it did not warn for. Sampling
+  parameters are now sent where the model takes them.
+
+- **`modelRejectsSampling` was too broad**, reading as "every Claude model except 4.6",
+  which is wrong for the 4.5 generation. It compounded with the above: on Haiku 4.5 the
+  driver dropped a legal `temperature` and advised `effort` instead — the one parameter
+  guaranteed to fail there. The advice is now only given where `effort` exists, in the
+  driver and in `validateAiConfig` alike.
+
+- **The streamed `thinking` chunk was always empty.** The API omits thinking text by
+  default on the current generation, so a documented stream chunk fired forever with
+  `text: ""` and no error — and a "thinking…" view built against the 4.6 models, where
+  it defaulted to on, silently stopped working as users moved to 5.
+  `drivers.anthropic.thinkingDisplay` defaults to `"summarized"`; set `"omitted"` for
+  the API's own default. The thinking happens and is billed either way.
+
+### Added
+
+- **`modelCapabilities()` and `ModelCapabilities`** — what a model accepts: sampling,
+  `effort`, and which of the three thinking shapes it takes.
+- **`drivers.anthropic.thinkingDisplay`** — whether a streamed `thinking` chunk carries
+  text.
+
 ## [1.11.0] — 2026-08-31
 
 ### Fixed

package/README.md

@@ -6,7 +6,9 @@ One way to talk to a language model: `Ai.text()` for a completion, `Ai.stream()`
 
 Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
 
-**Maturity: `experimental`** — the API may change in a minor release.
+**Maturity: `stable`** — the public API follows the compatibility promise in
+[the support policy](https://zerotal.dev/docs/support-policy). Anything importable
+that does not carry an `@internal` marker is covered.
 
 ## Installation
 

package/api-surface.md

@@ -31,6 +31,7 @@ class AiConfigError = {
 
 class AiDriverUnavailableError = {
   new (driver: string, packageName: string): AiDriverUnavailableError
+  static notConfigured: (requested: string) => AiDriverUnavailableError
   readonly code: string
   readonly context?: Record<string, unknown> | undefined
   readonly status: number
@@ -91,7 +92,7 @@ class AiGenerated = {
 class AiManager = {
   new (config: AiConfigShape): AiManager
   agent: (request: AiAgentRequest) => Promise<AiAgentResult>
-  countTokens: (request: AiRequest | string) => Promise<number>
+  countTokens: (request: AiRequest | string) => Promise<number | null>
   driver: (name?: string) => AiDriver
   drivers: () => string[]
   embed: (input: string | string[], options?: Omit<AiEmbedRequest, 'input'>) => Promise<AiEmbedResponse>
@@ -195,7 +196,7 @@ class AiToolCalled = {
 
 class AnthropicDriver = {
   new (config: AnthropicConfigShape, inject?: LoadedAnthropic): AnthropicDriver
-  countTokens: (request: AiRequest) => Promise<number>
+  countTokens: (request: AiRequest) => Promise<number | null>
   model: string
   object: <T>(request: AiRequest, schema: SchemaInput) => Promise<AiObjectResponse<T>>
   readonly name: 'anthropic'
@@ -206,7 +207,7 @@ class AnthropicDriver = {
 
 class OllamaDriver = {
   new (config: OllamaConfigShape, fetchImpl?: typeof fetch): OllamaDriver
-  countTokens: (_request: AiRequest) => Promise<number>
+  countTokens: (_request: AiRequest) => Promise<number | null>
   model: string
   object: <T>(request: AiRequest, schema: SchemaInput) => Promise<AiObjectResponse<T>>
   readonly name: 'ollama'
@@ -224,7 +225,7 @@ class OllamaEmbeddingsDriver = {
 
 class OpenAiDriver = {
   new (config: OpenAiConfigShape, fetchImpl?: typeof fetch): OpenAiDriver
-  countTokens: (_request: AiRequest) => Promise<number>
+  countTokens: (_request: AiRequest) => Promise<number | null>
   model: string
   object: <T>(request: AiRequest, schema: SchemaInput) => Promise<AiObjectResponse<T>>
   readonly name: 'openai'
@@ -256,6 +257,8 @@ function AiConfigFromEnv = () => AiConfigShape
 
 function estimateCost = (model: string, usage: AiUsage) => number
 
+function modelCapabilities = (model: string) => ModelCapabilities
+
 function modelPrice = (model: string) => ModelPrice | undefined
 
 function modelRejectsSampling = (model: string) => boolean
@@ -268,18 +271,10 @@ function refusalRate = () => number
 
 function registerModelPrice = (model: string, price: ModelPrice) => void
 
-function resetSpend = () => void
-
-function resetStats = () => void
-
 function spentToday = () => number
 
-function strippedConstraints = (input: SchemaInput) => string[]
-
 function tool = <I extends Record<string, unknown> = Record<string, unknown>>(options: {    name: string;    description: string;    input: ((rule: RuleBuilder) => Record<string, FieldRule>) | SchemaInput;    handle: (input: I, ctx: AiToolContext) => Promise<unknown> | unknown;}) => AiTool
 
-function toSchema = (input: SchemaInput) => Schema
-
 function translateSchema = (input: SchemaInput) => JsonSchema
 
 interface AgentOptions = {
@@ -356,7 +351,7 @@ interface AiDelivery = {
 
 interface AiDriver = {
   agent?: (request: AiRequest, options: AgentOptions) => Promise<AiAgentResult>
-  countTokens: (request: AiRequest) => Promise<number>
+  countTokens: (request: AiRequest) => Promise<number | null>
   object: <T>(request: AiRequest, schema: SchemaInput) => Promise<AiObjectResponse<T>>
   readonly model: string
   readonly name: string
@@ -470,6 +465,7 @@ interface AnthropicConfigShape = {
   model: string
   streamMaxTokens: number
   temperature?: number | undefined
+  thinkingDisplay: 'summarized' | 'omitted'
   timeout: number
 }
 
@@ -509,6 +505,12 @@ interface JsonSchema = {
   type?: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'integer' | 'null'
 }
 
+interface ModelCapabilities = {
+  effort: boolean
+  sampling: boolean
+  thinking: 'adaptive' | 'budget' | null
+}
+
 interface ModelPrice = {
   input: number
   output: number

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@zerotal/ai",
-  "version": "1.11.0",
+  "version": "1.11.2",
   "license": "MIT",
-  "maturity": "experimental",
-  "maturityReview": "1.11.0",
+  "maturity": "stable",
   "private": false,
   "type": "module",
   "main": "./src/index.ts",
@@ -31,9 +30,9 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.11.0",
-    "@zerotal/validator": "1.11.0",
-    "@zerotal/queue": "1.11.0"
+    "@zerotal/core": "1.11.2",
+    "@zerotal/validator": "1.11.2",
+    "@zerotal/queue": "1.11.2"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.70.0"

package/src/AiManager.ts

@@ -8,7 +8,13 @@ import { OpenAiEmbeddingsDriver } from "./drivers/embeddings/OpenAiEmbeddingsDri
 import type { EmbeddingsDriver } from "./drivers/embeddings/EmbeddingsDriver.ts";
 import type { AiDriver, DriverStatus } from "./drivers/AiDriver.ts";
 import { normalizeMessages, promptText } from "./drivers/AiDriver.ts";
-import { AiCancelledError, AiConfigError, AiRefusedError, UnknownAiDriverError } from "./errors.ts";
+import {
+  AiCancelledError,
+  AiConfigError,
+  AiDriverUnavailableError,
+  AiRefusedError,
+  UnknownAiDriverError,
+} from "./errors.ts";
 import { AiGenerated, AiRefused } from "./events.ts";
 import { estimateCost } from "./pricing.ts";
 import { redactPrompt } from "./redact.ts";
@@ -144,7 +150,16 @@ export class AiManager {
     if (existing) return existing;
 
     const resolver = this._resolvers.get(key);
-    if (!resolver) throw new UnknownAiDriverError(key, [...this._resolvers.keys()]);
+    if (!resolver) {
+      // No driver at all is a different situation from a driver named wrongly, and
+      // it is now a legal config: an app can ship with AI off and no key. Saying
+      // "unknown driver 'anthropic', configured: (none)" invites someone to go
+      // looking for a typo. Both errors are permanent (`transient: false`), so a
+      // caller latching itself off behaves correctly either way — this only decides
+      // which sentence it reads on the way.
+      if (this._resolvers.size === 0) throw AiDriverUnavailableError.notConfigured(key);
+      throw new UnknownAiDriverError(key, [...this._resolvers.keys()]);
+    }
 
     const instance = resolver();
     this._drivers.set(key, instance);
@@ -358,8 +373,12 @@ export class AiManager {
     return result;
   }
 
-  /** Count the prompt's tokens with the provider's own tokenizer. */
-  async countTokens(request: AiRequest | string): Promise<number> {
+  /**
+   * Count the prompt's tokens with the provider's own tokenizer.
+   *
+   * `null` when the configured provider cannot count — only Anthropic can, today.
+   */
+  async countTokens(request: AiRequest | string): Promise<number | null> {
     const normalized = normalize(request);
     return this.driver(normalized.driver).countTokens(normalized);
   }
@@ -458,7 +477,10 @@ export class AiManager {
     let inputTokens = 0;
 
     if (limits.perRequestUsd > 0) {
-      inputTokens = await driver.countTokens(request).catch(() => 0);
+      // A provider that cannot count, or one whose count failed, falls back to the
+      // approximation. Both were already the same branch when this returned 0 — the
+      // difference is that the ambiguity is no longer visible to callers.
+      inputTokens = (await driver.countTokens(request).catch(() => null)) ?? 0;
       if (inputTokens === 0) inputTokens = approximateTokens(request);
     }
 

package/src/config.ts

@@ -8,7 +8,7 @@ import type {
   OllamaConfigShape,
   OpenAiConfigShape,
 } from "./types.ts";
-import { modelRejectsSampling } from "./pricing.ts";
+import { modelCapabilities } from "./modelCapabilities.ts";
 
 /**
  * What {@link AiConfig} accepts — every key optional, all the way down. The
@@ -109,6 +109,7 @@ function applyDriverDefaults(config: AiConfigShape): void {
       // Streaming has no HTTP-timeout ceiling to respect, so give it room.
       streamMaxTokens: given.streamMaxTokens ?? 64000,
       effort: given.effort ?? "high",
+      thinkingDisplay: given.thinkingDisplay ?? "summarized",
       fallbacks: given.fallbacks ?? true,
       cacheSystem: given.cacheSystem ?? true,
       timeout: given.timeout ?? 600_000,
@@ -192,13 +193,19 @@ export function validateAiConfig(config: AiConfigShape): void {
     (name) => drivers[name as keyof typeof drivers] !== undefined,
   );
 
-  if (configured.length === 0) {
-    throw new AiConfigError(
-      "No AI drivers are configured. Add at least one under drivers in config/ai.ts.",
-    );
-  }
-
-  if (!configured.includes(config.default)) {
+  // "AI is off" is a coherent deployment, and it used to be inexpressible: naming no
+  // driver was a boot failure and naming one without a key was also a boot failure,
+  // so an app with no key on this machine had to declare a driver it did not run
+  // purely to satisfy this function. One did — an Ollama block it had no server for,
+  // with a comment explaining that the config was lying to get past the validator.
+  //
+  // So the split is by intent. *Declaring* a driver still means "I want this", and an
+  // incomplete one is still a misconfiguration worth refusing at boot. Declaring
+  // none — or pointing `default` at one you did not declare — now means AI is not
+  // available here, which is a fact rather than an error. The first call says so,
+  // through `AiDriverUnavailableError`, whose `transient` is already `false`: a caller
+  // that latches itself off on a permanent error gets the right behaviour for free.
+  if (configured.length > 0 && !configured.includes(config.default)) {
     throw new AiConfigError(
       `default is '${config.default}' but that driver has no block. Configured: ${configured.join(", ")}.`,
       { default: config.default, configured },
@@ -224,13 +231,20 @@ export function validateAiConfig(config: AiConfigShape): void {
         { maxTokens: a.maxTokens, streamMaxTokens: a.streamMaxTokens },
       );
     }
-    if (a.temperature !== undefined && modelRejectsSampling(a.model)) {
+    const capabilities = modelCapabilities(a.model);
+    if (a.temperature !== undefined && !capabilities.sampling) {
       // A warning rather than a throw: the driver drops it and the request still
       // succeeds. Throwing would break an app whose config merely carries a
       // leftover from a model that accepted it.
       console.warn(
         `[Zerotal/ai] drivers.anthropic.temperature is set, but ${a.model} rejects temperature/top_p/top_k ` +
-          `with a 400. The driver drops it. Use effort ('low' … 'max') to trade thoroughness for cost instead.`,
+          `with a 400. The driver drops it.` +
+          // Only where effort exists. This suggestion used to be unconditional and
+          // fired on models that accept the temperature it was telling them to
+          // replace — recommending the one parameter that 400s there.
+          (capabilities.effort
+            ? ` Use effort ('low' … 'max') to trade thoroughness for cost instead.`
+            : ""),
       );
     }
   }

package/src/drivers/AiDriver.ts

@@ -61,8 +61,13 @@ export interface AiDriver {
    * Count the tokens this request would consume, using the provider's own
    * tokenizer. Never an estimate from another vendor's tokenizer — the spend
    * panel is built on this number.
+   *
+   * `null` when the provider has no counting endpoint, which is most of them.
+   * It used to be `0`, and a zero that means "cannot count" is indistinguishable
+   * from a zero that means "empty prompt" — easy to divide by, easy to budget
+   * against, and wrong in the direction that costs money.
    */
-  countTokens(request: AiRequest): Promise<number>;
+  countTokens(request: AiRequest): Promise<number | null>;
 
   /** Reach the provider once and report what came back. Backs `zt ai:test`. */
   verify(): Promise<DriverStatus>;

package/src/drivers/AnthropicDriver.ts

@@ -7,7 +7,8 @@ import {
   AiSchemaError,
 } from "../errors.ts";
 import { recheckAgainstSchema, translateSchema, type SchemaInput } from "../schema.ts";
-import { modelRejectsSampling } from "../pricing.ts";
+import { modelCapabilities } from "../modelCapabilities.ts";
+import type { ModelCapabilities } from "../modelCapabilities.ts";
 import type {
   AiMessage,
   AiObjectResponse,
@@ -35,6 +36,14 @@ import type {
 /** Opts into the server-side refusal fallback. */
 const FALLBACK_BETA = "server-side-fallback-2026-07-01";
 
+/**
+ * The API's floor for an explicit thinking budget, on the models that take one.
+ *
+ * A budget below this is rejected, so a `max_tokens` too small to hold both a
+ * budget and an answer means thinking is dropped rather than asked for invalidly.
+ */
+const MIN_THINKING_BUDGET = 1024;
+
 /**
  * Roughly the shortest system prompt worth a cache breakpoint.
  *
@@ -165,10 +174,10 @@ export class AnthropicDriver implements AiDriver {
     };
   }
 
-  async countTokens(request: AiRequest): Promise<number> {
+  async countTokens(request: AiRequest): Promise<number | null> {
     const { client } = await this._load();
     const api = this._api(client);
-    if (!api.countTokens) return 0;
+    if (!api.countTokens) return null;
 
     const params = this._params(request, false);
     // Counting is about the prompt; the response ceiling and sampling knobs are
@@ -217,16 +226,62 @@ export class AnthropicDriver implements AiDriver {
       : { timeout: this.config.timeout };
   }
 
+  /**
+   * The `thinking` block for this model, or `null` to omit the field.
+   *
+   * Three shapes, because the models take three. The 4.5 generation wants an
+   * explicit `budget_tokens`; everything current takes `adaptive` and decides for
+   * itself; a non-Anthropic id gets nothing. Sending the wrong one is a 400, which
+   * is why this returns `null` rather than guessing.
+   *
+   * `display` is set on the adaptive form because the API omits thinking text by
+   * default there — see {@link AnthropicConfigShape.thinkingDisplay}.
+   *
+   * @param capabilities - What the model accepts.
+   * @param maxTokens - The request's ceiling, which thinking shares with the answer.
+   */
+  private _thinking(
+    capabilities: ModelCapabilities,
+    maxTokens: number,
+  ): Record<string, unknown> | null {
+    if (capabilities.thinking === null) return null;
+
+    if (capabilities.thinking === "budget") {
+      // The API requires at least 1024 thinking tokens, and the budget shares
+      // `max_tokens` with the answer. A ceiling too low to hold both is a request
+      // that would be rejected for asking, so thinking is dropped instead — the
+      // answer is what the caller wanted.
+      const budget = Math.floor(maxTokens / 2);
+      if (budget < MIN_THINKING_BUDGET) return null;
+      return { type: "enabled", budget_tokens: budget };
+    }
+
+    // Defaulted here as well as in `AiConfig`, because a config object built by
+    // hand — a test, a driver constructed directly — would otherwise send
+    // `display: undefined`, which drops out of the JSON and silently restores the
+    // API's own default of omitting the text.
+    return { type: "adaptive", display: this.config.thinkingDisplay ?? "summarized" };
+  }
+
   private _params(request: AiRequest, streaming: boolean): Record<string, unknown> {
     const model = request.model ?? this.config.model;
     const maxTokens =
       request.maxTokens ?? (streaming ? this.config.streamMaxTokens : this.config.maxTokens);
 
-    if (request.temperature !== undefined && modelRejectsSampling(model) && !this._warnedSampling) {
+    const capabilities = modelCapabilities(model);
+
+    if (request.temperature !== undefined && !capabilities.sampling && !this._warnedSampling) {
       this._warnedSampling = true;
       console.warn(
         `[Zerotal/ai] temperature was supplied but ${model} rejects temperature/top_p/top_k with ` +
-          `a 400. Dropping it. Use effort ('low' … 'max') to trade thoroughness for cost.`,
+          `a 400. Dropping it.` +
+          // Only suggest effort where effort exists. This advice used to be
+          // unconditional, and on the 4.5 models it named the one parameter that
+          // is guaranteed to 400 there — on models that accept the temperature it
+          // had just dropped.
+          (capabilities.effort
+            ? ` Use effort ('low' … 'max') to trade thoroughness for cost.`
+            : ""),
       );
     }
 
@@ -236,10 +291,26 @@ export class AnthropicDriver implements AiDriver {
       // by default on Claude Opus 5, so a budget sized for the prose truncates.
       max_tokens: maxTokens,
       messages: toAnthropicMessages(normalizeMessages(request)),
-      thinking: { type: "adaptive" },
-      output_config: { effort: request.effort ?? this.config.effort },
     };
 
+    // Sent where the model takes it. It never was, on any model: this driver
+    // warned about dropping `temperature` and then had no branch that set it, so
+    // `AiRequest.temperature` and the configured default were both inert. The old
+    // sampling predicate hid it by warning for almost every model, which made the
+    // silence look deliberate on the few it did not warn for.
+    if (capabilities.sampling) {
+      const temperature = request.temperature ?? this.config.temperature;
+      if (temperature !== undefined) params["temperature"] = temperature;
+    }
+
+    // Both of these are 400s on a model that does not take them, so they are added
+    // only where they are accepted rather than sent everywhere and hoped for.
+    if (capabilities.effort) {
+      params["output_config"] = { effort: request.effort ?? this.config.effort };
+    }
+    const thinking = this._thinking(capabilities, maxTokens);
+    if (thinking) params["thinking"] = thinking;
+
     const system = this._system(request);
     if (system) params["system"] = system;
 

package/src/drivers/OllamaDriver.ts

@@ -128,8 +128,10 @@ export class OllamaDriver implements AiDriver {
   }
 
   /** Ollama reports `prompt_eval_count` only after generating. 0 means unknown. */
-  async countTokens(_request: AiRequest): Promise<number> {
-    return 0;
+  async countTokens(_request: AiRequest): Promise<number | null> {
+    // Ollama exposes no token-counting endpoint. `null`, not 0 — the caller can
+    // tell "cannot count" from "counted nothing".
+    return null;
   }
 
   async verify(): Promise<DriverStatus> {

package/src/drivers/OpenAiDriver.ts

@@ -153,8 +153,10 @@ export class OpenAiDriver implements AiDriver {
    * tokenizer would be a guess dressed as a number. 0 means "unknown"; the spend
    * guard falls back to a labelled character approximation.
    */
-  async countTokens(_request: AiRequest): Promise<number> {
-    return 0;
+  async countTokens(_request: AiRequest): Promise<number | null> {
+    // OpenAI exposes no token-counting endpoint. `null`, not 0 — the caller can
+    // tell "cannot count" from "counted nothing".
+    return null;
   }
 
   async verify(): Promise<DriverStatus> {

package/src/errors.ts

@@ -94,6 +94,28 @@ export class AiDriverUnavailableError extends AiError {
       false,
     );
   }
+
+  /**
+   * The variant for an app that has configured no AI at all.
+   *
+   * Deliberately this class rather than a new one. "No driver is installed" and "no
+   * driver is configured" are the same fact to a caller — AI cannot answer here, and
+   * will not start being able to mid-process — and every consumer's handling is
+   * already written against the four permanent classes. A fifth would fall outside
+   * it silently, which is the failure mode a shared error taxonomy exists to prevent.
+   *
+   * @param requested - The driver name that was asked for.
+   */
+  static notConfigured(requested: string): AiDriverUnavailableError {
+    const error = new AiDriverUnavailableError(requested, "a provider SDK");
+    return Object.assign(error, {
+      message:
+        `[Zerotal/ai] No AI driver is configured, so there is nothing to generate with. ` +
+        `This is a supported state — an app can ship with AI off. Add a driver under ` +
+        `'drivers' in config/ai.ts to turn it on.`,
+      context: { requested, configured: [] as string[] },
+    });
+  }
 }
 
 /**

package/src/index.ts

@@ -58,6 +58,8 @@ export { AiGenerationJob } from "./AiGenerationJob.ts";
 
 // Cost estimation — extend the table for a model this package does not price.
 export { estimateCost, modelPrice, registerModelPrice, modelRejectsSampling } from "./pricing.ts";
+export { modelCapabilities } from "./modelCapabilities.ts";
+export type { ModelCapabilities } from "./modelCapabilities.ts";
 export type { ModelPrice } from "./pricing.ts";
 
 // Spend ledger

package/src/modelCapabilities.ts

@@ -0,0 +1,105 @@
+/**
+ * What each Anthropic model will actually accept on a request.
+ *
+ * The driver used to send `output_config.effort` and `thinking: { type: "adaptive" }`
+ * on every call, and decide sampling with one regex. That was right for the current
+ * generation and wrong for everything older, in a way that had the package
+ * contradicting itself: `claude-haiku-4-5` is in the pricing table — so the package
+ * presents it as supported — and the driver could not successfully call it, because
+ * `effort` is a 400 on that model and `adaptive` thinking is not a shape it takes.
+ *
+ * The two mistakes compounded. On Haiku 4.5 the driver dropped a `temperature` the
+ * model accepts perfectly well, and told the user to reach for `effort` instead —
+ * the one parameter guaranteed to fail there.
+ *
+ * ## Why the exceptions are listed and the default is current
+ *
+ * The obvious fix is an allowlist of models that behave the modern way, and it is the
+ * wrong one: it needs an edit every time a model ships, and until that edit lands a
+ * brand-new model is treated as legacy. Anthropic's direction of travel is *towards*
+ * this shape, so the models that differ are a closed set that ages out rather than an
+ * open one that grows.
+ *
+ * So: the older models are named, and anything unrecognised is assumed to behave like
+ * the current generation. A new model works on the day it ships.
+ *
+ * @module
+ */
+
+/** What a model accepts on a request. */
+export interface ModelCapabilities {
+  /**
+   * Accepts `temperature` / `top_p` / `top_k`.
+   *
+   * These became a 400 on the current generation; they are fine on 4.6 and below.
+   */
+  sampling: boolean;
+  /**
+   * Accepts `output_config.effort`.
+   *
+   * A 400 on the 4.5 generation, which has no equivalent knob.
+   */
+  effort: boolean;
+  /**
+   * How this model takes extended thinking.
+   *
+   * - `"adaptive"` — `{ type: "adaptive" }`, the model decides how much to spend.
+   * - `"budget"` — `{ type: "enabled", budget_tokens: N }`, an explicit allowance.
+   * - `null` — the model has no thinking mode and the field must be omitted.
+   */
+  thinking: "adaptive" | "budget" | null;
+}
+
+/**
+ * The current generation's shape, and the default for anything unrecognised.
+ *
+ * A model this file has never heard of is far more likely to be newer than these
+ * than older, because the older ones are already named below.
+ */
+const CURRENT: ModelCapabilities = { sampling: false, effort: true, thinking: "adaptive" };
+
+/**
+ * Models that differ from {@link CURRENT}, by exact id.
+ *
+ * A closed set: these age out of use, and nothing new joins them. That is the whole
+ * reason the table is written as exceptions rather than as an allowlist.
+ */
+const EXCEPTIONS: Record<string, ModelCapabilities> = {
+  // 4.6 was the last generation to accept sampling parameters. Effort and adaptive
+  // thinking both work.
+  "claude-opus-4-6": { sampling: true, effort: true, thinking: "adaptive" },
+  "claude-sonnet-4-6": { sampling: true, effort: true, thinking: "adaptive" },
+
+  // The 4.5 generation predates `output_config` entirely and wants an explicit
+  // thinking budget. Sampling is fine.
+  "claude-opus-4-5": { sampling: true, effort: false, thinking: "budget" },
+  "claude-sonnet-4-5": { sampling: true, effort: false, thinking: "budget" },
+  "claude-haiku-4-5": { sampling: true, effort: false, thinking: "budget" },
+};
+
+/**
+ * What this model accepts.
+ *
+ * Non-Anthropic model ids are reported as accepting sampling and nothing
+ * Anthropic-specific, because the Anthropic request shape is the only thing this
+ * describes — an Ollama or OpenAI model reaches a different driver that builds its
+ * own request.
+ *
+ * @param model - Exact model id, e.g. `claude-sonnet-5`.
+ */
+export function modelCapabilities(model: string): ModelCapabilities {
+  if (!model.startsWith("claude-")) {
+    return { sampling: true, effort: false, thinking: null };
+  }
+  return EXCEPTIONS[model] ?? CURRENT;
+}
+
+/**
+ * Whether a model rejects `temperature` / `top_p` / `top_k` with a 400.
+ *
+ * @param model - Exact model id.
+ * @returns `true` when sampling parameters must be dropped.
+ */
+export function modelRejectsSampling(model: string): boolean {
+  return !modelCapabilities(model).sampling;
+}

package/src/pricing.ts

@@ -30,7 +30,10 @@ const PRICES: Record<string, ModelPrice> = {
   "claude-opus-4-8": { input: 5, output: 25 },
   "claude-opus-4-7": { input: 5, output: 25 },
   "claude-opus-4-6": { input: 5, output: 25 },
-  "claude-sonnet-5": { input: 3, output: 15 },
+  // Sonnet 5 carried Sonnet 4.6's row — 3/15 — until 1.11.2. Every other family
+  // got its own number and this one was copied, so the ceiling refused requests
+  // that were 50% inside their budget and blamed the budget.
+  "claude-sonnet-5": { input: 2, output: 10 },
   "claude-sonnet-4-6": { input: 3, output: 15 },
   "claude-haiku-4-5": { input: 1, output: 5 },
 };
@@ -75,16 +78,9 @@ export function estimateCost(model: string, usage: AiUsage): number {
   );
 }
 
-/**
- * Whether a Claude model rejects `temperature` / `top_p` / `top_k` with a 400.
- *
- * Unknown models answer `true`. The removal has only ever gone one way, and the
- * two failure modes are not symmetric: guessing "rejects" costs a dropped
- * parameter the API would have ignored anyway, while guessing "accepts" fails
- * every single request against a model released after this line was written.
- */
-export function modelRejectsSampling(model: string): boolean {
-  // Opus 4.6 and Sonnet 4.6 were the last Claude models to accept sampling
-  // parameters; everything before them predates the models this package targets.
-  return !/^claude-(opus|sonnet)-4-6\b/.test(model) && model.startsWith("claude-");
-}
+// Re-exported from its new home so existing imports keep working. The predicate is
+// derived from the capability table now rather than from a regex over model ids —
+// see `modelCapabilities.ts` for why the exceptions are listed and the default is
+// the current generation.
+export { modelRejectsSampling, modelCapabilities } from "./modelCapabilities.ts";
+export type { ModelCapabilities } from "./modelCapabilities.ts";

package/src/schema.ts

@@ -44,7 +44,11 @@ function defOf(value: FieldRule | FieldRuleDefinition): FieldRuleDefinition {
   return "_def" in value ? value._def : value;
 }
 
-/** Normalise either input shape to raw definitions. */
+/** Normalise either input shape to raw definitions.
+ *
+ * @internal Normalisation between the two accepted input shapes. No caller anywhere, in this
+ * package or out of it — an app declares a schema; it never converts one.
+ */
 export function toSchema(input: SchemaInput): Schema {
   const out: Schema = {};
   for (const [key, value] of Object.entries(input)) out[key] = defOf(value);
@@ -212,6 +216,8 @@ function withStringKeywords(base: JsonSchema, def: FieldRuleDefinition): JsonSch
  * @example
  * strippedConstraints({ title: rule.string().min(3).max(80) });
  * // → ["title: min", "title: max"]
+ *
+ * @internal A diagnostic for the translation layer, called by nothing but its own test.
  */
 export function strippedConstraints(input: SchemaInput): string[] {
   const out: string[] = [];

package/src/spend.ts

@@ -48,7 +48,13 @@ export function recordSpend(model: string, usage: AiUsage): number {
   return cost;
 }
 
-/** Reset the ledger. Tests, and the `ai:spend --reset` path. */
+/**
+ * Reset the ledger.
+ *
+ * @internal Backs `ai:spend --reset` and this package's own tests. An app's test
+ * wanting spend isolation should reach for `AiFake`, which is the seam built for
+ * it; this one reaches past the manager into module state.
+ */
 export function resetSpend(): void {
   _day = today();
   _spentUsd = 0;
@@ -90,11 +96,27 @@ export function assertWithinLimits(
   });
 
   if (worstCase > limits.perRequestUsd) {
+    // The price is named because the table is a thing that can be wrong, and when
+    // it is, this refusal is the only symptom. A row carrying its predecessor's
+    // number once made the ceiling reject requests comfortably inside a budget, and
+    // the message said "spend limit" — which sends someone to their config rather
+    // than to the row that is 50% high. Quoting the rate makes a bad table legible
+    // from the error, and `registerModelPrice` is how it gets corrected without
+    // waiting for a release.
+    const price = modelPrice(model)!;
     throw new AiSpendLimitError(
       `This request could cost up to $${worstCase.toFixed(4)}, over the per-request ceiling of ` +
         `$${limits.perRequestUsd.toFixed(4)}. Shorten the prompt, lower maxTokens, or raise ` +
-        `limits.perRequestUsd in config/ai.ts.`,
-      { model, estimatedInputTokens, maxOutputTokens, worstCaseUsd: worstCase },
+        `limits.perRequestUsd in config/ai.ts. ` +
+        `Priced at $${price.input}/$${price.output} per million tokens for ${model} — if that is ` +
+        `not what you are billed, correct it with registerModelPrice() rather than raising the ceiling.`,
+      {
+        model,
+        estimatedInputTokens,
+        maxOutputTokens,
+        worstCaseUsd: worstCase,
+        priceUsdPerMillion: price,
+      },
     );
   }
 }

package/src/stats.ts

@@ -96,7 +96,10 @@ export function refusalRate(): number {
   return _deliveries.filter((d) => d.refused).length / _deliveries.length;
 }
 
-/** Reset the buffer. Tests. */
+/** Reset the buffer. Tests.
+ *
+ * @internal A test helper, as `resetSpend` is.
+ */
 export function resetStats(): void {
   _deliveries.length = 0;
 }

package/src/types.ts

@@ -232,6 +232,20 @@ export interface AnthropicConfigShape {
   /** Cap for streaming calls, where HTTP timeouts are not a concern. */
   streamMaxTokens: number;
   effort: AiEffort;
+  /**
+   * Whether a streamed `thinking` chunk carries text.
+   *
+   * The API defaults this to `"omitted"` on the current generation, which is why
+   * the documented `thinking` stream chunk used to fire forever with `text: ""` —
+   * thinking happened, and was billed, and nothing was emitted. It defaulted to
+   * `"summarized"` on the 4.6 models, so a "thinking…" view built against those
+   * worked and then silently stopped working as people moved forward.
+   *
+   * Defaults to `"summarized"` here, because a documented channel that is always
+   * empty is worse than one that costs a little to fill. Set `"omitted"` to get
+   * the API's own default back — the thinking still happens either way.
+   */
+  thinkingDisplay: "summarized" | "omitted";
   /** Route a safety refusal to Anthropic's recommended fallback model. */
   fallbacks: boolean;
   /** Mark the system prompt cacheable. The cheapest win available. */