@aria-framework/ai 0.26.0 → 0.27.0

package/README.md

@@ -35,7 +35,7 @@ const ai = createAiClient({
 const r = await ai.complete({
   system, messages, maxTokens: 400,
   schema,                 // optional: constrained JSON
-  // reasoning: 'full',   // optional, lmx only: let the model think fully (see Reasoning below)
+  // reasoning: 'full',   // optional, every provider: 'off' (default) or 'full' (see Reasoning below)
 });
 // r.text, r.json (when schema), r.model, r.usage.total, r.ms
 ```
@@ -44,6 +44,12 @@ Every failure is thrown as an `AiError` with a `kind`: `disabled`, `unconfigured
 `timeout`, `auth`, `rate_limit`, `bad_response` or `refused`. The `message` is written for
 an admin screen and never includes a URL or key.
 
+**A failed call that spent tokens is still metered** (0.26.1). When the model answered but the answer
+was unusable (it thought until the limit, or a structured reply was cut off), the error carries
+`usage` (`{ prompt, completion, total }`) and `budget.record(cfg, { usage, model, ms, failed: true }, meta)`
+is called before the error is thrown. A failure that spent nothing (refused, unreachable, timeout)
+records nothing. If `record` throws, the original error still reaches the caller.
+
 `providerStore`, `usageStore`, `speedStore` and `lmxStore` are optional db-worker-backed
 stores. Each exports a `schemaFor(dialect)`, so the app's migration can be checked against it.
 
@@ -63,7 +69,7 @@ to write yourself:
 | Engine URLs come from the document | Resolved on every call, and never stored |
 | A status outage is not an inference outage | Keeps routing on the last good document for 3 minutes (`staleMs`), logging loudly |
 | Pin the certificate; never disable verification | Uses an undici `Agent({ connect: { ca } })` per stack. Never `NODE_EXTRA_CA_CERTS`, never `rejectUnauthorized:false` |
-| Choose the reasoning flag from the model | By default thinking is kept to a minimum: `qwen` → `chat_template_kwargs.enable_thinking=false`, `gpt-oss` → `reasoning_effort:'low'`, anything else gets neither (with a warning). `reasoning: 'full'` on the call (since 0.26.0) sends `enable_thinking=true` / `reasoning_effort:'high'` instead. The flag always overrides a raw `extra`; only the named option changes it. See [Reasoning](#reasoning-reasoning-full) |
+| Choose the reasoning flag from the model | By default thinking is kept to a minimum: `qwen` → `chat_template_kwargs.enable_thinking=false`, `gpt-oss` → `reasoning_effort:'low'`, anything else gets neither (with a warning). `reasoning: 'full'` on the call (since 0.26.0) sends `enable_thinking=true` / `reasoning_effort:'high'` instead. The flag always overrides a raw `extra`; only the named option changes it. Since 0.27.0 the same rule applies to every provider. See [Reasoning](#reasoning-reasoning-off--full) |
 | Size requests against `maxInputTokens` (per slot) | `contextTokens` is taken from the engine, not from config |
 | Identity is `(instance, id)`, falling back to `name` | `lmx.engineId` is matched first; `rekeyPlan()` migrates rows when ids are minted or engines renamed |
 | A `429` is about the key, not the engine | Fails fast (since 0.25.0): throws `rate_limit` with `lmxSkip: 'lmx_throttled'` and `retryAfterMs`. The client never waits; whether to wait or move on is the caller's decision |
@@ -170,10 +176,11 @@ instead:
 Failover across several engines for one job is the app's job; lmx provides none. List
 endpoints in preference order and take the first one that serves.
 
-### Reasoning (`reasoning: 'full'`)
+### Reasoning (`reasoning: 'off' | 'full'`)
 
-By default the adapter makes the model think as little as its family allows, so a quick answer
-stays quick. Pass `reasoning: 'full'` on a `complete()` call to let the model think fully:
+How much a model may think is decided by the **app, per call**, and every provider honours it (since
+0.27.0; before that only lmx did). Leave it out, or pass `reasoning: 'off'`, and the model thinks as
+little as its family allows, so a quick answer stays quick. Pass `reasoning: 'full'` to let it think:
 
 ```js
 const r = await ai.complete({
@@ -198,23 +205,50 @@ a `bad_response` AiError saying it ran out of room (and, when the server says so
 tokens went on internal reasoning), but the work is lost either way. Use **`maxTokens` ≥ 4096** and a
 **`timeoutMs` ≥ 120 s** (120000) on the endpoint, or the deadline cuts the answer off first.
 
-**What is sent, per model family** (read from the model the engine is running on each call):
+**lmx, openai-compatible and lmstudio: what is added to the request body, per model family.** The
+family is read from the model the engine is running (lmx) or the endpoint's model name (others):
 
-| Family | Default (no `reasoning`) | `reasoning: 'full'` |
+| Family | `'off'` (the default) | `reasoning: 'full'` |
 |---|---|---|
 | qwen | `{"chat_template_kwargs":{"enable_thinking":false}}` | `{"chat_template_kwargs":{"enable_thinking":true}}` |
 | gpt-oss | `{"reasoning_effort":"low"}` | `{"reasoning_effort":"high"}` |
-| anything else | nothing (warning logged) | nothing (warning logged that `'full'` could not be honoured) |
+| anything else | nothing (lmx logs a warning) | nothing (a warning that `'full'` could not be honoured) |
+
+**LM Studio ignores `chat_template_kwargs`** (measured live: Qwen3 thought just as long with
+`enable_thinking: false`). So on **`provider: 'lmstudio'`** a qwen model gets two more switches. One is
+`{"reasoning_effort":"none"}` for `'off'` and `{"reasoning_effort":"high"}` for `'full'`: verified live, but
+LM Studio documents `reasoning_effort` only for gpt-oss. The other is Qwen's own documented prompt switch,
+`/no_think` for `'off'` and `/think` for `'full'`, appended to the system prompt (or sent as one when there
+is none): documented on LM Studio's Qwen3 model pages, but only hybrid Qwen3 reads it. Both are sent, so
+if a future LM Studio drops one the other still holds. Configure an LM Studio server as `lmstudio`, not
+`openai-compatible`; as `openai-compatible` it keeps thinking on every call. Plain `openai-compatible`
+gets neither, because vLLM validates `reasoning_effort` and may refuse `'none'`.
+
+**anthropic: what is sent, per Claude generation.** The Messages API differs by generation: Opus 5.5
+and Fable cannot turn thinking off (effort is the only lever), Sonnet 5.5 turns it off with
+`between_tools`, and several current models refuse `temperature`, so none is sent to them.
+
+| Models | `'off'` (the default) | `reasoning: 'full'` | temperature |
+|---|---|---|---|
+| claude-fable / claude-opus-5-5 | `{"output_config":{"effort":"low"}}` | `{"output_config":{"effort":"high"}}` | not sent |
+| claude-opus-5 | `{"output_config":{"effort":"low"}}` | `{"thinking":{"type":"adaptive"},"output_config":{"effort":"high"}}` | not sent |
+| claude-sonnet-5-5 | `{"thinking":{"type":"between_tools"}}` | `{"thinking":{"type":"adaptive"},"output_config":{"effort":"high"}}` | not sent |
+| claude-sonnet-5 | `{"thinking":{"type":"disabled"}}` | `{"thinking":{"type":"adaptive"},"output_config":{"effort":"high"}}` | not sent |
+| claude-opus-4-7 / 4-8 | nothing | `{"thinking":{"type":"adaptive"},"output_config":{"effort":"high"}}` | not sent |
+| claude-*-4-6 | nothing | `{"thinking":{"type":"adaptive"},"output_config":{"effort":"high"}}` | sent |
+| claude-*-4-5 and older | nothing | thinking enabled with a budget of `maxTokens` (at least 1024), added on top of `max_tokens` | sent; not sent with `'full'` |
+| anything else | nothing | nothing (a warning that `'full'` could not be honoured) | sent |
+
+`effort` is merged into any `output_config` the structured-output schema already put there.
 
 Rules:
 
-- `'full'` is the only value. Leaving the option out (or `null`) means the default. Any other value,
-  for example `'high'`, `true` or `''`, is refused with `AiError` kind `refused` before any
+- The values are `'off'` and `'full'`. Leaving the option out (or `null`) means `'off'`. Any other
+  value, for example `'high'`, `true` or `''`, is refused with `AiError` kind `refused` before any
   request is made, whichever provider the endpoint uses.
 - The flag is merged **after** `extra`, so a raw `extra: { chat_template_kwargs: … }` or
-  `extra: { reasoning_effort: … }` cannot change it. Only `reasoning` can.
-- Only `lmx` honours it. On `openai-compatible`, `lmstudio` or `anthropic` the client logs a
-  warning, removes the option, and nothing reaches that provider's request body.
+  `extra: { reasoning_effort: … }` cannot change it. Only `reasoning` can. The option itself is never
+  copied into a request body.
 - `REASONING_MODES` (package root) lists the accepted values for an app that validates its own
   settings.
 

package/index.js

@@ -26,7 +26,7 @@ const facts = require('./facts');
 const { AiError, fromFetchFailure, redact } = require('./error');
 const { polish } = require('./polish');
 const { generate } = require('./generate');
-const { assertReasoning, REASONING_MODES } = require('./providers/lmx');
+const { assertReasoning, REASONING_MODES } = require('./reasoning');
 
 const PROVIDERS = {
   // 'lmstudio' and 'openai-compatible' are the SAME adapter with different defaults — a kindness to
@@ -52,9 +52,6 @@ const DEFAULTS = {
 const RETRY_AFTER_MS = 400;
 const RETRY_ONLY_IF_FAILED_WITHIN_MS = 5000;
 
-/** Providers already warned that they ignore `reasoning` — once per provider per process. */
-const warnedReasoning = new Set();
-
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 const NOOP_BUDGET = { async assertWithinBudget() {}, async record() {} };
 
@@ -106,7 +103,7 @@ function createAiClient(deps = {}) {
    * Ask the configured model for something.
    * @param {{system?:string, messages:Array, maxTokens?:number, temperature?:number,
    *          schema?:object, signal?:AbortSignal, ticketId?:*, skipBudget?:boolean,
-   *          reasoning?:'full'}} opts
+   *          reasoning?:'off'|'full'}} opts
    * @param {object} [cfgOverride] the resolved config, when the caller already has it
    */
   async function complete(opts, cfgOverride) {
@@ -134,22 +131,31 @@ function createAiClient(deps = {}) {
     // by whichever caller forgets. `skipBudget` is for the admin's Test connection; it still records.
     if (!opts.skipBudget) await meter.assertWithinBudget(cfg, { ticketId: opts.ticketId });
 
-    // ONLY lmx HONOURS `reasoning`. Elsewhere it is warned about and removed, so no other adapter's
-    // request body can ever carry it.
-    let callOpts = opts;
-    if (opts.reasoning != null && cfg.provider !== 'lmx') {
-      if (!warnedReasoning.has(cfg.provider)) {
-        warnedReasoning.add(cfg.provider);
-        log.warn(`AI: reasoning '${opts.reasoning}' is honoured only by lmx engines — `
-          + `${cfg.label || cfg.provider} sends no reasoning flag and runs on its own default `
-          + '(warned once per provider).');
+    // EVERY PROVIDER HONOURS `reasoning` (0.27.0): each adapter translates it for its model family
+    // (see reasoning.js). It used to be lmx-only, warned about and stripped everywhere else.
+    const callOpts = opts;
+
+    const started = Date.now();
+    let result;
+    try {
+      result = await withOneRetry(() => adapter.complete(cfg, callOpts), opts);
+    } catch (err) {
+      // A FAILED CALL CAN STILL HAVE SPENT TOKENS (0.26.1) — a model that thought until it ran out of
+      // room, a structured reply cut off mid-bracket. Recording only successes let a benchmark or a
+      // connection test on such a model run outside the ceiling. Adapters put normalised usage on
+      // the error; a failure that spent nothing (refused, unreachable) carries none and is not counted.
+      // The ledger failing must never replace the error the caller needs to see.
+      if (err && err.usage && err.usage.total > 0) {
+        try {
+          await meter.record(cfg, { usage: err.usage, model: cfg.model, ms: Date.now() - started, failed: true },
+            { ticketId: opts.ticketId });
+        } catch (recErr) {
+          log.warn(`AI: usage of a failed call not recorded (${recErr.message})`);
+        }
       }
-      const { reasoning: _ignored, ...rest } = opts;
-      callOpts = rest;
+      throw err;
     }
 
-    const result = await withOneRetry(() => adapter.complete(cfg, callOpts), opts);
-
     // ...and the counter after it, AWAITED: two calls in quick succession must both be counted
     // before the second's ceiling check reads the total, or the limit is enforced against a stale one.
     await meter.record(cfg, result, { ticketId: opts.ticketId });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aria-framework/ai",
-  "description": "Aria App Framework \u2014 AI module. A dependency-injected model seam (createAiClient) over several providers (LM Studio / OpenAI-compatible / Anthropic), with a fact-preservation guard, generic Polish and Generate writing engines, and a browser polish widget. Prompts and config stay in the consuming app.",
-  "version": "0.26.0",
+  "description": "Aria App Framework — AI module. A dependency-injected model seam (createAiClient) over several providers (LM Studio / OpenAI-compatible / Anthropic), with a fact-preservation guard, generic Polish and Generate writing engines, and a browser polish widget. Prompts and config stay in the consuming app.",
+  "version": "0.27.0",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {
@@ -29,6 +29,7 @@
     "providers/lmxDiscovery.js",
     "providers/lmxTransport.js",
     "providers/openai-compatible.js",
+    "reasoning.js",
     "speedStore.js",
     "untrusted.js",
     "usageStore.js",
@@ -47,7 +48,7 @@
     }
   },
   "scripts": {
-    "test": "node test/smoke.js && node test/usageStore.js && node test/providerStore.js && node test/speedStore.js && node test/health.js && node test/listModels.js && node test/benchmark.js && node test/lmxDiscovery.js && node test/lmx.js && node test/lmxVerify.js && node test/lmxStore.js && node test/lmxStatus.js && node test/jobCard.js && node test/untrusted.js && node test/packaging.js && node test/views.js && node test/fenced.js && node test/polish.js && node test/reasoning.js",
+    "test": "node test/smoke.js && node test/usageStore.js && node test/providerStore.js && node test/speedStore.js && node test/health.js && node test/listModels.js && node test/benchmark.js && node test/lmxDiscovery.js && node test/lmx.js && node test/lmxVerify.js && node test/lmxStore.js && node test/lmxStatus.js && node test/jobCard.js && node test/untrusted.js && node test/packaging.js && node test/views.js && node test/fenced.js && node test/polish.js && node test/reasoning.js && node test/reasoningProviders.js && node test/usageOnFailure.js",
     "prepublishOnly": "node ../../test/packaging.js ai"
   },
   "devDependencies": {

package/providers/anthropic.js

@@ -19,6 +19,7 @@
 'use strict';
 
 const { AiError, fromFetchFailure, redact } = require('../error');
+const { anthropicReasoning } = require('../reasoning');
 
 const API_VERSION = '2023-06-01';
 const DEFAULT_BASE = 'https://api.anthropic.com/v1';
@@ -60,6 +61,22 @@ async function complete(cfg, opts) {
     if (beta) headers['anthropic-beta'] = beta;
   }
 
+  // HOW MUCH CLAUDE MAY THINK (0.27.0) — per model generation, because the API differs by
+  // generation (see ../reasoning.js). Absent means 'off'. An unknown model keeps the pre-0.27 body.
+  const r = anthropicReasoning(cfg.model, opts.reasoning, body.max_tokens);
+  if (r) {
+    if (r.thinking) body.thinking = r.thinking;
+    // Merged into output_config, which may already carry the structured-output format.
+    if (r.effort) body.output_config = { ...(body.output_config || {}), effort: r.effort };
+    // Several current models reject temperature outright, and extended thinking on older ones
+    // requires the default. Sending it would be a 400, so it is left out.
+    if (!r.sendTemperature) delete body.temperature;
+    body.max_tokens = r.maxTokens;
+  } else if (opts.reasoning === 'full' && cfg.logger) {
+    cfg.logger.warn(`${label}: reasoning 'full' was asked for, but model "${cfg.model}" is not in the `
+      + 'known Claude generations — sending no thinking setting; the model runs on its own default.');
+  }
+
   const started = Date.now();
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), cfg.timeoutMs || 60000);
@@ -97,6 +114,13 @@ async function complete(cfg, opts) {
     clearTimeout(timer);
   }
 
+  // A 200 WHOSE BODY IS `null` (0.26.1) is a typed failure, not a TypeError further down.
+  if (!payload || typeof payload !== 'object') {
+    throw new AiError('bad_response', `${label} answered with an empty body.`);
+  }
+  // Spent tokens ride on every later error so the client can meter a failed call (0.26.1).
+  const usage = normaliseUsage(payload.usage);
+
   // Difference 4: blocks, not a single string. Concatenated so a model that splits its answer over
   // two text blocks does not silently lose the second one.
   // Thinking arrives as its own block TYPE here rather than a field, so filtering to 'text' already
@@ -109,7 +133,7 @@ async function complete(cfg, opts) {
     const thought = (payload.content || []).some((b) => b && b.type === 'thinking');
     throw new AiError('bad_response', thought
       ? `${label} returned only its internal reasoning. Raise the reply limit and try again.`
-      : `${label} returned no text (stop reason: ${payload.stop_reason || 'none given'}).`);
+      : `${label} returned no text (stop reason: ${payload.stop_reason || 'none given'}).`, { usage });
   }
 
   let json = null;
@@ -121,10 +145,10 @@ async function complete(cfg, opts) {
       if (payload.stop_reason === 'max_tokens') {
         throw new AiError('bad_response',
           `${label} ran out of room mid-answer — the structured reply was cut off before it was ` +
-          'finished. A Regenerate usually succeeds.', { cause: err });
+          'finished. A Regenerate usually succeeds.', { cause: err, usage });
       }
       throw new AiError('bad_response',
-        `${label} was asked for structured output and returned text that will not parse.`, { cause: err });
+        `${label} was asked for structured output and returned text that will not parse.`, { cause: err, usage });
     }
   }
 
@@ -132,7 +156,7 @@ async function complete(cfg, opts) {
     text,
     json,
     model: payload.model || cfg.model,
-    usage: normaliseUsage(payload.usage),
+    usage,
     ms: Date.now() - started,
     finishReason: payload.stop_reason || null,
     truncated: payload.stop_reason === 'max_tokens',

package/providers/lmx.js

@@ -137,56 +137,15 @@ function skipError(name, res) {
 }
 
 /**
- * THE REASONING FLAG IS A PROPERTY OF THE MODEL, NOT OF THE ENGINE OR THE JOB.
- *
- * Both families reason before answering, and each needs a different instruction to stop. Getting it
- * wrong costs the whole budget and returns nothing — `content: ""` with `finish_reason: "length"`,
- * no error, and a retry produces the same nothing.
+ * THE REASONING FLAG IS A PROPERTY OF THE MODEL, NOT OF THE ENGINE.
  *
  * Read from the live document every call, never stored: point an engine at a different model and
- * the correct flag changes underneath a configuration that never changed.
- *
- * An UNRECOGNISED family gets NEITHER flag. Guessing would be worse than not guessing — sending a
- * Qwen argument to a model that ignores it wastes the budget silently, which is the failure this
- * exists to avoid.
- *
- * THE DEFAULT IS "THINK AS LITTLE AS THE FAMILY ALLOWS"; `reasoning: 'full'` (0.26.0) is the one
- * named way to ask for the opposite — Qwen thinking on, gpt-oss effort high — for judgement work
- * (triage) where a thinking-off answer measured as a different product. It is a NAMED per-call
- * option rather than a raw `extra`, because the forced flag deliberately outranks `extra`: a stray
- * passthrough must never be able to turn thinking on and spend a budget sized for a quick answer.
- */
-const REASONING_MODES = Object.freeze(['full']);
-
-/**
- * Refuse a `reasoning` value this package does not define. `undefined`/`null` mean the default.
- * Anything else — 'high', 'Full', true, '' — is a caller's mistake, and silently treating it as the
- * default would hand a triage caller a thinking-off answer while it believed it had asked for more.
- */
-function assertReasoning(value) {
-  if (value === undefined || value === null) return;
-  if (!REASONING_MODES.includes(value)) {
-    throw new AiError('refused',
-      `Unknown reasoning option ${JSON.stringify(value)}. The only value is `
-      + `${REASONING_MODES.map((m) => `'${m}'`).join(', ')}; leave it out for the default.`);
-  }
-}
-
-/**
- * The families with a known flag, in match order. A TABLE rather than a chain of ifs so the README
- * test can enumerate it: a family added here and not documented fails that test.
+ * the correct flag changes underneath a configuration that never changed. The table and the modes
+ * moved to ../reasoning.js in 0.27.0, when every provider started honouring `reasoning`; they are
+ * re-exported below so existing imports keep working. openai-compatible applies the flag, from the
+ * engine's model (`reasoningModel` on the engine config) — one place decides what is sent.
  */
-const REASONING_FAMILIES = Object.freeze([
-  { family: 'qwen', match: /qwen/, flag: (full) => ({ chat_template_kwargs: { enable_thinking: full } }) },
-  { family: 'gpt-oss', match: /gpt-oss/, flag: (full) => ({ reasoning_effort: full ? 'high' : 'low' }) }
-]);
-
-function reasoningFor(modelPath, mode) {
-  assertReasoning(mode);
-  const m = String(modelPath || '').toLowerCase();
-  const f = REASONING_FAMILIES.find((x) => x.match.test(m));
-  return f ? f.flag(mode === 'full') : null;
-}
+const { REASONING_MODES, REASONING_FAMILIES, assertReasoning, reasoningFor } = require('../reasoning');
 
 /** The config openai-compatible needs, once the address is known. */
 function engineConfig(cfg, url, engine) {
@@ -204,7 +163,10 @@ function engineConfig(cfg, url, engine) {
       : lmxTransport(cfg.lmx && cfg.lmx.ca),
     // SIZE AGAINST WHAT THE ENGINE REPORTS, not what somebody typed. maxInputTokens is PER SLOT,
     // because -c in llama.cpp is a pool divided across slots.
-    contextTokens: (engine && engine.maxInputTokens) || cfg.contextTokens
+    contextTokens: (engine && engine.maxInputTokens) || cfg.contextTokens,
+    // THE MODEL THE FLAG IS CHOSEN FROM — the one the engine is running, not the endpoint's model
+    // name (an lmx endpoint stores none). openai-compatible reads this before cfg.model.
+    reasoningModel: engine && engine.model
   };
 }
 
@@ -254,14 +216,10 @@ async function complete(cfg, opts) {
     );
   }
 
-  // The named option is consumed here; openai-compatible never sees it.
-  const { reasoning: _consumed, ...rest } = opts || {};
-  return openai.complete(engineConfig(cfg, res.url, res.engine), {
-    ...rest,
-    // Merged rather than replacing: a caller's own extras survive. The flag is spread LAST, so a
-    // raw extra can never override it — only the named `reasoning` option changes what it says.
-    extra: { ...(opts && opts.extra), ...(reasoning || {}) }
-  }).catch((err) => { throw tagThrottle(err); });
+  // The mode goes on to openai-compatible, which merges the flag AFTER `extra` (0.27.0) — so a raw
+  // extra still cannot override it, and the option itself never reaches the request body.
+  return openai.complete(engineConfig(cfg, res.url, res.engine), opts || {})
+    .catch((err) => { throw tagThrottle(err); });
 }
 
 async function embed(cfg, texts) {

package/providers/openai-compatible.js

@@ -12,6 +12,7 @@
 
 'use strict';
 
+const { reasoningFor, lmstudioPromptSwitch } = require('../reasoning');
 const { AiError, fromFetchFailure, redact } = require('../error');
 
 /**
@@ -65,6 +66,30 @@ async function complete(cfg, opts) {
     };
   }
 
+  // HOW MUCH THE MODEL MAY THINK (0.27.0), from the model family — the engine's model on lmx
+  // (`reasoningModel`), the configured name otherwise. Merged AFTER `extra`, so a raw passthrough
+  // cannot override it; only the named `reasoning` option changes it, and that option is never
+  // copied into the body itself. Absent means 'off': before 0.27.0 an LM Studio endpoint running
+  // Qwen3 reasoned on every call by default, spending budgets sized for a quick answer.
+  const flag = reasoningFor(cfg.reasoningModel || cfg.model, opts.reasoning, cfg.provider);
+  if (flag) Object.assign(body, flag);
+  else if (opts.reasoning === 'full' && cfg.logger && !cfg.lmx) {
+    // lmx warns for itself, naming the engine; this is the plain-endpoint case.
+    cfg.logger.warn(`${label}: reasoning 'full' was asked for, but no reasoning flag is known for model `
+      + `"${cfg.model}" — sending none; the model runs on its own default.`);
+  }
+
+  // LM STUDIO ALSO GETS QWEN'S DOCUMENTED PROMPT SWITCH (see reasoning.js LMSTUDIO_PROMPT_SWITCH),
+  // on the system prompt — appended to the caller's own, or as one of its own when there is none.
+  const promptSwitch = lmstudioPromptSwitch(cfg.reasoningModel || cfg.model, opts.reasoning, cfg.provider);
+  if (promptSwitch) {
+    if (messages.length && messages[0].role === 'system' && typeof messages[0].content === 'string') {
+      messages[0] = { role: 'system', content: `${messages[0].content}\n\n${promptSwitch}` };
+    } else {
+      messages.unshift({ role: 'system', content: promptSwitch });
+    }
+  }
+
   const started = Date.now();
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), cfg.timeoutMs || 60000);
@@ -133,7 +158,13 @@ async function complete(cfg, opts) {
   // completion" — which sent this investigation after a thinking-model theory that was not the
   // cause. Verified against the real server: the same request on /v1/chat/completions answers
   // normally.
-  if (payload && payload.error && !payload.choices) {
+  // A 200 WHOSE BODY IS `null` (0.26.1) — valid JSON, no object. It used to reach `payload.usage`
+  // below as a TypeError, which a router reads as an unknown fault.
+  if (!payload || typeof payload !== 'object') {
+    throw new AiError('bad_response', `${label} answered with an empty body.`);
+  }
+
+  if (payload.error && !payload.choices) {
     const said = typeof payload.error === 'string'
       ? payload.error
       : (payload.error.message || JSON.stringify(payload.error));
@@ -170,6 +201,10 @@ async function complete(cfg, opts) {
     throw emptyCompletion({ label, finishReason, reasoning, maxTokens: body.max_tokens, usage: payload.usage });
   }
 
+  // TOKENS WERE SPENT EVEN WHEN THE ANSWER IS UNUSABLE (0.26.1). Carried on every error raised after
+  // this point, normalised, so the client can meter a failed call — see index.js complete().
+  const usage = normaliseUsage(payload.usage);
+
   // With a schema the content is still a STRING containing JSON — the server constrains the shape,
   // it does not parse for you. Parsing here rather than at each call site means a malformed body is
   // one error type instead of a surprise in a page render.
@@ -188,10 +223,10 @@ async function complete(cfg, opts) {
         throw new AiError('bad_response',
           `${label} ran out of room mid-answer (${body.max_tokens} tokens) — the structured reply ` +
           'was cut off before it was finished. If this repeats, the schema may be letting the ' +
-          'model ramble; a Regenerate usually succeeds.', { cause: err });
+          'model ramble; a Regenerate usually succeeds.', { cause: err, usage });
       }
       throw new AiError('bad_response',
-        `${label} was asked for structured output and returned text that will not parse.`, { cause: err });
+        `${label} was asked for structured output and returned text that will not parse.`, { cause: err, usage });
     }
   }
 
@@ -199,7 +234,7 @@ async function complete(cfg, opts) {
     text,
     json,
     model: payload.model || cfg.model,
-    usage: normaliseUsage(payload.usage),
+    usage,
     ms: Date.now() - started,
     finishReason,
     // A caller that cares (the summary's coverage line) can tell a complete answer from a cut-off
@@ -236,8 +271,9 @@ function unclosedThinking(text) {
  * payload, so they are distinguished: the budget ran out, the budget went on thinking, or the server
  * genuinely said nothing.
  */
-function emptyCompletion({ label, finishReason, reasoning, maxTokens, usage }) {
-  const spent = (usage && usage.completion_tokens) || 0;
+function emptyCompletion({ label, finishReason, reasoning, maxTokens, usage: raw }) {
+  const spent = (raw && raw.completion_tokens) || 0;
+  const usage = normaliseUsage(raw);
   if (finishReason === 'length' || (reasoning && !spentLeftRoom(spent, maxTokens))) {
     return new AiError('bad_response',
       `${label} ran out of room before it answered — it used all ${maxTokens} reply tokens` +
@@ -253,7 +289,7 @@ function emptyCompletion({ label, finishReason, reasoning, maxTokens, usage }) {
   }
   return new AiError('bad_response',
     `${label} returned an empty completion (finish reason: ${finishReason || 'none given'}). ` +
-    'Check the model is fully loaded on the server.');
+    'Check the model is fully loaded on the server.', { usage });
 }
 
 /** Did the completion stop well short of the ceiling? Then the ceiling was not the problem. */

package/reasoning.js

@@ -0,0 +1,176 @@
+/**
+ * How much a model may think — the one rule, for every provider (0.27.0).
+ *
+ * THE APP DECIDES, PER CALL: `complete({ reasoning: 'off' | 'full' })`. Absent or null means 'off'.
+ * Before 0.27.0 only lmx honoured this; an LM Studio or OpenAI-compatible endpoint running Qwen3 or
+ * gpt-oss reasoned on EVERY call (its server default) and spent budgets sized for a quick answer,
+ * and the client stripped the option with a warning. Now each adapter translates the mode into what
+ * its model family understands:
+ *
+ *   OpenAI-shaped (lmx, openai-compatible, lmstudio) — a request-body flag per model family.
+ *   Anthropic — `thinking` / `output_config.effort` per model generation, because the API differs by
+ *   generation: Claude Opus 5.5 and Fable cannot turn thinking off at all (effort is the only lever),
+ *   Sonnet 5.5 turns it off with `between_tools`, 4.6 and older take an explicit on-switch, and
+ *   several current models refuse `temperature` outright.
+ *
+ * 'off' IS "AS LITTLE AS THE FAMILY ALLOWS", not "zero": on a model that always thinks it is the
+ * lowest effort. An UNRECOGNISED family gets nothing — guessing a flag a model ignores wastes the
+ * budget silently, which is the failure this exists to avoid — and keeps the pre-0.27 request.
+ *
+ * A NAMED OPTION, NOT A RAW `extra`: the flag is merged after `extra`, so a stray passthrough can
+ * never turn thinking on and spend a budget sized for a quick answer.
+ */
+
+'use strict';
+
+const { AiError } = require('./error');
+
+const REASONING_MODES = Object.freeze(['off', 'full']);
+
+/**
+ * Refuse a `reasoning` value this package does not define. `undefined`/`null` mean 'off'.
+ * Anything else — 'high', 'Full', true, '' — is a caller's mistake, and silently treating it as the
+ * default would hand a triage caller a thinking-off answer while it believed it had asked for more.
+ */
+function assertReasoning(value) {
+  if (value === undefined || value === null) return;
+  if (!REASONING_MODES.includes(value)) {
+    throw new AiError('refused',
+      `Unknown reasoning option ${JSON.stringify(value)}. The values are `
+      + `${REASONING_MODES.map((m) => `'${m}'`).join(', ')}; leave it out for 'off'.`);
+  }
+}
+
+const isFull = (mode) => mode === 'full';
+
+/**
+ * OpenAI-shaped families with a known flag, in match order. A TABLE rather than a chain of ifs so
+ * the README test can enumerate it: a family added here and not documented fails that test.
+ */
+const REASONING_FAMILIES = Object.freeze([
+  { family: 'qwen', match: /qwen/, flag: (full) => ({ chat_template_kwargs: { enable_thinking: full } }) },
+  { family: 'gpt-oss', match: /gpt-oss/, flag: (full) => ({ reasoning_effort: full ? 'high' : 'low' }) }
+]);
+
+/**
+ * LM STUDIO IGNORES chat_template_kwargs. Measured live 4 Oct 2026 (LM Studio, qwen/qwen3-1.7b):
+ * `enable_thinking: false` thought for 216 tokens, the same as `true`. What it DOES honour is
+ * `reasoning_effort`: 'none' turns Qwen thinking off (3 tokens, 0.9 s against 250 tokens, 14 s),
+ * and every other value (minimal/low/medium/high) means "on", ungraded. So on `provider: 'lmstudio'`
+ * Qwen gets reasoning_effort as well. NOT on plain openai-compatible: vLLM validates that field and
+ * may refuse 'none', and llama.cpp / vLLM already honour the template kwarg (lmx proves it daily).
+ * gpt-oss needs nothing extra — reasoning_effort is already its own flag.
+ */
+const LMSTUDIO_EXTRA = Object.freeze({
+  qwen: (full) => ({ reasoning_effort: full ? 'high' : 'none' })
+});
+
+/**
+ * ...AND THE DOCUMENTED SWITCH, TOO. LM Studio documents no per-request reasoning field on its
+ * OpenAI-compatible endpoint for Qwen (reasoning_effort is documented for gpt-oss only); what it does
+ * document, on the Qwen3 model pages, is Qwen's own soft switch: `/no_think` (or `/think`) in the
+ * prompt. Both are sent (decided with Petrus 4 Oct 2026): the body field is verified live but
+ * undocumented, the prompt switch is documented but only hybrid Qwen3 reads it — if a future LM
+ * Studio drops one, the other still holds. Appended to the system prompt by openai-compatible.
+ */
+const LMSTUDIO_PROMPT_SWITCH = Object.freeze({
+  qwen: (full) => (full ? '/think' : '/no_think')
+});
+
+/** The prompt switch for an LM Studio model and mode, or null. */
+function lmstudioPromptSwitch(model, mode, provider) {
+  assertReasoning(mode);
+  if (provider !== 'lmstudio') return null;
+  const m = String(model || '').toLowerCase();
+  const f = REASONING_FAMILIES.find((x) => x.match.test(m));
+  const sw = f && LMSTUDIO_PROMPT_SWITCH[f.family];
+  return sw ? sw(isFull(mode)) : null;
+}
+
+/**
+ * The OpenAI-shaped body flag for a model (path or name), mode and provider, or null for an unknown
+ * family. `provider` matters only for 'lmstudio' (see LMSTUDIO_EXTRA).
+ */
+function reasoningFor(model, mode, provider) {
+  assertReasoning(mode);
+  const m = String(model || '').toLowerCase();
+  const f = REASONING_FAMILIES.find((x) => x.match.test(m));
+  if (!f) return null;
+  const flag = f.flag(isFull(mode));
+  const extra = provider === 'lmstudio' && LMSTUDIO_EXTRA[f.family];
+  return extra ? { ...flag, ...extra(isFull(mode)) } : flag;
+}
+
+/**
+ * Anthropic generations, in match order (5-5 before 5). Each row says what 'off' and 'full' send and
+ * whether the model still accepts `temperature`.
+ *
+ *   effort      → output_config.effort
+ *   thinking    → the `thinking` object
+ *   budget      → `{ type: 'enabled', budget_tokens }` sized from maxTokens (pre-4.6 models)
+ *   sampling    → false: the model rejects temperature, so none is sent
+ *
+ * `examples` are real model ids that must land on their own row — the test checks each one, which is
+ * what catches a match-order mistake (opus-5 swallowing opus-5-5).
+ *
+ * Source: the Messages API thinking table (cached 2026-09-25). Opus 5 'off' is low effort rather
+ * than `disabled`, which Anthropic documents as leaking tool calls and thinking tags into text.
+ */
+const ANTHROPIC_FAMILIES = Object.freeze([
+  { family: 'claude-fable / claude-opus-5-5', match: /fable|mythos|opus-5-5/,
+    examples: ['claude-opus-5-5', 'claude-fable-5-1', 'claude-fable-5', 'claude-mythos-5-1'],
+    off: { effort: 'low' }, full: { effort: 'high' }, sampling: false },
+  { family: 'claude-opus-5', match: /opus-5(?![-.]?\d)/,
+    examples: ['claude-opus-5'],
+    off: { effort: 'low' }, full: { thinking: { type: 'adaptive' }, effort: 'high' }, sampling: false },
+  { family: 'claude-sonnet-5-5', match: /sonnet-5-5/,
+    examples: ['claude-sonnet-5-5'],
+    off: { thinking: { type: 'between_tools' } }, full: { thinking: { type: 'adaptive' }, effort: 'high' }, sampling: false },
+  { family: 'claude-sonnet-5', match: /sonnet-5(?![-.]?\d)/,
+    examples: ['claude-sonnet-5'],
+    off: { thinking: { type: 'disabled' } }, full: { thinking: { type: 'adaptive' }, effort: 'high' }, sampling: false },
+  { family: 'claude-opus-4-7 / 4-8', match: /opus-4-[78]/,
+    examples: ['claude-opus-4-8', 'claude-opus-4-7'],
+    off: {}, full: { thinking: { type: 'adaptive' }, effort: 'high' }, sampling: false },
+  { family: 'claude-*-4-6', match: /(opus|sonnet)-4-6/,
+    examples: ['claude-opus-4-6', 'claude-sonnet-4-6'],
+    off: {}, full: { thinking: { type: 'adaptive' }, effort: 'high' }, sampling: true },
+  { family: 'claude-*-4-5 and older', match: /-4-5|-4-1|(opus|sonnet|haiku)-4(?![-.]?\d)|claude-3/,
+    examples: ['claude-haiku-4-5', 'claude-sonnet-4-5', 'claude-opus-4-5', 'claude-opus-4-1', 'claude-3-7-sonnet-latest'],
+    off: {}, full: { budget: true }, sampling: true }
+]);
+
+/** Thinking room added on top of the answer's own maxTokens when a pre-4.6 model is asked to think. */
+const MIN_THINKING_BUDGET = 1024;
+
+/**
+ * What to change on an Anthropic request body for this model and mode, or null for an unknown model
+ * (which keeps the pre-0.27 request: no thinking field, temperature as given).
+ *
+ * @returns {{family:string, thinking?:object, effort?:string, sendTemperature:boolean, maxTokens:number}|null}
+ */
+function anthropicReasoning(model, mode, maxTokens) {
+  assertReasoning(mode);
+  const m = String(model || '').toLowerCase();
+  const f = ANTHROPIC_FAMILIES.find((x) => x.match.test(m));
+  if (!f) return null;
+  const want = isFull(mode) ? f.full : f.off;
+  const out = { family: f.family, sendTemperature: f.sampling, maxTokens };
+  if (want.thinking) out.thinking = want.thinking;
+  if (want.effort) out.effort = want.effort;
+  if (want.budget) {
+    // The caller's maxTokens stays the ANSWER's room; the thinking budget is added on top, because
+    // budget_tokens must be below max_tokens and a budget carved out of the answer would starve it.
+    const budget = Math.max(MIN_THINKING_BUDGET, maxTokens);
+    out.thinking = { type: 'enabled', budget_tokens: budget };
+    out.maxTokens = maxTokens + budget;
+    // Extended thinking requires the default temperature on these models.
+    out.sendTemperature = false;
+  }
+  return out;
+}
+
+module.exports = {
+  REASONING_MODES, REASONING_FAMILIES, LMSTUDIO_EXTRA, LMSTUDIO_PROMPT_SWITCH, ANTHROPIC_FAMILIES, MIN_THINKING_BUDGET,
+  assertReasoning, reasoningFor, lmstudioPromptSwitch, anthropicReasoning
+};