@aria-framework/ai 0.25.0 → 0.26.1

package/index.js

@@ -1,309 +1,352 @@
-/**
- * @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 started = Date.now();
+    let result;
+    try {
+      result = await withOneRetry(() => adapter.complete(cfg, callOpts), opts);
+    } catch (err) {
+      // A FAILED CALL CAN STILL HAVE SPENT TOKENS (0.26.1) — a model that thought until it ran out of
+      // room, a structured reply cut off mid-bracket. Recording only successes let a benchmark or a
+      // connection test on such a model run outside the ceiling. Adapters put normalised usage on
+      // the error; a failure that spent nothing (refused, unreachable) carries none and is not counted.
+      // The ledger failing must never replace the error the caller needs to see.
+      if (err && err.usage && err.usage.total > 0) {
+        try {
+          await meter.record(cfg, { usage: err.usage, model: cfg.model, ms: Date.now() - started, failed: true },
+            { ticketId: opts.ticketId });
+        } catch (recErr) {
+          log.warn(`AI: usage of a failed call not recorded (${recErr.message})`);
+        }
+      }
+      throw err;
+    }
+
+    // ...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
+};