@aria-framework/ai 0.14.3 → 0.15.0

package/browser/ai-panels.js

@@ -0,0 +1,113 @@
+/**
+ * The fold on the Inference list, and prefilling the supervisor form from a panel.
+ *
+ * WHY ANYTHING FOLDS. A stable stack is four engines, three credentials, a certificate fingerprint
+ * and a verification report — worth having, not worth reading every time you open this page to do
+ * something else. Folded, a panel is one line that still carries the whole verdict: status, the
+ * count of what depends on it, all three credentials and when it was last checked. Folding hides
+ * detail; it must never hide the reason you would have opened it.
+ *
+ * A PANEL WITH A PROBLEM IGNORES WHAT YOU REMEMBERED. `data-panel-attention` is stamped by the
+ * server on anything with a missing engine, an expiring certificate, a failed check or a nearly
+ * spent cap. Those open and stay open. Attention beats tidiness — the alternative is a page that
+ * quietly honours a fold you chose last week and hides the thing that broke yesterday.
+ *
+ * THE PREFERENCE IS PER BROWSER AND DISPOSABLE. It is a convenience about how a page looks to one
+ * person, so localStorage is the right home and losing it costs nothing. Every access is guarded:
+ * a browser set to block site data throws on read, and a settings page must not break because
+ * somebody tightened their privacy settings.
+ */
+(function () {
+  'use strict';
+
+  var KEY = 's101.ai.panels';
+
+  function readPrefs() {
+    try {
+      return JSON.parse(window.localStorage.getItem(KEY) || '{}') || {};
+    } catch (e) {
+      return {};
+    }
+  }
+
+  function writePref(id, open) {
+    try {
+      var prefs = readPrefs();
+      prefs[id] = !!open;
+      window.localStorage.setItem(KEY, JSON.stringify(prefs));
+    } catch (e) { /* private window, or site data blocked — the fold still works for this visit */ }
+  }
+
+  function bodyOf(panel) {
+    var btn = panel.querySelector('[data-panel-toggle]');
+    if (!btn) return null;
+    return document.getElementById(btn.getAttribute('aria-controls'));
+  }
+
+  function setOpen(panel, open, remember) {
+    var btn = panel.querySelector('[data-panel-toggle]');
+    var body = bodyOf(panel);
+    if (!btn || !body) return;
+    // `hidden`, not a style: the server renders the closed state the same way, so a panel does not
+    // flicker open on load before this script runs.
+    body.hidden = !open;
+    btn.setAttribute('aria-expanded', open ? 'true' : 'false');
+    panel.classList.toggle('panel-open', open);
+    if (remember) writePref(panel.getAttribute('data-panel'), open);
+  }
+
+  function restore() {
+    var prefs = readPrefs();
+    var panels = document.querySelectorAll('[data-panel]');
+    for (var i = 0; i < panels.length; i += 1) {
+      var panel = panels[i];
+      var id = panel.getAttribute('data-panel');
+      // The server already opened this one and means it. Do not consult the preference at all —
+      // reading it and then ignoring it is the same thing, but invites somebody to "fix" it later.
+      if (panel.hasAttribute('data-panel-attention')) {
+        setOpen(panel, true, false);
+        continue;
+      }
+      if (Object.prototype.hasOwnProperty.call(prefs, id)) setOpen(panel, !!prefs[id], false);
+    }
+  }
+
+  document.addEventListener('click', function (ev) {
+    var toggle = ev.target.closest('[data-panel-toggle]');
+    if (toggle) {
+      var panel = toggle.closest('[data-panel]');
+      if (!panel) return;
+      var body = bodyOf(panel);
+      setOpen(panel, !!(body && body.hidden), true);
+      return;
+    }
+
+    // EDIT PREFILLS FROM THE PANEL, so changing a stack is not retyping it.
+    //
+    // The two secrets stay BLANK on purpose. Blank means keep, which is the rule the handler
+    // already follows, and it is why correcting an address cannot cost you the credentials. There
+    // is no read-back to prefill them with in any case: they are write-only by design.
+    var edit = ev.target.closest('[data-lmx-edit]');
+    if (!edit) return;
+    var src = document.querySelector('[data-lmx-id="' + edit.getAttribute('data-lmx-edit') + '"]');
+    var form = document.querySelector('#lmx-new form');
+    if (!src || !form) return;
+    var set = function (name, value) {
+      var field = form.querySelector('[name="' + name + '"]');
+      if (field) field.value = value == null ? '' : value;
+    };
+    set('id', src.getAttribute('data-lmx-id'));
+    set('label', src.getAttribute('data-lmx-label'));
+    set('status_url', src.getAttribute('data-lmx-url'));
+    set('status_token', '');
+    set('engines_key', '');
+    var heading = document.querySelector('#lmx-new .card-title');
+    if (heading) heading.textContent = 'Change ' + (src.getAttribute('data-lmx-label') || src.getAttribute('data-lmx-id'));
+  });
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', restore);
+  } else {
+    restore();
+  }
+})();

package/index.js

@@ -1,245 +1,261 @@
-/**
- * @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 failures where trying again could help — a local provider that
-   * dropped the connection while loading a model, and nothing else. A cancelled call, a timeout, a
-   * rate limit or a slow failure is never retried (see the guards below).
-   */
-  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;
-  }
-
-  /** 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, 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; },
-  get usageSchemaFor() { return require('./usageStore').schemaFor; },
-  createAiClient,
-  PROVIDERS, DEFAULTS,
-  AiError, fromFetchFailure, redact,
-  facts,
-  // 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 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 failures where trying again could help — a local provider that
+   * dropped the connection while loading a model, and nothing else. A cancelled call, a timeout, a
+   * rate limit or a slow failure is never retried (see the guards below).
+   */
+  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;
+  }
+
+  /** 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, 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'),
+  // 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,
+  // 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
+};