@aria-framework/ai 0.26.1 → 0.27.0

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.1",
+  "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 && node test/usageOnFailure.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);

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);

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
+};