@aria-framework/ai 0.25.0 → 0.26.0

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
 ```
 
@@ -59,7 +63,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 +170,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/index.js

@@ -1,309 +1,333 @@
-/**
- * @aria-framework/ai — the AI seam. One `complete()`, several providers behind it, plus the
- * writing-assist engines (polish/generate) and the fact-preservation guard.
- *
- * DEPENDENCY-INJECTED, DATABASE-FREE. The package knows how to talk to a model; it does NOT know
- * where an app keeps its settings, its credentials or its token ledger. The consumer builds a
- * client with two functions of its own:
- *
- *   const ai = createAiClient({
- *     resolveConfig,   // async () => resolved config (provider, baseUrl, model, apiKey, caps…)
- *     budget,          // { assertWithinBudget(cfg, ctx), record(cfg, result, ctx) }  — optional
- *     logger           // { info, warn, error }                                        — optional
- *   });
- *
- * The provider adapters already take an explicit config and never read a database, which is what
- * makes the seam testable: a stub adapter and a real adapter are called identically.
- *
- * PROMPTS ARE CONTENT AND LIVE IN THE APP. This package carries the mechanism (how to call a model,
- * how to enforce a token ceiling, how to check a rewrite kept its facts) and generic writing
- * operations; the words that say "you are editing a reply to a customer" belong to the app.
- */
-
-'use strict';
-
-const facts = require('./facts');
-const { AiError, fromFetchFailure, redact } = require('./error');
-const { polish } = require('./polish');
-const { generate } = require('./generate');
-
-const PROVIDERS = {
-  // 'lmstudio' and 'openai-compatible' are the SAME adapter with different defaults — a kindness to
-  // whoever configures it: an operator running LM Studio should not have to know it speaks a shape
-  // named after somebody else.
-  lmstudio: require('./providers/openai-compatible'),
-  'openai-compatible': require('./providers/openai-compatible'),
-  anthropic: require('./providers/anthropic'),
-  // 0.14.0 — a supervised fleet rather than an address. The engine URL is discovered from the
-  // supervisor's status document per call, the reasoning flag is read from the model the engine
-  // is actually running, and the whole conversation is pinned to a self-signed certificate.
-  lmx: require('./providers/lmx')
-};
-
-const DEFAULTS = {
-  lmstudio: { baseUrl: 'http://localhost:1234/v1', model: 'qwen3.5-9b', label: 'LM Studio' },
-  'openai-compatible': { baseUrl: 'http://localhost:11434/v1', model: '', label: 'The model server' },
-  anthropic: { baseUrl: 'https://api.anthropic.com/v1', model: 'claude-sonnet-4-5', label: 'Claude' },
-  // No baseUrl: an lmx engine's address is never configured, only discovered.
-  lmx: { baseUrl: '', model: '', label: 'lmx engine' }
-};
-
-const RETRY_AFTER_MS = 400;
-const RETRY_ONLY_IF_FAILED_WITHIN_MS = 5000;
-
-const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
-const NOOP_BUDGET = { async assertWithinBudget() {}, async record() {} };
-
-/**
- * Build an AI client bound to one app's config resolution and token budget.
- * @param {{resolveConfig: () => Promise<object>, budget?: object, logger?: object}} deps
- */
-function createAiClient(deps = {}) {
-  const resolveConfig = deps.resolveConfig;
-  if (typeof resolveConfig !== 'function') {
-    throw new Error('createAiClient: resolveConfig must be an async function returning the resolved config');
-  }
-  const log = deps.logger || NOOP_LOGGER;
-  const meter = deps.budget || NOOP_BUDGET;
-
-  /**
-   * Try once more, but only for the failure where trying again could help — a local provider that
-   * dropped the connection while loading a model. A cancelled call, a timeout, a rate limit or a slow
-   * failure is never retried (see the guards below).
-   *
-   * A 429 FAILS FAST (0.25.0). 0.23/0.24 slept its Retry-After here (up to 10 s), below every app's
-   * dispatcher: every engine on an lmx stack shares one gateway key, so each failover re-hit the same
-   * throttle and paid the wait again, and an OpenAI-compatible primary that sent Retry-After delayed a
-   * healthy backup by the full wait. Decided 2026-10-01: the client does not wait. The error carries
-   * `retryAfterMs` (and `lmxSkip: 'lmx_throttled'` from an lmx engine) for a caller that chooses to.
-   */
-  async function withOneRetry(run, opts = {}) {
-    const startedAt = Date.now();
-    try {
-      return await run();
-    } catch (err) {
-      if (opts.signal && opts.signal.aborted) throw err;
-      if (!err || !err.retryable) throw err;
-      const elapsed = Date.now() - startedAt;
-      // A TIMEOUT is the deadline itself being reached — retrying waits the whole deadline again. A
-      // RATE LIMIT is the provider asking for less pressure. A slow `unreachable` is not the
-      // sub-second dropped-connection transient this retry exists for. None of those retry.
-      if (err.kind === 'timeout' || err.kind === 'rate_limit' || elapsed > RETRY_ONLY_IF_FAILED_WITHIN_MS) {
-        log.warn(`AI: ${err.kind} after ${elapsed}ms — not retrying (${err.message})`);
-        throw err;
-      }
-      log.warn(`AI: ${err.kind} — trying once more in ${RETRY_AFTER_MS}ms (${err.message})`);
-      await new Promise((r) => setTimeout(r, RETRY_AFTER_MS));
-      return run();
-    }
-  }
-
-  /**
-   * Ask the configured model for something.
-   * @param {{system?:string, messages:Array, maxTokens?:number, temperature?:number,
-   *          schema?:object, signal?:AbortSignal, ticketId?:*, skipBudget?:boolean}} opts
-   * @param {object} [cfgOverride] the resolved config, when the caller already has it
-   */
-  async function complete(opts, cfgOverride) {
-    const cfg = cfgOverride || await resolveConfig();
-    if (!cfg.enabled) {
-      throw new AiError('disabled', 'AI assistance is switched off. An administrator can enable it in Settings.');
-    }
-    // A MODEL NAME IS REQUIRED OF EVERY PROVIDER THAT HAS ONE TO CONFIGURE — which is all of them
-    // except a supervised stack. There the model is a FACT the supervisor reports about an engine,
-    // not a setting: the operator picks an engine and whatever it is running answers. Insisting on
-    // a model name would make an lmx endpoint unusable by demanding the one field the design says
-    // not to store, and would say so with a message naming nothing an operator could go and fill in.
-    if (!cfg.model && cfg.provider !== 'lmx') {
-      throw new AiError('unconfigured', 'No model name is configured.');
-    }
-    const adapter = PROVIDERS[cfg.provider];
-    if (!adapter) {
-      throw new AiError('unconfigured', `No adapter is registered for provider "${cfg.provider}".`);
-    }
-
-    // The ceiling, before the call — the only place a limit can be enforced without being bypassable
-    // 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 });
-
-    const result = await withOneRetry(() => adapter.complete(cfg, opts), opts);
-
-    // ...and the counter after it, AWAITED: two calls in quick succession must both be counted
-    // before the second's ceiling check reads the total, or the limit is enforced against a stale one.
-    await meter.record(cfg, result, { ticketId: opts.ticketId });
-
-    log.info(`AI: ${cfg.provider}/${result.model} ${result.usage.total} tokens in ${result.ms}ms`);
-    return result;
-  }
-
-  /**
-   * Embed one or more strings, with the same retry policy as complete() — a fast dropped connection
-   * is retried once; a 429 fails fast (0.25.0, see withOneRetry). Embeddings are idempotent, so the
-   * one resend is always safe.
-   *
-   * THE CONFIG IS THE CALLER'S. An app resolves its embedding settings separately from completion
-   * (embeddingModel, often a different endpoint), so this never falls back to resolveConfig().
-   * No budget metering - embeddings were never metered, and starting is a separate decision.
-   * @param {object} cfg the resolved embedding config (provider, embeddingModel, …)
-   * @param {string|string[]} texts
-   * @param {{signal?: AbortSignal}} [opts]
-   */
-  async function embed(cfg, texts, opts = {}) {
-    // EXPLICITLY DISABLED is refused, as complete() refuses it (the review found embed ignored it).
-    // Strictly `false`: an embedding config the caller built without the flag is still honoured.
-    if (cfg && cfg.enabled === false) {
-      throw new AiError('disabled', 'This endpoint is switched off.');
-    }
-    const adapter = cfg && PROVIDERS[cfg.provider];
-    if (!adapter) {
-      throw new AiError('unconfigured', `No adapter is registered for provider "${cfg && cfg.provider}".`);
-    }
-    if (typeof adapter.embed !== 'function') {
-      throw new AiError('unsupported', `${cfg.label || cfg.provider} does not support embeddings.`);
-    }
-    return withOneRetry(() => adapter.embed(cfg, texts), opts);
-  }
-
-  /** Is there a provider configured at all? Callers use this to decide whether to render a control. */
-  async function isEnabled() {
-    return (await resolveConfig()).enabled;
-  }
-
-  /** A short round trip for an admin "Test connection". NEVER THROWS — it reports what is wrong. */
-  async function test(cfgOverride) {
-    const cfg = cfgOverride || await resolveConfig();
-    if (!cfg.enabled) return { ok: false, kind: 'disabled', error: 'No provider is selected.' };
-    try {
-      const r = await complete({
-        system: 'Reply with the single word: ready. Do not explain.',
-        messages: [{ role: 'user', content: 'ready?' }],
-        maxTokens: 512,
-        temperature: 0,
-        skipBudget: true            // an admin diagnosing a provider must not be blocked by a full budget
-      }, cfg);
-      return {
-        ok: true, model: r.model, ms: r.ms, reply: (r.text || '').trim().slice(0, 60), usage: r.usage,
-        finishReason: r.finishReason || null, reasoned: !!r.reasonedFor
-      };
-    } catch (err) {
-      if (err instanceof AiError) return { ok: false, kind: err.kind, error: err.message, retryable: err.retryable };
-      return { ok: false, kind: 'bad_response', error: err.message };
-    }
-  }
-
-  /** What the server has loaded, for an admin model picker. Empty when it cannot say. */
-  async function listModels(cfgOverride) {
-    return (await listModelsResult(cfgOverride)).models;
-  }
-
-  /**
-   * The model list and WHY it is the length it is.
-   *
-   * Callers that only want names should use listModels(). An admin screen wants this one: an empty
-   * array on its own cannot tell "the server has nothing loaded" from "that address is not an
-   * OpenAI-compatible API root", and those need different fixes.
-   */
-  async function listModelsResult(cfgOverride) {
-    const cfg = cfgOverride || await resolveConfig();
-    if (!cfg.enabled) {
-      return { ok: false, models: [], url: null, status: 0, error: 'No provider is selected.' };
-    }
-    const adapter = PROVIDERS[cfg.provider];
-    if (!adapter) {
-      return { ok: false, models: [], url: null, status: 0, error: `Unknown provider “${cfg.provider}”.` };
-    }
-    try {
-      if (adapter.listModelsResult) return await adapter.listModelsResult(cfg);
-      // An adapter that predates this contract still works; it simply cannot explain itself.
-      return { ok: true, models: await adapter.listModels(cfg), url: null, status: 0, error: null };
-    } catch (err) {
-      return { ok: false, models: [], url: null, status: 0, error: err.message };
-    }
-  }
-
-  /**
-   * A fixed-workload speed test for one endpoint. See benchmark.js for why the workload is fixed
-   * rather than the prompt, and why the warm-up is reported rather than discarded.
-   */
-  async function benchmarkEndpoint(cfgOverride, benchOpts) {
-    const cfg = cfgOverride || await resolveConfig();
-    return require('./benchmark').benchmark(complete, cfg, benchOpts || {});
-  }
-
-  // The writing-assist engines are bound to this client's complete() so a caller gets config +
-  // budget + retry for free. Prompt framing is supplied per call by the app (content).
-  const boundPolish = (opts) => polish(complete, opts);
-  const boundGenerate = (opts) => generate(complete, opts);
-
-  return {
-    complete, embed, isEnabled, test, listModels, listModelsResult, withOneRetry,
-    benchmark: benchmarkEndpoint,
-    polish: boundPolish, generate: boundGenerate,
-    facts, AiError, PROVIDERS, DEFAULTS
-  };
-}
-
-module.exports = {
-  // The usage counter behind every ceiling. LAZY: it needs the db-worker driver contract, which
-  // is an OPTIONAL peer — a consumer using only createAiClient/polish/facts must not be made to
-  // install a database package to require this one.
-  get createUsageStore() { return require('./usageStore').createUsageStore; },
-  get createProviderStore() { return require('./providerStore').createProviderStore; },
-  // Speed history. Lazy for the same reason as the others: it needs the db-worker driver contract,
-  // which is an optional peer.
-  get createSpeedStore() { return require('./speedStore').createSpeedStore; },
-  // EXPORTED SO A CONSUMER CAN ASSERT ITS TABLE MATCHES. An app writes its own migration, which is
-  // a hand copy of this DDL — and a copy with nothing comparing it to the original is the failure
-  // mode this repo has already documented twice. providerSchemaFor and usageSchemaFor exist for the
-  // same reason; leaving this one out meant a drift would surface as an INSERT throwing at runtime.
-  get speedSchemaFor() { return require('./speedStore').schemaFor; },
-  // No database behind health, so it loads eagerly like the rest of the seam.
-  ...require('./health'),
-  /**
-   * Where this package's EJS partials live, for the consumer's view-roots list.
-   *
-   * Same contract as backup/server/notify/uploads: the package knows its own layout, the app
-   * puts its own views FIRST so a local file of the same name wins.
-   */
-  viewsDir: require('path').join(__dirname, 'views'),
-  get providerSchemaFor() { return require('./providerStore').schemaFor; },
-  // ── SUPERVISED STACKS (lmx) ─────────────────────────────────────────────────────────────────
-  // The store is LAZY for the same reason as the others: it needs the db-worker driver contract,
-  // which is an optional peer. A consumer using only createAiClient must not be made to install a
-  // database package to require this one.
-  get createLmxStore() { return require('./lmxStore').createLmxStore; },
-  // EXPORTED SO A CONSUMER CAN ASSERT ITS TABLE MATCHES — the migration is a hand copy of this, and
-  // a copy with nothing comparing it to the original is the failure this repo has documented three
-  // times now. The first app to carry the table wrote it with nothing to check against.
-  get lmxSchemaFor() { return require('./lmxStore').schemaFor; },
-  // Does this stack actually work? Four checks in the only order they can run. No database and no
-  // keystore — every credential arrives as an argument — so it loads eagerly.
-  lmxVerify: require('./lmxVerify'),
-  // Engine identity - (instance, id), falling back to name - shared by the router, the stack panel
-  // and the verifier. Apps used to deep-require providers/lmxDiscovery for it; that path still
-  // works, but this is the supported one.
-  findEngine: require('./providers/lmxDiscovery').findEngine,
-  // The counting rules a screen needs. Separate from the verifier because "what did the stack say"
-  // and "what does that mean for what I am relying on" are different questions, and only the second
-  // one needs to know which engines this app has adopted.
-  ...require('./lmxStatus'),
-  get usageSchemaFor() { return require('./usageStore').schemaFor; },
-  createAiClient,
-  PROVIDERS, DEFAULTS,
-  AiError, fromFetchFailure, redact,
-  facts,
-  // THE INPUT SIDE of the same concern facts.js covers on the output side: text somebody else
-  // wrote, placed where a model can read it without being able to give orders. See
-  // untrusted.js for why the fence marker has to be generated per call.
-  untrusted: require('./untrusted'),
-  // ...and the correct ASSEMBLY of it. untrusted.js hands over `fence()` and `rule()` separately;
-  // fenced.js puts them together, because one app assembled them two different ways in two prompt
-  // builders and one of the divergences started refusing correct answers. See fenced.js for the
-  // measurements, including why a fenced document is worth about a third of the defence unless the
-  // caller also states its schema's field names.
-  fenced: require('./fenced'),
-  // Default writing-op catalogues, so an app can build its menus without re-declaring them.
-  POLISH_MODES: require('./polish').MODES,
-  POLISH_TONES: require('./polish').TONES,
-  RETRY_AFTER_MS
-};
+/**
+ * @aria-framework/ai — the AI seam. One `complete()`, several providers behind it, plus the
+ * writing-assist engines (polish/generate) and the fact-preservation guard.
+ *
+ * DEPENDENCY-INJECTED, DATABASE-FREE. The package knows how to talk to a model; it does NOT know
+ * where an app keeps its settings, its credentials or its token ledger. The consumer builds a
+ * client with two functions of its own:
+ *
+ *   const ai = createAiClient({
+ *     resolveConfig,   // async () => resolved config (provider, baseUrl, model, apiKey, caps…)
+ *     budget,          // { assertWithinBudget(cfg, ctx), record(cfg, result, ctx) }  — optional
+ *     logger           // { info, warn, error }                                        — optional
+ *   });
+ *
+ * The provider adapters already take an explicit config and never read a database, which is what
+ * makes the seam testable: a stub adapter and a real adapter are called identically.
+ *
+ * PROMPTS ARE CONTENT AND LIVE IN THE APP. This package carries the mechanism (how to call a model,
+ * how to enforce a token ceiling, how to check a rewrite kept its facts) and generic writing
+ * operations; the words that say "you are editing a reply to a customer" belong to the app.
+ */
+
+'use strict';
+
+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 PROVIDERS = {
+  // 'lmstudio' and 'openai-compatible' are the SAME adapter with different defaults — a kindness to
+  // whoever configures it: an operator running LM Studio should not have to know it speaks a shape
+  // named after somebody else.
+  lmstudio: require('./providers/openai-compatible'),
+  'openai-compatible': require('./providers/openai-compatible'),
+  anthropic: require('./providers/anthropic'),
+  // 0.14.0 — a supervised fleet rather than an address. The engine URL is discovered from the
+  // supervisor's status document per call, the reasoning flag is read from the model the engine
+  // is actually running, and the whole conversation is pinned to a self-signed certificate.
+  lmx: require('./providers/lmx')
+};
+
+const DEFAULTS = {
+  lmstudio: { baseUrl: 'http://localhost:1234/v1', model: 'qwen3.5-9b', label: 'LM Studio' },
+  'openai-compatible': { baseUrl: 'http://localhost:11434/v1', model: '', label: 'The model server' },
+  anthropic: { baseUrl: 'https://api.anthropic.com/v1', model: 'claude-sonnet-4-5', label: 'Claude' },
+  // No baseUrl: an lmx engine's address is never configured, only discovered.
+  lmx: { baseUrl: '', model: '', label: 'lmx engine' }
+};
+
+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() {} };
+
+/**
+ * Build an AI client bound to one app's config resolution and token budget.
+ * @param {{resolveConfig: () => Promise<object>, budget?: object, logger?: object}} deps
+ */
+function createAiClient(deps = {}) {
+  const resolveConfig = deps.resolveConfig;
+  if (typeof resolveConfig !== 'function') {
+    throw new Error('createAiClient: resolveConfig must be an async function returning the resolved config');
+  }
+  const log = deps.logger || NOOP_LOGGER;
+  const meter = deps.budget || NOOP_BUDGET;
+
+  /**
+   * Try once more, but only for the failure where trying again could help — a local provider that
+   * dropped the connection while loading a model. A cancelled call, a timeout, a rate limit or a slow
+   * failure is never retried (see the guards below).
+   *
+   * A 429 FAILS FAST (0.25.0). 0.23/0.24 slept its Retry-After here (up to 10 s), below every app's
+   * dispatcher: every engine on an lmx stack shares one gateway key, so each failover re-hit the same
+   * throttle and paid the wait again, and an OpenAI-compatible primary that sent Retry-After delayed a
+   * healthy backup by the full wait. Decided 2026-10-01: the client does not wait. The error carries
+   * `retryAfterMs` (and `lmxSkip: 'lmx_throttled'` from an lmx engine) for a caller that chooses to.
+   */
+  async function withOneRetry(run, opts = {}) {
+    const startedAt = Date.now();
+    try {
+      return await run();
+    } catch (err) {
+      if (opts.signal && opts.signal.aborted) throw err;
+      if (!err || !err.retryable) throw err;
+      const elapsed = Date.now() - startedAt;
+      // A TIMEOUT is the deadline itself being reached — retrying waits the whole deadline again. A
+      // RATE LIMIT is the provider asking for less pressure. A slow `unreachable` is not the
+      // sub-second dropped-connection transient this retry exists for. None of those retry.
+      if (err.kind === 'timeout' || err.kind === 'rate_limit' || elapsed > RETRY_ONLY_IF_FAILED_WITHIN_MS) {
+        log.warn(`AI: ${err.kind} after ${elapsed}ms — not retrying (${err.message})`);
+        throw err;
+      }
+      log.warn(`AI: ${err.kind} — trying once more in ${RETRY_AFTER_MS}ms (${err.message})`);
+      await new Promise((r) => setTimeout(r, RETRY_AFTER_MS));
+      return run();
+    }
+  }
+
+  /**
+   * 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
+   * @param {object} [cfgOverride] the resolved config, when the caller already has it
+   */
+  async function complete(opts, cfgOverride) {
+    // `reasoning` (0.26.0) is checked here for EVERY provider, first: a typo is the caller's bug
+    // whichever endpoint the route happens to pick, and must not wait for an lmx one to surface.
+    assertReasoning(opts && opts.reasoning);
+    const cfg = cfgOverride || await resolveConfig();
+    if (!cfg.enabled) {
+      throw new AiError('disabled', 'AI assistance is switched off. An administrator can enable it in Settings.');
+    }
+    // A MODEL NAME IS REQUIRED OF EVERY PROVIDER THAT HAS ONE TO CONFIGURE — which is all of them
+    // except a supervised stack. There the model is a FACT the supervisor reports about an engine,
+    // not a setting: the operator picks an engine and whatever it is running answers. Insisting on
+    // a model name would make an lmx endpoint unusable by demanding the one field the design says
+    // not to store, and would say so with a message naming nothing an operator could go and fill in.
+    if (!cfg.model && cfg.provider !== 'lmx') {
+      throw new AiError('unconfigured', 'No model name is configured.');
+    }
+    const adapter = PROVIDERS[cfg.provider];
+    if (!adapter) {
+      throw new AiError('unconfigured', `No adapter is registered for provider "${cfg.provider}".`);
+    }
+
+    // The ceiling, before the call — the only place a limit can be enforced without being bypassable
+    // 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;
+    }
+
+    const result = await withOneRetry(() => adapter.complete(cfg, callOpts), opts);
+
+    // ...and the counter after it, AWAITED: two calls in quick succession must both be counted
+    // before the second's ceiling check reads the total, or the limit is enforced against a stale one.
+    await meter.record(cfg, result, { ticketId: opts.ticketId });
+
+    log.info(`AI: ${cfg.provider}/${result.model} ${result.usage.total} tokens in ${result.ms}ms`);
+    return result;
+  }
+
+  /**
+   * Embed one or more strings, with the same retry policy as complete() — a fast dropped connection
+   * is retried once; a 429 fails fast (0.25.0, see withOneRetry). Embeddings are idempotent, so the
+   * one resend is always safe.
+   *
+   * THE CONFIG IS THE CALLER'S. An app resolves its embedding settings separately from completion
+   * (embeddingModel, often a different endpoint), so this never falls back to resolveConfig().
+   * No budget metering - embeddings were never metered, and starting is a separate decision.
+   * @param {object} cfg the resolved embedding config (provider, embeddingModel, …)
+   * @param {string|string[]} texts
+   * @param {{signal?: AbortSignal}} [opts]
+   */
+  async function embed(cfg, texts, opts = {}) {
+    // EXPLICITLY DISABLED is refused, as complete() refuses it (the review found embed ignored it).
+    // Strictly `false`: an embedding config the caller built without the flag is still honoured.
+    if (cfg && cfg.enabled === false) {
+      throw new AiError('disabled', 'This endpoint is switched off.');
+    }
+    const adapter = cfg && PROVIDERS[cfg.provider];
+    if (!adapter) {
+      throw new AiError('unconfigured', `No adapter is registered for provider "${cfg && cfg.provider}".`);
+    }
+    if (typeof adapter.embed !== 'function') {
+      throw new AiError('unsupported', `${cfg.label || cfg.provider} does not support embeddings.`);
+    }
+    return withOneRetry(() => adapter.embed(cfg, texts), opts);
+  }
+
+  /** Is there a provider configured at all? Callers use this to decide whether to render a control. */
+  async function isEnabled() {
+    return (await resolveConfig()).enabled;
+  }
+
+  /** A short round trip for an admin "Test connection". NEVER THROWS — it reports what is wrong. */
+  async function test(cfgOverride) {
+    const cfg = cfgOverride || await resolveConfig();
+    if (!cfg.enabled) return { ok: false, kind: 'disabled', error: 'No provider is selected.' };
+    try {
+      const r = await complete({
+        system: 'Reply with the single word: ready. Do not explain.',
+        messages: [{ role: 'user', content: 'ready?' }],
+        maxTokens: 512,
+        temperature: 0,
+        skipBudget: true            // an admin diagnosing a provider must not be blocked by a full budget
+      }, cfg);
+      return {
+        ok: true, model: r.model, ms: r.ms, reply: (r.text || '').trim().slice(0, 60), usage: r.usage,
+        finishReason: r.finishReason || null, reasoned: !!r.reasonedFor
+      };
+    } catch (err) {
+      if (err instanceof AiError) return { ok: false, kind: err.kind, error: err.message, retryable: err.retryable };
+      return { ok: false, kind: 'bad_response', error: err.message };
+    }
+  }
+
+  /** What the server has loaded, for an admin model picker. Empty when it cannot say. */
+  async function listModels(cfgOverride) {
+    return (await listModelsResult(cfgOverride)).models;
+  }
+
+  /**
+   * The model list and WHY it is the length it is.
+   *
+   * Callers that only want names should use listModels(). An admin screen wants this one: an empty
+   * array on its own cannot tell "the server has nothing loaded" from "that address is not an
+   * OpenAI-compatible API root", and those need different fixes.
+   */
+  async function listModelsResult(cfgOverride) {
+    const cfg = cfgOverride || await resolveConfig();
+    if (!cfg.enabled) {
+      return { ok: false, models: [], url: null, status: 0, error: 'No provider is selected.' };
+    }
+    const adapter = PROVIDERS[cfg.provider];
+    if (!adapter) {
+      return { ok: false, models: [], url: null, status: 0, error: `Unknown provider “${cfg.provider}”.` };
+    }
+    try {
+      if (adapter.listModelsResult) return await adapter.listModelsResult(cfg);
+      // An adapter that predates this contract still works; it simply cannot explain itself.
+      return { ok: true, models: await adapter.listModels(cfg), url: null, status: 0, error: null };
+    } catch (err) {
+      return { ok: false, models: [], url: null, status: 0, error: err.message };
+    }
+  }
+
+  /**
+   * A fixed-workload speed test for one endpoint. See benchmark.js for why the workload is fixed
+   * rather than the prompt, and why the warm-up is reported rather than discarded.
+   */
+  async function benchmarkEndpoint(cfgOverride, benchOpts) {
+    const cfg = cfgOverride || await resolveConfig();
+    return require('./benchmark').benchmark(complete, cfg, benchOpts || {});
+  }
+
+  // The writing-assist engines are bound to this client's complete() so a caller gets config +
+  // budget + retry for free. Prompt framing is supplied per call by the app (content).
+  const boundPolish = (opts) => polish(complete, opts);
+  const boundGenerate = (opts) => generate(complete, opts);
+
+  return {
+    complete, embed, isEnabled, test, listModels, listModelsResult, withOneRetry,
+    benchmark: benchmarkEndpoint,
+    polish: boundPolish, generate: boundGenerate,
+    facts, AiError, PROVIDERS, DEFAULTS
+  };
+}
+
+module.exports = {
+  // The usage counter behind every ceiling. LAZY: it needs the db-worker driver contract, which
+  // is an OPTIONAL peer — a consumer using only createAiClient/polish/facts must not be made to
+  // install a database package to require this one.
+  get createUsageStore() { return require('./usageStore').createUsageStore; },
+  get createProviderStore() { return require('./providerStore').createProviderStore; },
+  // Speed history. Lazy for the same reason as the others: it needs the db-worker driver contract,
+  // which is an optional peer.
+  get createSpeedStore() { return require('./speedStore').createSpeedStore; },
+  // EXPORTED SO A CONSUMER CAN ASSERT ITS TABLE MATCHES. An app writes its own migration, which is
+  // a hand copy of this DDL — and a copy with nothing comparing it to the original is the failure
+  // mode this repo has already documented twice. providerSchemaFor and usageSchemaFor exist for the
+  // same reason; leaving this one out meant a drift would surface as an INSERT throwing at runtime.
+  get speedSchemaFor() { return require('./speedStore').schemaFor; },
+  // No database behind health, so it loads eagerly like the rest of the seam.
+  ...require('./health'),
+  /**
+   * Where this package's EJS partials live, for the consumer's view-roots list.
+   *
+   * Same contract as backup/server/notify/uploads: the package knows its own layout, the app
+   * puts its own views FIRST so a local file of the same name wins.
+   */
+  viewsDir: require('path').join(__dirname, 'views'),
+  get providerSchemaFor() { return require('./providerStore').schemaFor; },
+  // ── SUPERVISED STACKS (lmx) ─────────────────────────────────────────────────────────────────
+  // The store is LAZY for the same reason as the others: it needs the db-worker driver contract,
+  // which is an optional peer. A consumer using only createAiClient must not be made to install a
+  // database package to require this one.
+  get createLmxStore() { return require('./lmxStore').createLmxStore; },
+  // EXPORTED SO A CONSUMER CAN ASSERT ITS TABLE MATCHES — the migration is a hand copy of this, and
+  // a copy with nothing comparing it to the original is the failure this repo has documented three
+  // times now. The first app to carry the table wrote it with nothing to check against.
+  get lmxSchemaFor() { return require('./lmxStore').schemaFor; },
+  // Does this stack actually work? Four checks in the only order they can run. No database and no
+  // keystore — every credential arrives as an argument — so it loads eagerly.
+  lmxVerify: require('./lmxVerify'),
+  // Engine identity - (instance, id), falling back to name - shared by the router, the stack panel
+  // and the verifier. Apps used to deep-require providers/lmxDiscovery for it; that path still
+  // works, but this is the supported one.
+  findEngine: require('./providers/lmxDiscovery').findEngine,
+  // The counting rules a screen needs. Separate from the verifier because "what did the stack say"
+  // and "what does that mean for what I am relying on" are different questions, and only the second
+  // one needs to know which engines this app has adopted.
+  ...require('./lmxStatus'),
+  get usageSchemaFor() { return require('./usageStore').schemaFor; },
+  createAiClient,
+  PROVIDERS, DEFAULTS,
+  AiError, fromFetchFailure, redact,
+  facts,
+  // THE INPUT SIDE of the same concern facts.js covers on the output side: text somebody else
+  // wrote, placed where a model can read it without being able to give orders. See
+  // untrusted.js for why the fence marker has to be generated per call.
+  untrusted: require('./untrusted'),
+  // ...and the correct ASSEMBLY of it. untrusted.js hands over `fence()` and `rule()` separately;
+  // fenced.js puts them together, because one app assembled them two different ways in two prompt
+  // builders and one of the divergences started refusing correct answers. See fenced.js for the
+  // measurements, including why a fenced document is worth about a third of the defence unless the
+  // caller also states its schema's field names.
+  fenced: require('./fenced'),
+  // Default writing-op catalogues, so an app can build its menus without re-declaring them.
+  POLISH_MODES: require('./polish').MODES,
+  POLISH_TONES: require('./polish').TONES,
+  // The values complete({ reasoning }) accepts (0.26.0), for a caller that validates its own config.
+  REASONING_MODES,
+  RETRY_AFTER_MS
+};

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}`;
 }
 
 /**

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.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

@@ -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

@@ -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) {