@aria-framework/ai 0.25.0 → 0.26.1

package/README.md

@@ -32,7 +32,11 @@ const ai = createAiClient({
   logger: console                                                                        // optional
 });
 
-const r = await ai.complete({ system, messages, maxTokens: 400, schema /* optional */ });
+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)
+});
 // r.text, r.json (when schema), r.model, r.usage.total, r.ms
 ```
 
@@ -40,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.
 
@@ -59,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 | `qwen` → `chat_template_kwargs.enable_thinking=false`, `gpt-oss` → `reasoning_effort:'low'`, anything else gets neither (with a warning) |
+| 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) |
 | 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 |
@@ -166,6 +176,54 @@ 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'`)
+
+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:
+
+```js
+const r = await ai.complete({
+  system, messages, schema,
+  reasoning: 'full',
+  maxTokens: 4096,        // at least 4096; see the trap below
+});                       // and give the endpoint timeoutMs: 120000 or more
+```
+
+**When to use it.** Use it for judgement tasks where the answer depends on weighing evidence,
+such as alert triage. Do not use it for quick summaries, rewrites or extraction. They do not get
+better, only slower.
+
+**What it costs.** It is much slower, roughly 30–45 s per answer on lab hardware instead of a few
+seconds, and it spends many more tokens, because the thinking is generated and billed like any
+other output. Budget for both.
+
+**The trap.** Thinking comes out of `maxTokens`. If the limit is too small, the model spends all
+of it thinking and returns **an empty answer, with no error from the server** (`finish_reason:
+"length"`). The adapter turns that, and a reply cut off inside an unclosed `<think>` block, into
+a `bad_response` AiError saying it ran out of room (and, when the server says so, that the
+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):
+
+| Family | Default (no `reasoning`) | `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) |
+
+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
+  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.
+- `REASONING_MODES` (package root) lists the accepted values for an app that validates its own
+  settings.
+
 ### Embeddings
 
 Call `client.embed(cfg, texts, { signal })` and pass your own resolved embedding config; it never

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