@aria-framework/ai 0.13.0 → 0.14.1

package/index.js

@@ -33,13 +33,19 @@ const PROVIDERS = {
   // named after somebody else.
   lmstudio: require('./providers/openai-compatible'),
   'openai-compatible': require('./providers/openai-compatible'),
-  anthropic: require('./providers/anthropic')
+  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' }
+  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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aria-framework/ai",
   "description": "Aria App Framework — 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.13.0",
+  "version": "0.14.1",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {
@@ -16,16 +16,33 @@
     "generate.js",
     "providers/openai-compatible.js",
     "providers/anthropic.js",
-    "browser/ai-polish.js", "usageStore.js", "providerStore.js","speedStore.js", "health.js",
-    "benchmark.js", "views/"
+    "browser/ai-polish.js",
+    "usageStore.js",
+    "providerStore.js",
+    "speedStore.js",
+    "health.js",
+    "benchmark.js",
+    "views/",
+    "providers/lmx.js",
+    "providers/lmxDiscovery.js",
+    "providers/lmxTransport.js"
   ],
   "peerDependencies": {
-    "@aria-framework/db-worker": ">=0.7.0"
+    "@aria-framework/db-worker": ">=0.7.0",
+    "undici": ">=6"
   },
   "peerDependenciesMeta": {
-    "@aria-framework/db-worker": { "optional": true }
+    "@aria-framework/db-worker": {
+      "optional": true
+    },
+    "undici": {
+      "optional": true
+    }
   },
   "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/packaging.js && node test/views.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/packaging.js && node test/views.js"
+  },
+  "devDependencies": {
+    "undici": "^8.10.0"
   }
 }

package/providerStore.js

@@ -41,7 +41,18 @@ const FIELDS = [
   //
   // An app that has not added the column is unaffected: clean() skips anything undefined, so the
   // field is only ever written by a caller that knows about it.
-  'min_tokens_per_sec'
+  'min_tokens_per_sec',
+  // WHICH ENGINE ON WHICH SUPERVISED STACK, for `kind: lmx`. Identity is the PAIR: engine names are
+  // stable but say nothing about purpose, and they collide across deployments — `analysis` exists
+  // on every stack — so a name alone would let a mis-pointed status URL send work to another
+  // machine and get plausible answers back.
+  //
+  // Deliberately NOT reusing `model`: the status document already carries `model` as a fact about
+  // the engine, and conflating the two would make a model swap look like a configuration change.
+  //
+  // An lmx row has no meaningful `base_url`. The address is discovered from the supervisor on every
+  // call, because ports move and a stored URL is the one thing the contract says not to keep.
+  'lmx_instance', 'lmx_engine'
 ];
 
 const NUMERIC = new Set(['context_tokens', 'max_tokens', 'timeout_ms', 'daily_token_cap', 'enabled',
@@ -208,8 +219,14 @@ function schemaFor(dialect) {
   -- can report a verdict rather than a number to be remembered. 0 means no expectation was set,
   -- which is not the same as expecting it to be slow.
   min_tokens_per_sec INTEGER NOT NULL DEFAULT 0,
+  -- WHICH ENGINE ON WHICH SUPERVISED STACK, for kind 'lmx'. Identity is the PAIR: engine names are
+  -- stable but collide across deployments, so a name alone would let a mis-pointed status URL send
+  -- work to another stack's engine of the same name. An lmx row stores no base_url at all — the
+  -- address is discovered from the supervisor on every call.
+  lmx_instance      TEXT,
+  lmx_engine        TEXT,
   created_at        TEXT    NOT NULL DEFAULT (${t.now()})
 `;
 }
 
-module.exports = { createProviderStore, schemaFor, _assertId: assertId };
+module.exports = { createProviderStore, schemaFor, _assertId: assertId, _fields: FIELDS };

package/providers/lmxDiscovery.js

@@ -0,0 +1,209 @@
+/**
+ * Knowing WHERE to send inference, when the answer changes underneath you.
+ *
+ * An lmx stack is a supervisor and several engines. The supervisor publishes a status document
+ * saying which engines exist and what state each is in; the engines take the work. The supervisor
+ * is deliberately NOT on the request path — a client calls engines directly, so a supervisor fault
+ * cannot break an in-flight request. This module is the only part that talks to the supervisor, and
+ * it never carries work.
+ *
+ * FOUR RULES FROM THE CONTRACT, each of which exists because ignoring it fails silently:
+ *
+ *   SELECT *FOR* `healthy`, NEVER AGAINST A LIST OF BAD STATES. The supervisor may add a state
+ *   later; a client testing `state !== 'failed'` would start routing to it the day it appears.
+ *   Testing `state === 'healthy'` cannot.
+ *
+ *   `draining` MEANS FINISH WHAT YOU SENT AND SEND NOTHING NEW. It is the trap in the whole
+ *   contract: a draining engine still answers 200 on its own /health, because draining is the
+ *   supervisor's concept and llama-server knows nothing about it. Probe it yourself and it looks
+ *   fine. Ignore the state and every rolling restart kills whatever was in flight.
+ *
+ *   A STATUS OUTAGE IS NOT AN INFERENCE OUTAGE. If the listener is unreachable, keep routing on the
+ *   last good document. Halting would put the supervisor back on the request path it was designed
+ *   to stay off — turning a supervisor blip into a total loss of inference. Bounded, because
+ *   routing on a view from an hour ago is its own kind of wrong.
+ *
+ *   THE URL COMES FROM THE DOCUMENT, NEVER FROM CONFIG. Ports move. An engine bound to 0.0.0.0 is
+ *   advertised at the same host the client used to reach the listener, because that is an address
+ *   known to work from where the client is standing.
+ *
+ * IDENTITY IS (instance, name). Engine names are stable but say nothing about purpose, and they
+ * collide across deployments — `analysis` exists on every stack. The document names its own
+ * instance, so pointing a status URL at a different stack is caught here rather than discovered as
+ * work quietly going to the wrong machine.
+ *
+ * NOTHING HERE THROWS INTO A REQUEST. A discovery failure is an ABSENCE OF A ROUTE, which the
+ * caller turns into "try the next endpoint", not an error that trips a breaker on an engine that
+ * is very probably fine.
+ */
+
+'use strict';
+
+/** Two seconds is what the contract suggests; the document is served no-store. */
+const POLL_MS = 2000;
+
+/**
+ * How long a document stays usable once the listener goes quiet.
+ *
+ * Long enough that a supervisor restart is invisible, short enough that nobody is routing on a view
+ * from another era. The contract says "a few minutes is reasonable".
+ */
+const STALE_MS = 3 * 60 * 1000;
+
+/** The only state that may receive new work. */
+const HEALTHY = 'healthy';
+
+/**
+ * @param {object} opts
+ * @param {string} opts.statusUrl      e.g. https://host:9443/status
+ * @param {string} opts.instance       the deployment this row believes it is talking to
+ * @param {string} opts.token          bearer for the status listener
+ * @param {string} [opts.ca]           PEM of the certificate to pin
+ * @param {number} [opts.staleMs]
+ * @param {number} [opts.pollMs]
+ * @param {object} [opts.logger]
+ * @param {function} [opts.fetchImpl]  injectable for tests; defaults to global fetch
+ * @param {function} [opts.now]        injectable clock
+ */
+function createLmxDiscovery(opts = {}) {
+  const {
+    statusUrl,
+    instance,
+    token,
+    ca = null,
+    staleMs = STALE_MS,
+    pollMs = POLL_MS,
+    logger = console,
+    fetchImpl,
+    now = () => Date.now()
+  } = opts;
+
+  if (!statusUrl) throw new Error('createLmxDiscovery: statusUrl is required');
+  if (!instance) throw new Error('createLmxDiscovery: instance is required — identity is (instance, name)');
+
+  let doc = null;         // the last document that parsed and matched our instance
+  let docAt = 0;
+  let lastError = null;
+  let timer = null;
+
+  /**
+   * The pinned transport — see providers/lmxTransport.js for why this is not NODE_EXTRA_CA_CERTS
+   * and never `rejectUnauthorized: false`. Built lazily and cached there, so a consumer that never
+   * configures lmx does not load undici at all.
+   */
+  const transport = () => (fetchImpl
+    ? { fetch: fetchImpl, dispatcher: undefined }
+    : require('./lmxTransport').lmxTransport(ca));
+
+  async function fetchOnce() {
+    const t = transport();
+    const res = await t.fetch(statusUrl, {
+      headers: { Authorization: `Bearer ${token}` },
+      dispatcher: t.dispatcher
+    });
+    if (!res.ok) {
+      const err = new Error(`status listener answered ${res.status}`);
+      err.status = res.status;
+      throw err;
+    }
+    return res.json();
+  }
+
+  /**
+   * Fetch once and adopt the result if it is usable.
+   *
+   * A document for the WRONG INSTANCE is rejected rather than adopted. It is not a transport
+   * failure — the listener answered perfectly — so it is reported as a configuration error, which
+   * is what it is. Adopting it would route `analysis` to another deployment's `analysis`.
+   */
+  async function refresh() {
+    try {
+      const next = await fetchOnce();
+      if (next && next.instance && next.instance !== instance) {
+        lastError = `status listener at ${statusUrl} reports instance "${next.instance}", not `
+          + `"${instance}" — this endpoint is pointed at a different stack, and engine names `
+          + 'collide across stacks';
+        logger.error(`lmx: ${lastError}`);
+        return { ok: false, error: lastError };
+      }
+      doc = next;
+      docAt = now();
+      lastError = null;
+      return { ok: true, doc: next };
+    } catch (e) {
+      lastError = e.message;
+      // LOUDLY, per the contract — and with the age, because "unreachable" matters differently at
+      // four seconds and at four minutes.
+      logger.warn(`lmx: status unreachable (${e.message}); routing on a document ${ageSec()}s old`);
+      return { ok: false, error: e.message };
+    }
+  }
+
+  const ageMs = () => (docAt ? now() - docAt : Infinity);
+  const ageSec = () => (docAt ? Math.round(ageMs() / 1000) : 0);
+  const isStale = () => ageMs() > staleMs;
+
+  /** Every engine in the last usable document. Empty when there is nothing fresh enough to say. */
+  function engines() {
+    if (!doc || isStale()) return [];
+    return Array.isArray(doc.engines) ? doc.engines : [];
+  }
+
+  /**
+   * The engine record for `name`, whatever state it is in — for a health card, which needs to show
+   * "draining" rather than "gone".
+   */
+  const engine = (name) => engines().find((e) => e && e.name === name) || null;
+
+  /**
+   * Where to send work for `name`, or null.
+   *
+   * Returns a REASON alongside, because the caller has to distinguish "this engine is fine and busy
+   * being replaced" from "we cannot see the stack" from "there is no such engine" — three different
+   * things that all mean "not right now" and only one of which is anybody's fault.
+   */
+  function resolve(name) {
+    if (!doc) return { url: null, reason: 'no_document', detail: lastError };
+    if (isStale()) return { url: null, reason: 'stale', detail: `${ageSec()}s old` };
+
+    const e = engine(name);
+    if (!e) return { url: null, reason: 'unknown_engine' };
+
+    // Select FOR healthy. `draining`, `restarting`, and any state invented after this was written
+    // all fail this test, which is the property worth having.
+    if (e.state !== HEALTHY) return { url: null, reason: 'not_healthy', detail: e.state };
+    if (!e.url) return { url: null, reason: 'no_url' };
+
+    return { url: e.url, engine: e };
+  }
+
+  function start() {
+    if (timer) return;
+    refresh();
+    timer = setInterval(refresh, pollMs);
+    if (timer.unref) timer.unref();   // never hold a process open for a poller
+  }
+
+  function stop() {
+    if (timer) clearInterval(timer);
+    timer = null;
+  }
+
+  return {
+    start, stop, refresh, resolve, engines, engine,
+    /** The pinned transport, so ENGINE calls reach the same host over the same trust. */
+    transport,
+    /** For a diagnostics panel: what we know and how old it is. */
+    status: () => ({
+      instance,
+      statusUrl,
+      overall: doc ? doc.state : null,
+      engineCount: engines().length,
+      ageSec: doc ? ageSec() : null,
+      stale: doc ? isStale() : true,
+      lastError
+    })
+  };
+}
+
+module.exports = { createLmxDiscovery, POLL_MS, STALE_MS, HEALTHY };

package/providers/lmxTransport.js

@@ -0,0 +1,60 @@
+/**
+ * The pinned HTTPS transport an lmx stack is reached over — status listener AND engines.
+ *
+ * WHY THIS IS NOT `NODE_EXTRA_CA_CERTS`. That is the first thing the contract suggests and the
+ * wrong answer here, for three reasons: it is read once before Node starts, so a certificate that
+ * lives in the database can never get into it; it is PROCESS-GLOBAL, so a second stack with its own
+ * certificate is impossible and every unrelated outbound request in the app silently gains a new
+ * trusted root; and it cannot be overridden per engine, which the configuration deliberately
+ * allows.
+ *
+ * WHY NOT `rejectUnauthorized: false`. Because that is not "ignore this one self-signed
+ * certificate", it is "accept any certificate from anyone able to answer on that address" — the
+ * whole attack pinning exists to stop. The option appears nowhere in this package and a test
+ * asserts its absence.
+ *
+ * `ca` REPLACES the trust store for this connection rather than adding to it. That is what makes it
+ * a pin: only this certificate is accepted, not this certificate plus every public CA.
+ *
+ * UNDICI'S OWN `fetch`, NOT THE GLOBAL ONE. Node's global fetch is built on a private copy of
+ * undici, and there is no supported way to hand it a dispatcher from the copy installed here — the
+ * two do not have to recognise each other's classes. Using the installed package for both halves
+ * removes the question entirely.
+ */
+
+'use strict';
+
+/** Cache by certificate text: one agent per distinct cert, not one per request. */
+const agents = new Map();
+
+function requireUndici() {
+  try {
+    return require('undici');
+  } catch (e) {
+    throw new Error(
+      'lmx needs the `undici` package to pin a self-signed certificate — Node\'s built-in fetch '
+      + 'cannot be given a certificate authority. Install it: npm install undici'
+    );
+  }
+}
+
+/**
+ * @param {string|null} ca PEM text of the certificate to pin. Null means the system trust store,
+ *        which is correct for a stack behind a normally-issued certificate.
+ * @returns {{fetch: function, dispatcher: object|undefined}}
+ */
+function lmxTransport(ca) {
+  if (!ca) return { fetch: globalThis.fetch, dispatcher: undefined };
+
+  const key = String(ca);
+  if (!agents.has(key)) {
+    const { Agent } = requireUndici();
+    agents.set(key, new Agent({ connect: { ca: key } }));
+  }
+  return { fetch: requireUndici().fetch, dispatcher: agents.get(key) };
+}
+
+/** Test seam: forget the cached agents so a rotated certificate is picked up. */
+lmxTransport._reset = () => agents.clear();
+
+module.exports = { lmxTransport };

package/providers/openai-compatible.js

@@ -20,6 +20,16 @@ const { AiError, fromFetchFailure, redact } = require('../error');
  *          temperature?:number, schema?:object, signal?:AbortSignal}} opts
  * @returns {Promise<{text:string, json:object|null, model:string, usage:object, ms:number}>}
  */
+/**
+ * The HTTP transport for this config.
+ *
+ * Defaults to the global fetch, which is right for every provider reached over ordinary TLS. A
+ * caller that must PIN a certificate — lmx, whose stack is self-signed — passes its own
+ * { fetch, dispatcher } through cfg.transport, so engine calls travel over the same pinned trust
+ * as the status poll rather than falling back to the system trust store for the actual work.
+ */
+const tx = (cfg) => (cfg && cfg.transport) || { fetch: globalThis.fetch, dispatcher: undefined };
+
 async function complete(cfg, opts) {
   const label = cfg.label || 'The model server';
   const url = apiRoot(cfg.baseUrl) + '/chat/completions';
@@ -31,6 +41,13 @@ async function complete(cfg, opts) {
   for (const m of opts.messages || []) messages.push({ role: m.role, content: m.content });
 
   const body = {
+    // SERVER-SPECIFIC ARGUMENTS THIS ADAPTER KNOWS NOTHING ABOUT, spread FIRST so nothing in a
+    // passthrough can override the fields below — a caller must not be able to change the model or
+    // turn on streaming this way. Its purpose is arguments that are real, documented and outside
+    // the OpenAI schema: llama.cpp's `chat_template_kwargs`, gpt-oss's `reasoning_effort`. Both are
+    // load-bearing — without the right one the model spends its whole budget reasoning and returns
+    // empty content with finish_reason "length", and no error at all.
+    ...(opts.extra || {}),
     model: cfg.model,
     messages,
     max_tokens: opts.maxTokens || 1024,
@@ -55,7 +72,8 @@ async function complete(cfg, opts) {
 
   let res;
   try {
-    res = await fetch(url, {
+    res = await tx(cfg).fetch(url, {
+      dispatcher: tx(cfg).dispatcher,
       method: 'POST',
       headers: Object.assign(
         { 'Content-Type': 'application/json' },
@@ -304,7 +322,8 @@ function normaliseUsage(u) {
 async function listModelsResult(cfg) {
   const url = apiRoot(cfg.baseUrl) + '/models';
   try {
-    const res = await fetch(url, {
+    const res = await tx(cfg).fetch(url, {
+      dispatcher: tx(cfg).dispatcher,
       headers: cfg.apiKey ? { Authorization: `Bearer ${cfg.apiKey}` } : {},
       signal: AbortSignal.timeout(cfg.timeoutMs || 10000)
     });
@@ -353,7 +372,8 @@ async function embed(cfg, texts) {
   const timer = setTimeout(() => controller.abort(), cfg.timeoutMs || 60000);
   let res;
   try {
-    res = await fetch(url, {
+    res = await tx(cfg).fetch(url, {
+      dispatcher: tx(cfg).dispatcher,
       method: 'POST', headers, signal: controller.signal,
       body: JSON.stringify({ model: cfg.embeddingModel, input: list })
     });