@aria-framework/ai 0.24.1 → 0.26.0

package/lmxStatus.js

@@ -50,7 +50,7 @@ function reasoningLabel(model) {
   const flag = reasoningFor(model);
   if (!flag) return null;
   if (flag.reasoning_effort) return `reasoning_effort: ${flag.reasoning_effort}`;
-  return 'enable_thinking: false';
+  return `enable_thinking: ${flag.chat_template_kwargs.enable_thinking}`;
 }
 
 /**
@@ -155,12 +155,16 @@ const rowRef = (row) => ({ id: row.lmx_engine_id || null, name: row.lmx_engine }
  */
 function rekeyPlan(rows, engines) {
   if (!Array.isArray(engines)) return [];
+  // IDS ROWS ALREADY TRACK (0.25.0). CLIENT.md's condition for minting is "an id you have never
+  // seen". Without it, renaming row A's engine to the name a stale, id-less row B still carries
+  // handed B A's id — B's routes silently went to A's engine.
+  const held = new Set((rows || []).map((r) => r && r.lmx_engine_id).filter(Boolean));
   const plan = [];
   for (const row of rows || []) {
     if (!row) continue;
     if (!row.lmx_engine_id) {
       const e = findEngine(engines, { name: row.lmx_engine });
-      if (e && e.id) plan.push({ id: row.id, set: { lmx_engine_id: e.id }, why: 'minted' });
+      if (e && e.id && !held.has(e.id)) plan.push({ id: row.id, set: { lmx_engine_id: e.id }, why: 'minted' });
       continue;
     }
     const e = findEngine(engines, { id: row.lmx_engine_id });

package/lmxVerify.js

@@ -216,6 +216,11 @@ async function verify(o = {}) {
     if (doc && doc.instance && String(doc.instance) !== instance) {
       checks.push(fail('instance',
         `this stack reports itself as “${doc.instance}”, not “${instance}” — the address points at a different deployment`));
+      // AND ITS ENGINES ARE NOT HANDED BACK (0.25.0). The apps' scheduled refresh feeds
+      // report.engines to rekeyPlan; returning another deployment's list wrote THAT stack's engine
+      // ids onto this stack's rows — irreversibly, since a row with an id is never re-pointed.
+      // `null` is "no document for this stack", which every consumer treats as "write nothing".
+      found = null;
     }
 
     checks.push(await enginesKeyCheck(o, engines, timeoutMs));

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.24.1",
+  "version": "0.26.0",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {
@@ -47,7 +47,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",
+    "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",
     "prepublishOnly": "node ../../test/packaging.js ai"
   },
   "devDependencies": {

package/providers/lmx.js

@@ -27,16 +27,33 @@ const { createLmxDiscovery } = require('./lmxDiscovery');
 const { lmxTransport } = require('./lmxTransport');
 const { AiError } = require('../error');
 
-/** Discovery instances, keyed so several engines on one stack share a single poller. */
+/**
+ * Discovery instances, ONE PER STACK (keyed by instance), so several engines on one stack share a
+ * single poller.
+ *
+ * Keyed by instance alone since 0.25.0. Keyed by (instance, statusUrl), an edited status URL created
+ * a SECOND poller and left the first polling the old address every 2 s for the life of the process.
+ */
 const registry = new Map();
 
-const keyOf = (lmx) => `${lmx.instance}\u0000${lmx.statusUrl}`;
+/** The settings a live poller takes from the app's supervisor row, applied on every use. */
+const settingsOf = (lmx) => ({
+  token: lmx.statusToken,
+  ca: lmx.ca || null,
+  staleMs: lmx.staleMs,
+  pollMs: lmx.pollMs,
+  fetchTimeoutMs: lmx.statusTimeoutMs
+});
 
 /**
- * The discovery for this supervisor, created once and started on first use.
+ * The discovery for this supervisor, created once and started on first use — and RECONFIGURED on
+ * every use (0.25.0).
  *
- * Credentials are NOT part of the key: rotating a token should not orphan a running poller and
- * leave the old one polling with a dead credential. The live instance is updated in place instead.
+ * Credentials are not part of the key, so rotating a token does not orphan the poller; until 0.25.0
+ * nothing then applied the new token either (the comment here said "updated in place"; nothing did),
+ * so a rotated key or a replaced certificate never reached the poller and every lmx endpoint went
+ * stale until a restart. configure() applies whatever the app hands over each time — the app
+ * resolves its supervisor row per call, so the row is the source of truth.
  */
 function discoveryFor(lmx, logger) {
   if (!lmx || !lmx.instance || !lmx.statusUrl) {
@@ -44,29 +61,44 @@ function discoveryFor(lmx, logger) {
       'This endpoint is an lmx engine but no supervisor is configured for it — an engine name '
       + 'without a status listener cannot be resolved to an address.');
   }
-  const key = keyOf(lmx);
+  const key = lmx.instance;
   let d = registry.get(key);
-  if (!d) {
-    d = createLmxDiscovery({
+  if (d && d.status().statusUrl !== lmx.statusUrl) {
+    // A NEW ADDRESS IS A NEW POLLER: the document, its age and its last error belong to the old one.
+    d.stop();
+    registry.delete(key);
+    d = null;
+  }
+  if (d) {
+    d.configure(settingsOf(lmx));
+  } else {
+    d = createLmxDiscovery(Object.assign({
       instance: lmx.instance,
       statusUrl: lmx.statusUrl,
-      token: lmx.statusToken,
-      ca: lmx.ca || null,
-      staleMs: lmx.staleMs,
-      // Was accepted from the app's supervisor row and then dropped here, so a configured poll
-      // interval never took effect. undefined falls through to POLL_MS.
-      pollMs: lmx.pollMs,
       // Test seam, the same one createLmxDiscovery already takes: it is the only way to exercise
       // complete() end-to-end without a live stack, and the cold-start bug lived exactly there.
       fetchImpl: lmx.fetchImpl,
       logger
-    });
+    }, settingsOf(lmx)));
     d.start();
     registry.set(key, d);
   }
   return d;
 }
 
+/**
+ * Stop and drop the poller for a stack — call it when the app deletes or disables a supervisor
+ * (0.25.0). Otherwise that stack's poller kept polling every 2 s for the life of the process.
+ * @returns {boolean} whether there was one to forget
+ */
+function forgetDiscovery(instance) {
+  const d = registry.get(instance);
+  if (!d) return false;
+  d.stop();
+  registry.delete(instance);
+  return true;
+}
+
 /**
  * Why a resolution failed, in the vocabulary the dispatcher classifies on.
  *
@@ -117,12 +149,43 @@ function skipError(name, res) {
  * 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.
  */
-function reasoningFor(modelPath) {
+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.
+ */
+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();
-  if (/qwen/.test(m)) return { chat_template_kwargs: { enable_thinking: false } };
-  if (/gpt-oss/.test(m)) return { reasoning_effort: 'low' };
-  return null;
+  const f = REASONING_FAMILIES.find((x) => x.match.test(m));
+  return f ? f.flag(mode === 'full') : null;
 }
 
 /** The config openai-compatible needs, once the address is known. */
@@ -172,23 +235,31 @@ function tagThrottle(err) {
 }
 
 async function complete(cfg, opts) {
+  // Validated BEFORE discovery, so a typo is refused without a status read or an engine call.
+  const mode = opts && opts.reasoning;
+  assertReasoning(mode);
   const d = discoveryFor(cfg.lmx, cfg.logger);
   const name = cfg.lmx.engine;
   const res = await resolveWarm(d, refOf(cfg.lmx));
   if (!res.url) throw skipError(name, res);
 
-  const reasoning = reasoningFor(res.engine.model);
+  const reasoning = reasoningFor(res.engine.model, mode);
   if (!reasoning && cfg.logger) {
-    cfg.logger.warn(
-      `lmx: no reasoning flag known for model "${res.engine.model}" on engine "${name}" — sending `
-      + 'none. If it reasons before answering, the token budget may be consumed with no content '
-      + 'returned.'
+    cfg.logger.warn(mode === 'full'
+      ? `lmx: reasoning '${mode}' was asked for, but no reasoning flag is known for model `
+        + `"${res.engine.model}" on engine "${name}" — sending none; the model runs on its own default.`
+      : `lmx: no reasoning flag known for model "${res.engine.model}" on engine "${name}" — sending `
+        + 'none. If it reasons before answering, the token budget may be consumed with no content '
+        + 'returned.'
     );
   }
 
+  // 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), {
-    ...opts,
-    // Merged rather than replacing: a caller's own extras survive.
+    ...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); });
 }
@@ -257,5 +328,6 @@ function _resetRegistry() {
 module.exports = {
   complete, embed, listModels, listModelsResult,
   apiRoot: openai.apiRoot,
-  reasoningFor, discoveryFor, _resetRegistry, SKIP_CODE
+  reasoningFor, assertReasoning, REASONING_MODES, REASONING_FAMILIES,
+  discoveryFor, forgetDiscovery, _resetRegistry, SKIP_CODE
 };

package/providers/lmxDiscovery.js

@@ -56,6 +56,25 @@ const STALE_MS = 3 * 60 * 1000;
 /** The only state that may receive new work. */
 const HEALTHY = 'healthy';
 
+/**
+ * The fastest a poller may run (0.25.0). A poll interval of 0 — a NULL coerced, a typo — is not a
+ * faster poll, it is a busy loop against the supervisor.
+ */
+const MIN_POLL_MS = 500;
+
+/**
+ * How long one status read may take (0.25.0). There was no bound at all — only undici's 300 s
+ * defaults — so after a restart an lmx call awaited a hung listener far past its own timeout and
+ * the dispatcher never failed over. The document is small and served no-store: seconds is ample.
+ */
+const FETCH_TIMEOUT_MS = 5000;
+
+// null/undefined mean "the default" (lmxStore stores NULL for exactly that); any number — 0, a
+// typo, NaN — is floored rather than trusted.
+const floorPoll = (ms) => (ms === undefined || ms === null || ms === ''
+  ? POLL_MS
+  : Math.max(MIN_POLL_MS, Number(ms) || 0));
+
 /**
  * @param {object} opts
  * @param {string} opts.statusUrl      e.g. https://host:9443/status
@@ -63,7 +82,8 @@ const HEALTHY = 'healthy';
  * @param {string} opts.token          bearer for the status listener
  * @param {string} [opts.ca]           PEM of the certificate to pin
  * @param {number} [opts.staleMs]
- * @param {number} [opts.pollMs]
+ * @param {number} [opts.pollMs]         floored at MIN_POLL_MS
+ * @param {number} [opts.fetchTimeoutMs] one status read's deadline (default FETCH_TIMEOUT_MS)
  * @param {object} [opts.logger]
  * @param {function} [opts.fetchImpl]  injectable for tests; defaults to global fetch
  * @param {function} [opts.now]        injectable clock
@@ -72,10 +92,6 @@ function createLmxDiscovery(opts = {}) {
   const {
     statusUrl,
     instance,
-    token,
-    ca = null,
-    staleMs = STALE_MS,
-    pollMs = POLL_MS,
     logger = console,
     fetchImpl,
     now = () => Date.now()
@@ -84,10 +100,21 @@ function createLmxDiscovery(opts = {}) {
   if (!statusUrl) throw new Error('createLmxDiscovery: statusUrl is required');
   if (!instance) throw new Error('createLmxDiscovery: instance is required — identity is (instance, name)');
 
+  // MUTABLE, AND THAT IS THE 0.25.0 FIX. These were captured once for the life of the process, so a
+  // rotated token or a replaced certificate never reached the poller: Check (a fresh fetch) said
+  // "verified" while every poll got 401 and, after staleMs, every engine was skipped as stale until
+  // a restart. configure() below updates them in place; the registry calls it on every use.
+  let token = opts.token;
+  let ca = opts.ca || null;
+  let staleMs = opts.staleMs || STALE_MS;
+  let pollMs = floorPoll(opts.pollMs);
+  let fetchTimeoutMs = Number(opts.fetchTimeoutMs) || FETCH_TIMEOUT_MS;
+
   let doc = null;         // the last document that parsed and matched our instance
   let docAt = 0;
   let lastError = null;
   let timer = null;
+  let inFlight = null;    // the one refresh running now; concurrent callers share it
 
   /**
    * The pinned transport — see providers/lmxTransport.js for why this is not NODE_EXTRA_CA_CERTS
@@ -102,7 +129,9 @@ function createLmxDiscovery(opts = {}) {
     const t = transport();
     const res = await t.fetch(statusUrl, {
       headers: { Authorization: `Bearer ${token}` },
-      dispatcher: t.dispatcher
+      dispatcher: t.dispatcher,
+      // BOUNDED (0.25.0): a listener that accepts and never answers is abandoned, not awaited.
+      signal: AbortSignal.timeout(fetchTimeoutMs)
     });
     if (!res.ok) {
       const err = new Error(`status listener answered ${res.status}`);
@@ -119,7 +148,17 @@ function createLmxDiscovery(opts = {}) {
    * failure — the listener answered perfectly — so it is reported as a configuration error, which
    * is what it is. Adopting it would route `analysis` to another deployment's `analysis`.
    */
-  async function refresh() {
+  /**
+   * SINGLE-FLIGHT (0.25.0). The 2 s poller and every warming AI call each started their own read, so
+   * a hung listener stacked a new pending fetch per tick and per request. Concurrent callers now
+   * share the one in flight.
+   */
+  function refresh() {
+    if (!inFlight) inFlight = refreshOnce().finally(() => { inFlight = null; });
+    return inFlight;
+  }
+
+  async function refreshOnce() {
     try {
       const next = await fetchOnce();
       if (next && next.instance && next.instance !== instance) {
@@ -196,8 +235,28 @@ function createLmxDiscovery(opts = {}) {
     timer = null;
   }
 
+  /**
+   * Apply new settings to a live poller (0.25.0). `undefined` keeps the current value. A new poll
+   * interval restarts a running timer so it takes effect now, not after a process restart.
+   * The status URL and instance are identity, not settings: a different URL is a different poller
+   * (the registry replaces it — see providers/lmx.js).
+   */
+  function configure(next = {}) {
+    if (next.token !== undefined) token = next.token;
+    if (next.ca !== undefined) ca = next.ca || null;
+    if (next.staleMs !== undefined) staleMs = next.staleMs || STALE_MS;
+    if (next.fetchTimeoutMs !== undefined) fetchTimeoutMs = Number(next.fetchTimeoutMs) || FETCH_TIMEOUT_MS;
+    if (next.pollMs !== undefined) {
+      const p = floorPoll(next.pollMs);
+      if (p !== pollMs) {
+        pollMs = p;
+        if (timer) { stop(); timer = setInterval(refresh, pollMs); if (timer.unref) timer.unref(); }
+      }
+    }
+  }
+
   return {
-    start, stop, refresh, resolve, engines, engine,
+    start, stop, refresh, resolve, engines, engine, configure,
     /** The pinned transport, so ENGINE calls reach the same host over the same trust. */
     transport,
     /** For a diagnostics panel: what we know and how old it is. */
@@ -208,7 +267,9 @@ function createLmxDiscovery(opts = {}) {
       engineCount: engines().length,
       ageSec: doc ? ageSec() : null,
       stale: doc ? isStale() : true,
-      lastError
+      lastError,
+      pollMs,
+      running: !!timer
     })
   };
 }
@@ -227,4 +288,4 @@ function findEngine(list, ref) {
   return all.find((e) => e && e.name === r.name) || null;
 }
 
-module.exports = { createLmxDiscovery, findEngine, POLL_MS, STALE_MS, HEALTHY };
+module.exports = { createLmxDiscovery, findEngine, POLL_MS, STALE_MS, HEALTHY, MIN_POLL_MS, FETCH_TIMEOUT_MS };

package/providers/openai-compatible.js

@@ -154,8 +154,17 @@ async function complete(cfg, opts) {
   // that thinking back separately (`reasoning_content`) or inline, wrapped in <think> tags. Neither
   // is the answer, and both have to be recognised — otherwise a model that reasoned and then ran
   // out of room looks identical to a broken server.
-  const reasoning = message.reasoning_content || message.reasoning || '';
-  const text = stripThinking(message.content || '');
+  let reasoning = message.reasoning_content || message.reasoning || '';
+  let text = stripThinking(message.content || '');
+
+  // A LENGTH STOP INSIDE AN UNCLOSED <think> IS NO ANSWER (0.26.0). stripThinking only removes a
+  // CLOSED block, so a model that ran out of room mid-thought used to resolve with its half-finished
+  // reasoning as the "answer" (truncated: true). Narrow on purpose: only a reply that STARTS with
+  // the tag, has no closing tag, and stopped on length — the case reasoning: 'full' makes common.
+  if (finishReason === 'length' && unclosedThinking(text)) {
+    reasoning = reasoning || text;
+    text = '';
+  }
 
   if (!text) {
     throw emptyCompletion({ label, finishReason, reasoning, maxTokens: body.max_tokens, usage: payload.usage });
@@ -214,6 +223,12 @@ function stripThinking(content) {
     .trim();
 }
 
+/** A reply that opens a <think>/<thinking> block and never closes it. */
+function unclosedThinking(text) {
+  const m = /^<(think|thinking)>/i.exec(String(text || '').trimStart());
+  return !!m && !new RegExp(`</${m[1]}>`, 'i').test(text);
+}
+
 /**
  * Why nothing came back — the message an operator can act on.
  *
@@ -227,7 +242,8 @@ function emptyCompletion({ label, finishReason, reasoning, maxTokens, usage }) {
     return new AiError('bad_response',
       `${label} ran out of room before it answered — it used all ${maxTokens} reply tokens` +
       (reasoning ? ' on internal reasoning' : '') +
-      '. This model thinks before it replies, so raise the reply limit (1024 is a sensible floor).',
+      '. This model thinks before it replies, so raise the reply limit (1024 is a sensible floor; ' +
+      "4096 or more with reasoning: 'full').",
     { usage });
   }
   if (reasoning) {