@aria-framework/ai 0.26.1 → 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
 ```
@@ -69,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 |
@@ -176,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({
@@ -204,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/browser/ai-panels.js

@@ -1,138 +1,138 @@
-/**
- * The fold on the Inference list, and prefilling the supervisor form from a panel.
- *
- * WHY ANYTHING FOLDS. A stable stack is four engines, three credentials, a certificate fingerprint
- * and a verification report — worth having, not worth reading every time you open this page to do
- * something else. Folded, a panel is one line that still carries the whole verdict: status, the
- * count of what depends on it, all three credentials and when it was last checked. Folding hides
- * detail; it must never hide the reason you would have opened it.
- *
- * A PANEL WITH A PROBLEM IGNORES WHAT YOU REMEMBERED. `data-panel-attention` is stamped by the
- * server on anything with a missing engine, an expiring certificate, a failed check or a nearly
- * spent cap. Those open and stay open. Attention beats tidiness — the alternative is a page that
- * quietly honours a fold you chose last week and hides the thing that broke yesterday.
- *
- * THE PREFERENCE IS PER BROWSER AND DISPOSABLE. It is a convenience about how a page looks to one
- * person, so localStorage is the right home and losing it costs nothing. Every access is guarded:
- * a browser set to block site data throws on read, and a settings page must not break because
- * somebody tightened their privacy settings.
- */
-(function () {
-  'use strict';
-
-  var KEY = 's101.ai.panels';
-
-  function readPrefs() {
-    try {
-      return JSON.parse(window.localStorage.getItem(KEY) || '{}') || {};
-    } catch (e) {
-      return {};
-    }
-  }
-
-  function writePref(id, open) {
-    try {
-      var prefs = readPrefs();
-      prefs[id] = !!open;
-      window.localStorage.setItem(KEY, JSON.stringify(prefs));
-    } catch (e) { /* private window, or site data blocked — the fold still works for this visit */ }
-  }
-
-  function bodyOf(panel) {
-    var btn = panel.querySelector('[data-panel-toggle]');
-    if (!btn) return null;
-    return document.getElementById(btn.getAttribute('aria-controls'));
-  }
-
-  function setOpen(panel, open, remember) {
-    var btn = panel.querySelector('[data-panel-toggle]');
-    var body = bodyOf(panel);
-    if (!btn || !body) return;
-    // `hidden`, not a style: the server renders the closed state the same way, so a panel does not
-    // flicker open on load before this script runs.
-    body.hidden = !open;
-    btn.setAttribute('aria-expanded', open ? 'true' : 'false');
-    panel.classList.toggle('panel-open', open);
-    if (remember) writePref(panel.getAttribute('data-panel'), open);
-  }
-
-  function restore() {
-    var prefs = readPrefs();
-    var panels = document.querySelectorAll('[data-panel]');
-    for (var i = 0; i < panels.length; i += 1) {
-      var panel = panels[i];
-      var id = panel.getAttribute('data-panel');
-      // The server already opened this one and means it. Do not consult the preference at all —
-      // reading it and then ignoring it is the same thing, but invites somebody to "fix" it later.
-      if (panel.hasAttribute('data-panel-attention')) {
-        setOpen(panel, true, false);
-        continue;
-      }
-      if (Object.prototype.hasOwnProperty.call(prefs, id)) setOpen(panel, !!prefs[id], false);
-    }
-  }
-
-  document.addEventListener('click', function (ev) {
-    var toggle = ev.target.closest('[data-panel-toggle]');
-    if (toggle) {
-      var panel = toggle.closest('[data-panel]');
-      if (!panel) return;
-      var body = bodyOf(panel);
-      setOpen(panel, !!(body && body.hidden), true);
-      return;
-    }
-
-    // ── EDITING A STACK HAPPENS IN THE PANEL ────────────────────────────────────────────────────
-    //
-    // It used to happen in a form at the foot of the page, and Edit scrolled you down to it — away
-    // from the stack you were reading, into a form that also served as "Add a supervisor" and said
-    // nothing about which stack it had been filled with. Nothing needs prefilling now: every panel
-    // renders its own form, from the server, with its own values already in it.
-    var open = ev.target.closest('[data-stack-edit-open]');
-    if (open) { stackMode(open.closest('[data-stack]'), true); return; }
-
-    var cancel = ev.target.closest('[data-stack-cancel]');
-    if (cancel) {
-      var panel2 = cancel.closest('[data-stack]');
-      // A NEW stack has no reading half to go back to, so cancelling it puts the blank panel away.
-      if (panel2 && panel2.hasAttribute('data-stack-new')) { panel2.hidden = true; return; }
-      // Otherwise reload rather than restore: a Cancel that left half-typed values behind, ready to
-      // be posted by the next Save, would be worse than the extra request.
-      window.location.reload();
-      return;
-    }
-
-    // "Add LMX" reveals the blank panel that is already on the page, at the top of the list.
-    var add = ev.target.closest('[data-stack-add]');
-    if (add) {
-      var blank = document.querySelector('[data-stack-new]');
-      if (!blank) return;
-      blank.hidden = false;
-      blank.scrollIntoView({ block: 'nearest' });
-      var id = blank.querySelector('[name="id"]');
-      if (id) id.focus();
-    }
-  });
-
-  /** Swap one stack panel between reading and editing. */
-  function stackMode(panel, editing) {
-    if (!panel) return;
-    var view = panel.querySelector('[data-stack-view]');
-    var form = panel.querySelector('[data-stack-edit]');
-    if (!view || !form) return;
-    view.hidden = editing;
-    form.hidden = !editing;
-    if (editing) {
-      // The id is readonly on an existing stack, so focus the first field somebody can actually
-      // change rather than one that will not accept a keystroke.
-      var first = form.querySelector('[name="label"]') || form.querySelector('[name="status_url"]');
-      if (first) first.focus();
-    }
-  }
-
-  if (document.readyState === 'loading') {
-    document.addEventListener('DOMContentLoaded', restore);
-  } else {
-    restore();
-  }
-})();
+/**
+ * The fold on the Inference list, and prefilling the supervisor form from a panel.
+ *
+ * WHY ANYTHING FOLDS. A stable stack is four engines, three credentials, a certificate fingerprint
+ * and a verification report — worth having, not worth reading every time you open this page to do
+ * something else. Folded, a panel is one line that still carries the whole verdict: status, the
+ * count of what depends on it, all three credentials and when it was last checked. Folding hides
+ * detail; it must never hide the reason you would have opened it.
+ *
+ * A PANEL WITH A PROBLEM IGNORES WHAT YOU REMEMBERED. `data-panel-attention` is stamped by the
+ * server on anything with a missing engine, an expiring certificate, a failed check or a nearly
+ * spent cap. Those open and stay open. Attention beats tidiness — the alternative is a page that
+ * quietly honours a fold you chose last week and hides the thing that broke yesterday.
+ *
+ * THE PREFERENCE IS PER BROWSER AND DISPOSABLE. It is a convenience about how a page looks to one
+ * person, so localStorage is the right home and losing it costs nothing. Every access is guarded:
+ * a browser set to block site data throws on read, and a settings page must not break because
+ * somebody tightened their privacy settings.
+ */
+(function () {
+  'use strict';
+
+  var KEY = 's101.ai.panels';
+
+  function readPrefs() {
+    try {
+      return JSON.parse(window.localStorage.getItem(KEY) || '{}') || {};
+    } catch (e) {
+      return {};
+    }
+  }
+
+  function writePref(id, open) {
+    try {
+      var prefs = readPrefs();
+      prefs[id] = !!open;
+      window.localStorage.setItem(KEY, JSON.stringify(prefs));
+    } catch (e) { /* private window, or site data blocked — the fold still works for this visit */ }
+  }
+
+  function bodyOf(panel) {
+    var btn = panel.querySelector('[data-panel-toggle]');
+    if (!btn) return null;
+    return document.getElementById(btn.getAttribute('aria-controls'));
+  }
+
+  function setOpen(panel, open, remember) {
+    var btn = panel.querySelector('[data-panel-toggle]');
+    var body = bodyOf(panel);
+    if (!btn || !body) return;
+    // `hidden`, not a style: the server renders the closed state the same way, so a panel does not
+    // flicker open on load before this script runs.
+    body.hidden = !open;
+    btn.setAttribute('aria-expanded', open ? 'true' : 'false');
+    panel.classList.toggle('panel-open', open);
+    if (remember) writePref(panel.getAttribute('data-panel'), open);
+  }
+
+  function restore() {
+    var prefs = readPrefs();
+    var panels = document.querySelectorAll('[data-panel]');
+    for (var i = 0; i < panels.length; i += 1) {
+      var panel = panels[i];
+      var id = panel.getAttribute('data-panel');
+      // The server already opened this one and means it. Do not consult the preference at all —
+      // reading it and then ignoring it is the same thing, but invites somebody to "fix" it later.
+      if (panel.hasAttribute('data-panel-attention')) {
+        setOpen(panel, true, false);
+        continue;
+      }
+      if (Object.prototype.hasOwnProperty.call(prefs, id)) setOpen(panel, !!prefs[id], false);
+    }
+  }
+
+  document.addEventListener('click', function (ev) {
+    var toggle = ev.target.closest('[data-panel-toggle]');
+    if (toggle) {
+      var panel = toggle.closest('[data-panel]');
+      if (!panel) return;
+      var body = bodyOf(panel);
+      setOpen(panel, !!(body && body.hidden), true);
+      return;
+    }
+
+    // ── EDITING A STACK HAPPENS IN THE PANEL ────────────────────────────────────────────────────
+    //
+    // It used to happen in a form at the foot of the page, and Edit scrolled you down to it — away
+    // from the stack you were reading, into a form that also served as "Add a supervisor" and said
+    // nothing about which stack it had been filled with. Nothing needs prefilling now: every panel
+    // renders its own form, from the server, with its own values already in it.
+    var open = ev.target.closest('[data-stack-edit-open]');
+    if (open) { stackMode(open.closest('[data-stack]'), true); return; }
+
+    var cancel = ev.target.closest('[data-stack-cancel]');
+    if (cancel) {
+      var panel2 = cancel.closest('[data-stack]');
+      // A NEW stack has no reading half to go back to, so cancelling it puts the blank panel away.
+      if (panel2 && panel2.hasAttribute('data-stack-new')) { panel2.hidden = true; return; }
+      // Otherwise reload rather than restore: a Cancel that left half-typed values behind, ready to
+      // be posted by the next Save, would be worse than the extra request.
+      window.location.reload();
+      return;
+    }
+
+    // "Add LMX" reveals the blank panel that is already on the page, at the top of the list.
+    var add = ev.target.closest('[data-stack-add]');
+    if (add) {
+      var blank = document.querySelector('[data-stack-new]');
+      if (!blank) return;
+      blank.hidden = false;
+      blank.scrollIntoView({ block: 'nearest' });
+      var id = blank.querySelector('[name="id"]');
+      if (id) id.focus();
+    }
+  });
+
+  /** Swap one stack panel between reading and editing. */
+  function stackMode(panel, editing) {
+    if (!panel) return;
+    var view = panel.querySelector('[data-stack-view]');
+    var form = panel.querySelector('[data-stack-edit]');
+    if (!view || !form) return;
+    view.hidden = editing;
+    form.hidden = !editing;
+    if (editing) {
+      // The id is readonly on an existing stack, so focus the first field somebody can actually
+      // change rather than one that will not accept a keystroke.
+      var first = form.querySelector('[name="label"]') || form.querySelector('[name="status_url"]');
+      if (first) first.focus();
+    }
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', restore);
+  } else {
+    restore();
+  }
+})();

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,19 +131,9 @@ 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).');
-      }
-      const { reasoning: _ignored, ...rest } = opts;
-      callOpts = rest;
-    }
+    // 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;