@aria-framework/ai 0.22.0 → 0.24.0

package/README.md

@@ -0,0 +1,193 @@
+# @aria-framework/ai
+
+A model seam shared by apps: one client (`createAiClient`) over several providers, plus the
+writing engines (Polish, Generate), a fact-preservation guard, an untrusted-text fence, and
+the stores and views behind an AI admin page. Prompts, routing policy and credentials stay in
+the app that uses the package.
+
+| Provider | `provider` value | Address |
+|---|---|---|
+| LM Studio | `lmstudio` | `baseUrl` (default `http://localhost:1234/v1`) |
+| Any OpenAI-compatible server | `openai-compatible` | `baseUrl` |
+| Anthropic | `anthropic` | `https://api.anthropic.com/v1` |
+| **lmx supervised stack** | `lmx` | **discovered at run time**, never configured |
+
+```bash
+npm install @aria-framework/ai undici     # undici only if you use lmx with a pinned certificate
+```
+
+## The client
+
+```js
+const { createAiClient } = require('@aria-framework/ai');
+
+const ai = createAiClient({
+  // Called on every request, so a settings change needs no restart.
+  resolveConfig: async () => ({
+    enabled: true, provider: 'openai-compatible',
+    baseUrl: 'http://gpu-box:8080/v1', model: 'qwen3', apiKey: '...',
+    timeoutMs: 60000, maxTokens: 1024, contextTokens: 8192
+  }),
+  budget: { async assertWithinBudget(cfg, meta) {}, async record(cfg, result, meta) {} }, // optional
+  logger: console,                                                                       // optional
+  maxRetryAfterMs: 10000   // optional: the longest Retry-After a call will wait out (see 429 below)
+});
+
+const r = await ai.complete({ system, messages, maxTokens: 400, schema /* optional */ });
+// r.text, r.json (when schema), r.model, r.usage.total, r.ms
+```
+
+Every failure is thrown as an `AiError` with a `kind`: `disabled`, `unconfigured`, `unreachable`,
+`timeout`, `auth`, `rate_limit`, `bad_response` or `refused`. The `message` is written for
+an admin screen and never includes a URL or key.
+
+`providerStore`, `usageStore`, `speedStore` and `lmxStore` are optional db-worker-backed
+stores. Each exports a `schemaFor(dialect)`, so the app's migration can be checked against it.
+
+---
+
+## lmx
+
+lmx is a supervisor that runs llama.cpp engines and publishes a **status document** saying
+which engines exist, which model each one runs and what state it is in. The full contract is
+`CLIENT.md` in the lmx repo, and this adapter implements it. The rules you would otherwise have
+to write yourself:
+
+| Contract rule | What the adapter does |
+|---|---|
+| Poll `/status` about every 2 s | One poller per `(instance, statusUrl)`, shared by every engine on that stack, with `unref()` called on it |
+| Route only to `healthy`; `draining` gets nothing new | Selects **for** `healthy`, so a state lmx adds later can never receive work by accident |
+| 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) |
+| 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 | Waits `Retry-After` once (up to `maxRetryAfterMs`), then throws with `lmxSkip: 'lmx_throttled'` |
+| The document's `instance` must match | A document for another instance is refused, because engine names collide across stacks |
+
+### Ask the operator for
+
+- **Direct to lmx:** the status URL (`https://<host>:9443/status`), `lmx.crt`, `status.token`,
+  and an engine key (`lmx keygen --add`). **Never** take `admin.token`.
+- **Through the gateway:** the status URL `https://<host>/e/status`, the certificate if it is
+  self-signed, and **one** `infer`-scoped `lmxk_…` key. That one key is both the status token
+  and the engines key, so put the same value in both fields.
+
+The adapter takes the status URL exactly as given; it does not append `/status`.
+
+### Config shape
+
+`resolveConfig()` (or the `cfgOverride` you pass to `complete`) returns:
+
+```js
+{
+  enabled: true,
+  provider: 'lmx',
+  apiKey: '<engines key>',           // sent to the ENGINE as Bearer
+  timeoutMs: 60000, maxTokens: 1024,
+  logger,                            // optional, gets the "status unreachable" warnings
+  lmx: {
+    instance: 'site-a-dev',          // MUST equal the document's top-level `instance`
+    statusUrl: 'https://lmx-host:9443/status',   // or https://gateway/e/status
+    statusToken: '<status token>',   // the same lmxk_ key as apiKey through the gateway
+    ca: '-----BEGIN CERTIFICATE-----…',          // PEM to pin; null = system trust store
+    engine: 'advanced',              // engine name: always stored, used for display and logs
+    engineId: '7c9e6679-…',          // engine id when the stack publishes one; null before mint-ids
+    pollMs: 2000, staleMs: 180000    // optional
+  }
+}
+```
+
+`model` is not needed. The engine reports which model it runs, and anything you send is
+ignored.
+
+### What to store
+
+The operator assigns engines to jobs, and the supervisor never does. For each choice, store:
+
+- `instance`, which is the stack's own name, checked against the document.
+- `engine_id`, when present. It is the only field that survives a rename.
+- `engine` (the name), as the fallback before `mint-ids` and for display.
+
+Do **not** store the URL, port, model, or `label`. The label is for display only and should be
+re-read on every poll.
+
+`providerStore.schemaFor()` has `lmx_instance`, `lmx_engine` and `lmx_engine_id`.
+`lmxStore.schemaFor()` holds the supervisor row (`id` = instance, `status_url`, poll and stale
+intervals). Credentials belong in your own secret store; this package never sees one at rest.
+
+### Re-keying when ids appear or engines are renamed
+
+Call this after each status read, for example from the same refresh that updates labels:
+
+```js
+const { rekeyPlan } = require('@aria-framework/ai');
+for (const step of rekeyPlan(rows, doc.engines)) {
+  // { id: 'row-id', set: { lmx_engine_id: 'uuid' }, why: 'minted' }
+  // { id: 'row-id', set: { lmx_engine: 'new-name' }, why: 'renamed', from: 'old-name' }
+  await updateRow(step.id, step.set);   // and audit it
+}
+```
+
+`minted` means the *same* engine has gained an id, so its routes, health and history carry
+over to the id. A row whose id has disappeared is left alone, and the panel shows it as
+missing. It is never re-pointed at whichever engine now has its old name.
+
+To find a stored row's engine in a status document, use the same rule the router, the panel and
+the verifier use. Import it from the package root, not from `providers/lmxDiscovery`:
+
+```js
+const { findEngine } = require('@aria-framework/ai');
+const engine = findEngine(doc.engines, { id: row.lmx_engine_id || null, name: row.lmx_engine });
+```
+
+### Errors and routing
+
+When an lmx call cannot run, the thrown `AiError` carries `err.lmxSkip`. None of these mean the
+engine is broken, so **do not trip a circuit breaker on them**. Move to the next endpoint
+instead:
+
+| `lmxSkip` | Meaning |
+|---|---|
+| `lmx_not_healthy` | draining, restarting or starting; the supervisor is doing planned work |
+| `lmx_stale` | no fresh status document, so we cannot see the stack |
+| `lmx_unknown_engine` | the engine is not in the document (removed, or hidden from this gateway key) |
+| `lmx_throttled` | a `429` on the key; the one `Retry-After` wait has already been spent |
+
+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.
+
+### Embeddings
+
+Call `client.embed(cfg, texts, { signal })` and pass your own resolved embedding config; it never
+falls back to `resolveConfig()`. It applies the same retry as `complete()`: a `429` with
+`Retry-After` is waited out once, and a fast dropped connection is retried once. Calling the
+provider adapter's `embed()` directly skips both, and a throttled batch then fails outright.
+Embeddings are not metered against the token budget.
+
+On lmx, `embed()` puts the engine's `dimensions` on the config as `embeddingDimensions`. Record the width
+you built an index with and compare it on startup. A model swap changes the width, and an index
+built at the old width becomes quietly wrong rather than loudly broken.
+
+### Operator screens
+
+- `lmxVerify.verify({ instance, statusUrl, statusToken, caCert, enginesKey, engineId?, engineName? })`
+  runs the ordered checks (reachable → certificate → status token → engines key). The
+  engines-key check uses `/v1/models`, so it costs no tokens and works through the gateway.
+- `describeStack()` and `views/ai/lmx-stack.ejs` draw the stack panel (active, draining, missing
+  and available engines, and certificate expiry).
+- `listModelsResult(cfg)` returns the engines for the picker, with `id`, `label`, `role`, model
+  facts and the reasoning flag.
+
+### Untrusted content
+
+A ticket, an email or a log line is attacker-controlled text. Pass it through `untrusted.js`
+or `fenced.js`, which supply delimited, provenance-tagged data. Use a `schema` so decoding is
+constrained. Verify extracted entities against your own records, and keep a person in the loop
+for anything that changes state.
+
+### Conformance
+
+Run lmx's `examples/client-smoke.mjs` against the stack before blaming this package. Exit
+code 0 means the contract holds, so a failure is on this side.

package/index.js

@@ -50,6 +50,8 @@ const DEFAULTS = {
 
 const RETRY_AFTER_MS = 400;
 const RETRY_ONLY_IF_FAILED_WITHIN_MS = 5000;
+/** The longest Retry-After a call will sit out before giving up on this endpoint. */
+const MAX_RETRY_AFTER_MS = 10000;
 
 const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
 const NOOP_BUDGET = { async assertWithinBudget() {}, async record() {} };
@@ -65,11 +67,13 @@ function createAiClient(deps = {}) {
   }
   const log = deps.logger || NOOP_LOGGER;
   const meter = deps.budget || NOOP_BUDGET;
+  const maxRetryAfterMs = Number.isFinite(deps.maxRetryAfterMs) ? deps.maxRetryAfterMs : MAX_RETRY_AFTER_MS;
 
   /**
    * 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).
+   * dropped the connection while loading a model, or a rate limit that said how long to wait. A
+   * cancelled call, a timeout, an open-ended rate limit or a slow failure is never retried (see the
+   * guards below).
    */
   async function withOneRetry(run, opts = {}) {
     const startedAt = Date.now();
@@ -78,6 +82,17 @@ function createAiClient(deps = {}) {
     } catch (err) {
       if (opts.signal && opts.signal.aborted) throw err;
       if (!err || !err.retryable) throw err;
+      // A 429 THAT SAYS HOW LONG. The lmx gateway's per-key limits answer with Retry-After, and its
+      // contract is explicit: the limit is on the KEY, so wait and retry rather than blaming the
+      // engine. Bounded, because a request a person is waiting on cannot sit out a minute; past the
+      // cap it throws as before and the caller's routing decides.
+      if (err.kind === 'rate_limit' && Number.isFinite(err.retryAfterMs)
+          && err.retryAfterMs <= maxRetryAfterMs) {
+        log.warn(`AI: rate limited — waiting ${err.retryAfterMs}ms as asked, then trying once more`);
+        await new Promise((r) => setTimeout(r, err.retryAfterMs));
+        if (opts.signal && opts.signal.aborted) throw err;
+        return run();
+      }
       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
@@ -130,6 +145,32 @@ function createAiClient(deps = {}) {
     return result;
   }
 
+  /**
+   * Embed one or more strings, with the same retry policy as complete().
+   *
+   * THE RETRY IS THE POINT. complete() always went through withOneRetry; embeddings were called on
+   * the adapter directly, so a gateway 429 failed the whole batch even though Retry-After said how
+   * long to wait - the README promised otherwise, and lmx's CLIENT.md requires a wait-and-retry for
+   * every request through the gateway. Embeddings are idempotent, so a 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 = {}) {
+    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;
@@ -202,7 +243,7 @@ function createAiClient(deps = {}) {
   const boundGenerate = (opts) => generate(complete, opts);
 
   return {
-    complete, isEnabled, test, listModels, listModelsResult, withOneRetry,
+    complete, embed, isEnabled, test, listModels, listModelsResult, withOneRetry,
     benchmark: benchmarkEndpoint,
     polish: boundPolish, generate: boundGenerate,
     facts, AiError, PROVIDERS, DEFAULTS
@@ -245,6 +286,10 @@ module.exports = {
   // 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.

package/lmxStatus.js

@@ -32,6 +32,7 @@
 'use strict';
 
 const { reasoningFor } = require('./providers/lmx');
+const { findEngine } = require('./providers/lmxDiscovery');
 
 /** Inside this window a certificate is worth mentioning: an expired pin fails at the handshake. */
 const EXPIRY_WARN_DAYS = 30;
@@ -88,17 +89,22 @@ function describeStack(o = {}) {
   // NULL, NOT [] — "we never got a document" and "this stack has no engines" send an operator to
   // completely different places, and only the first one means "press Check".
   const reported = (o.report && o.report.engines) ? o.report.engines.map(describeEngine) : null;
-  const byName = new Map((reported || []).map((e) => [e.name, e]));
 
-  const added = rows.map((row) => ({
-    row,
-    engine: byName.get(row.lmx_engine) || null,
-    missing: !!reported && !byName.has(row.lmx_engine),
-    health: health[row.id] || null,
-    routes: routes[row.id] || []
-  }));
+  // THE SAME MATCH THE ROUTER MAKES — by id when the row has one, by name otherwise. A panel that
+  // matched on name alone would call a renamed engine "missing" while calls to it went on working.
+  const added = rows.map((row) => {
+    const engine = findEngine(reported, rowRef(row));
+    return {
+      row,
+      engine,
+      missing: !!reported && !engine,
+      health: health[row.id] || null,
+      routes: routes[row.id] || []
+    };
+  });
 
-  const available = (reported || []).filter((e) => !rows.some((r) => r.lmx_engine === e.name));
+  const adopted = new Set(added.map((a) => a.engine).filter(Boolean));
+  const available = (reported || []).filter((e) => !adopted.has(e));
 
   const activeCount = added
     .filter((a) => Number(a.row.enabled) && a.engine && a.engine.state === 'healthy').length;
@@ -122,4 +128,49 @@ function describeStack(o = {}) {
   };
 }
 
-module.exports = { describeStack, describeEngine, modelName, reasoningLabel, EXPIRY_WARN_DAYS };
+/** An endpoint row's reference to its engine, in the shape findEngine takes. */
+const rowRef = (row) => ({ id: row.lmx_engine_id || null, name: row.lmx_engine });
+
+/**
+ * What to write to the endpoint rows so they follow the stack — the RE-KEY CLIENT.md asks for.
+ *
+ * Two cases, and only two:
+ *
+ *   minted  — the row has no id, and the engine of the same name now carries one. This is
+ *             `lmx mint-ids` having run on the host. It is the SAME engine, and the row's state
+ *             (routes, health, history) must carry forward onto the id. Reading it as one engine
+ *             disappearing and another appearing is the natural mistake, and it loses all of that.
+ *   renamed — the row has an id, the engine with that id now has a different name. The row keeps
+ *             its id and takes the new name, so logs and admin URLs say what the stack says.
+ *
+ * Nothing else moves. A row whose id is no longer reported stays as it is (the panel calls it
+ * missing); it is NEVER re-pointed at whatever now carries its old name, because ids are add-only
+ * upstream and that is a different engine.
+ *
+ * Pure: returns a plan, writes nothing. The app owns its rows, its audit trail and its transaction.
+ *
+ * @param {Array} rows     endpoint rows: { id, lmx_engine, lmx_engine_id? }
+ * @param {Array|null} engines  engines from a status document; null when none arrived
+ * @returns {Array<{id, set, why, from?}>}
+ */
+function rekeyPlan(rows, engines) {
+  if (!Array.isArray(engines)) return [];
+  const plan = [];
+  for (const row of rows || []) {
+    if (!row) continue;
+    if (!row.lmx_engine_id) {
+      const e = findEngine(engines, { name: row.lmx_engine });
+      if (e && e.id) plan.push({ id: row.id, set: { lmx_engine_id: e.id }, why: 'minted' });
+      continue;
+    }
+    const e = findEngine(engines, { id: row.lmx_engine_id });
+    if (e && e.name && e.name !== row.lmx_engine) {
+      plan.push({ id: row.id, set: { lmx_engine: e.name }, why: 'renamed', from: row.lmx_engine });
+    }
+  }
+  return plan;
+}
+
+module.exports = {
+  describeStack, describeEngine, modelName, reasoningLabel, rekeyPlan, EXPIRY_WARN_DAYS
+};

package/lmxStore.js

@@ -146,10 +146,16 @@ function createLmxStore(opts = {}) {
       return { changes: r.changes };
     },
 
-    /** The endpoint rows served by this supervisor — the join that groups a stack on screen. */
+    /**
+     * The endpoint rows served by this supervisor — the join that groups a stack on screen.
+     *
+     * `*`, not a column list: `lmx_engine_id` (ai 0.23.0) must reach describeStack for a renamed
+     * engine to be matched, and naming it here would turn an app that has not yet migrated the
+     * column into an SQL error on every stack panel. The rows carry no credential to leak.
+     */
     async engines(id) {
       return driver.all(
-        `SELECT id, label, lmx_engine, enabled, sort_order FROM ${providers} `
+        `SELECT * FROM ${providers} `
         + 'WHERE lmx_instance = ? ORDER BY sort_order, id', [String(id)]);
     }
   };

package/lmxVerify.js

@@ -155,6 +155,7 @@ const skip = (key, text) => ({ key, status: 'skip', text });
  *   caCert       the certificate to pin, PEM
  *   enginesKey   bearer for inference — checked only when there is an engine to check it against
  *   engineName   an adopted engine to authenticate against; omitted, the first healthy one is used
+ *   engineId     its stable id, when the row has one — matched instead of the name (renames)
  *   fetchImpl    test seam; the pinned transport is used when absent
  */
 async function verify(o = {}) {
@@ -311,8 +312,9 @@ async function enginesKeyCheck(o, engines, timeoutMs) {
   if (!o.enginesKey) {
     return skip('engines_key', 'no engines key set — engines are being called unauthenticated');
   }
-  const wanted = o.engineName
-    ? engines.find((e) => e && e.name === o.engineName)
+  const { findEngine } = require('./providers/lmxDiscovery');
+  const wanted = (o.engineId || o.engineName)
+    ? findEngine(engines, { id: o.engineId || null, name: o.engineName })
     : engines.find((e) => e && e.state === 'healthy' && e.url);
   if (!wanted || !wanted.url) {
     return skip('engines_key',

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.22.0",
+  "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.24.0",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {
@@ -47,7 +47,8 @@
     }
   },
   "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",
+    "prepublishOnly": "node ../../test/packaging.js ai"
   },
   "devDependencies": {
     "undici": "^8.10.0",

package/providerStore.js

@@ -52,7 +52,11 @@ const FIELDS = [
   //
   // 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'
+  'lmx_instance', 'lmx_engine',
+  // THE ENGINE'S STABLE ID, when the stack publishes one (lmx `mint-ids`). Names can be renamed by
+  // the operator and have been; the id cannot. NULL on a stack that has not minted, where the name
+  // is all there is — see lmxStatus.rekeyPlan for how a row gains one without losing its state.
+  'lmx_engine_id'
 ];
 
 const NUMERIC = new Set(['context_tokens', 'max_tokens', 'timeout_ms', 'daily_token_cap', 'enabled',
@@ -193,6 +197,7 @@ function createProviderStore(opts = {}) {
         // three, having originally compared only the first two and missed exactly this.
         lmxInstance: row.lmx_instance || null,
         lmxEngine: row.lmx_engine || null,
+        lmxEngineId: row.lmx_engine_id || null,
         // Carried on the resolved config so a speed test can judge a result without a second read.
         // 0 means no expectation was recorded, which is different from "expected to be slow".
         minTokensPerSec: Number(row.min_tokens_per_sec) || 0
@@ -235,6 +240,8 @@ function schemaFor(dialect) {
   -- address is discovered from the supervisor on every call.
   lmx_instance      TEXT,
   lmx_engine        TEXT,
+  -- The engine's stable id (lmx mint-ids), matched before the name. NULL until the stack has one.
+  lmx_engine_id     TEXT,
   created_at        TEXT    NOT NULL DEFAULT (${t.now()})
 `;
 }

package/providers/lmxDiscovery.js

@@ -27,10 +27,13 @@
  *   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.
+ * IDENTITY IS (instance, id), FALLING BACK TO (instance, name). The `id` is the only engine field
+ * guaranteed to survive a rename, and this stack has already renamed engines in production
+ * (`triage`/`analysis` became `normal`/`advanced`). A deployment that has not run `lmx mint-ids`
+ * publishes no id, and there the name is all there is. Names also collide across deployments —
+ * `analysis` exists on every stack — so the document's own `instance` is checked on every poll:
+ * 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
@@ -150,23 +153,27 @@ function createLmxDiscovery(opts = {}) {
   }
 
   /**
-   * The engine record for `name`, whatever state it is in — for a health card, which needs to show
+   * The engine record for `ref`, whatever state it is in — for a health card, which needs to show
    * "draining" rather than "gone".
+   *
+   * `ref` is a name (string) or `{ id, name }`. WITH AN ID, ONLY THE ID MATCHES. Ids are add-only
+   * upstream, so an engine that carries our old name under a different id (or none) is a different
+   * engine, and falling back to the name would quietly send our work to it.
    */
-  const engine = (name) => engines().find((e) => e && e.name === name) || null;
+  const engine = (ref) => findEngine(engines(), ref);
 
   /**
-   * Where to send work for `name`, or null.
+   * Where to send work for `ref` (a name, or `{ id, 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) {
+  function resolve(ref) {
     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);
+    const e = engine(ref);
     if (!e) return { url: null, reason: 'unknown_engine' };
 
     // Select FOR healthy. `draining`, `restarting`, and any state invented after this was written
@@ -206,4 +213,18 @@ function createLmxDiscovery(opts = {}) {
   };
 }
 
-module.exports = { createLmxDiscovery, POLL_MS, STALE_MS, HEALTHY };
+/**
+ * Find the engine a stored reference means. Shared with lmxStatus so the panel and the router can
+ * never disagree about which engine a row is.
+ *
+ * @param {Array} list   engines from a status document
+ * @param {string|{id?: string|null, name?: string}} ref
+ */
+function findEngine(list, ref) {
+  const r = (ref && typeof ref === 'object') ? ref : { name: ref };
+  const all = Array.isArray(list) ? list : [];
+  if (r.id) return all.find((e) => e && e.id === r.id) || null;
+  return all.find((e) => e && e.name === r.name) || null;
+}
+
+module.exports = { createLmxDiscovery, findEngine, POLL_MS, STALE_MS, HEALTHY };

package/providers/openai-compatible.js

@@ -252,7 +252,12 @@ async function httpError(res, label, apiKey) {
     return new AiError('auth', `${label} rejected the API key.`, { status: res.status });
   }
   if (res.status === 429) {
-    return new AiError('rate_limit', `${label} is rate limiting this app.`, { status: res.status });
+    const err = new AiError('rate_limit', `${label} is rate limiting this app.`, { status: res.status });
+    // WHOLE SECONDS, as the lmx gateway sends it. An HTTP-date form, or anything unparseable, leaves
+    // it unset — and an unset wait is never retried, which is the safe direction to be wrong in.
+    const ra = res.headers && typeof res.headers.get === 'function' ? res.headers.get('retry-after') : null;
+    if (ra != null && /^\s*\d+\s*$/.test(String(ra))) err.retryAfterMs = Number(ra) * 1000;
+    return err;
   }
   if (res.status === 404) {
     // The single most common local mistake: a model name that is not the one loaded.

package/views/ai/lmx-stack.ejs

@@ -84,8 +84,9 @@
      <%# WHAT EDIT PREFILLS. The certificate IS carried, because it is public — it is not even
          encrypted at rest — and an operator opening Edit to a blank certificate box has no way to
          tell a stored one from none at all. The two tokens are carried only as LENGTHS, which is
-         the most that can be said about a write-only secret and, as it happens, exactly enough to
-         notice the same value pasted into both fields. %>
+         the most that can be said about a write-only secret, and enough for an operator to see
+         whether the two match: they SHOULD through the gateway (one lmxk_ key in both fields) and
+         should NOT direct to lmx (status.token and an engine key are different credentials). %>
      data-lmx-cert="<%= inst.caCert || '' %>"
      data-lmx-token-len="<%= (inst.creds && inst.creds.statusTokenLength) || '' %>"
      data-lmx-key-len="<%= (inst.creds && inst.creds.enginesKeyLength) || '' %>"
@@ -307,6 +308,7 @@
             <form method="POST" action="<%= _base %>/lmx/<%= inst.id %>/adopt">
               <input type="hidden" name="_csrf" value="<%= _csrf() %>">
               <input type="hidden" name="engine" value="<%= e.name %>">
+              <% if (e.id) { %><input type="hidden" name="engine_id" value="<%= e.id %>"><% } %>
               <input type="hidden" name="label" value="<%= e.label || e.name %>">
               <input type="hidden" name="role" value="<%= e.role || '' %>">
               <input type="hidden" name="max_input_tokens" value="<%= e.maxInputTokens || '' %>">
@@ -366,21 +368,25 @@
         </div>
 
         <%# THE LENGTHS ARE THE POINT. Both are write-only, so the only thing that can be said about
-            a stored secret is how long it is — and two fields offering to keep the same number of
-            characters is exactly how an engines key pasted into both of them became visible. %>
+            a stored secret is how long it is. Equal lengths are expected through the gateway, where
+            one lmxk_ key is both credentials; direct to lmx they are two different secrets, and
+            equal lengths there are worth a second look. The help text says which is which. %>
         <div class="col-md-6">
           <label class="form-label" for="lmx-token-<%= inst.id %>">Status token</label>
           <input id="lmx-token-<%= inst.id %>" type="password" class="form-control" name="status_token"
                  autocomplete="new-password"
                  placeholder="<%= (inst.creds && inst.creds.statusTokenLength) ? 'unchanged — ' + inst.creds.statusTokenLength + ' characters stored' : 'nothing stored — enter a value' %>">
-          <div class="form-text">Reads the status document. Never sent to an engine.</div>
+          <div class="form-text">Reads the status document; never sent to an engine. Direct to lmx: the
+            <code>status.token</code>. Through the gateway: your <code>lmxk_</code> key, the same value
+            as the engines key.</div>
         </div>
         <div class="col-md-6">
           <label class="form-label" for="lmx-key-<%= inst.id %>">Engines key</label>
           <input id="lmx-key-<%= inst.id %>" type="password" class="form-control" name="engines_key"
                  autocomplete="new-password"
                  placeholder="<%= (inst.creds && inst.creds.enginesKeyLength) ? 'unchanged — ' + inst.creds.enginesKeyLength + ' characters stored' : 'nothing stored — enter a value' %>">
-          <div class="form-text">Used by every engine here unless one overrides it.</div>
+          <div class="form-text">Used by every engine here unless one overrides it. Through the gateway:
+            the same <code>lmxk_</code> key as the status token.</div>
         </div>
 
         <div class="col-12">