@aria-framework/ai 0.25.0 → 0.26.1

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.25.0",
+  "version": "0.26.1",
   "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 && node test/usageOnFailure.js",
     "prepublishOnly": "node ../../test/packaging.js ai"
   },
   "devDependencies": {

package/providers/anthropic.js

@@ -97,6 +97,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 +116,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 +128,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 +139,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

@@ -149,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.
+ */
+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.
  */
-function reasoningFor(modelPath) {
+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. */
@@ -204,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); });
 }
@@ -289,5 +328,6 @@ function _resetRegistry() {
 module.exports = {
   complete, embed, listModels, listModelsResult,
   apiRoot: openai.apiRoot,
-  reasoningFor, discoveryFor, forgetDiscovery, _resetRegistry, SKIP_CODE
+  reasoningFor, assertReasoning, REASONING_MODES, REASONING_FAMILIES,
+  discoveryFor, forgetDiscovery, _resetRegistry, SKIP_CODE
 };

package/providers/openai-compatible.js

@@ -133,7 +133,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));
@@ -154,13 +160,26 @@ 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 });
   }
 
+  // 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.
@@ -179,10 +198,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 });
     }
   }
 
@@ -190,7 +209,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
@@ -214,6 +233,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.
  *
@@ -221,13 +246,15 @@ function stripThinking(content) {
  * 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` +
       (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) {
@@ -237,7 +264,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. */