@aria-framework/ai 0.12.1 → 0.14.0

package/health.js

@@ -320,13 +320,69 @@ function createHealthChecker(opts = {}) {
       };
     },
 
-    /** All known state, for persisting across a restart if an app wants to. */
+    /** All known state in the shape a UI renders. For PERSISTENCE use exportState(). */
     snapshot() {
       const out = {};
       for (const id of state.keys()) out[id] = this.status(id);
       return out;
     },
 
+    /**
+     * The facts worth surviving a restart.
+     *
+     * NOT EVERYTHING IS. Health lives in memory, so every deploy wipes it and each card reads "no
+     * record" until something touches the endpoint — which is why this exists. But restoring the
+     * whole state would be worse than restoring none of it:
+     *
+     *   lastGoodAt, lastCheckedAt, lastMs, lastError, modelPresent — KEPT. Each is a record of
+     *     something that already happened, and the UI dates them ("last good 3h ago"). An operator
+     *     reading one is not misled about when it was true.
+     *
+     *   failures and downUntil — DROPPED. A cooldown is a decision about NOW, and a restart is very
+     *     often the fix: restoring a trip from before it would hold a repaired endpoint out of
+     *     rotation for a reason that no longer exists. A fresh process gives every endpoint one
+     *     honest attempt, which costs at most a single timeout to discover.
+     *
+     *   throughput samples — DROPPED. A rate is shown bare — "52 tok/s" — with nothing saying when
+     *     it was measured, so carrying one across a restart presents a stale figure as current.
+     *     Unlike "3h ago" it cannot date itself. It refills on the next real call.
+     */
+    exportState() {
+      const out = {};
+      for (const [id, e] of state) {
+        if (!e.lastCheckedAt && !e.lastGoodAt) continue;   // nothing worth writing down
+        out[id] = {
+          lastGoodAt: e.lastGoodAt,
+          lastCheckedAt: e.lastCheckedAt,
+          lastMs: e.lastMs,
+          lastError: e.lastError,
+          modelPresent: e.modelPresent
+        };
+      }
+      return out;
+    },
+
+    /**
+     * Seed from a previous process. Anything already known in THIS process wins.
+     *
+     * A live entry means something has happened since boot, and a fact measured a moment ago beats
+     * one restored from disk — importing over it would move "last good" backwards.
+     */
+    importState(saved) {
+      let seeded = 0;
+      for (const [id, v] of Object.entries(saved || {})) {
+        if (state.has(id) || !v) continue;
+        const e = entry(id);
+        e.lastGoodAt = v.lastGoodAt == null ? null : Number(v.lastGoodAt);
+        e.lastCheckedAt = v.lastCheckedAt == null ? null : Number(v.lastCheckedAt);
+        e.lastMs = v.lastMs == null ? null : Number(v.lastMs);
+        e.lastError = v.lastError == null ? null : String(v.lastError);
+        e.modelPresent = v.modelPresent == null ? null : !!v.modelPresent;
+        seeded += 1;
+      }
+      return seeded;
+    },
+
     /** Forget everything — used by tests and by "recheck now" in a UI. */
     reset(id) {
       if (id) state.delete(id); else state.clear();

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.12.1",
+  "version": "0.14.0",
   "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',

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 })
     });

package/usageStore.js

@@ -71,12 +71,22 @@ function createUsageStore(opts = {}) {
   const rollupTable = opts.rollupTable || 'ai_usage_daily';
   const scopeCol = opts.scopeColumn || null;
   const routeCol = opts.routeColumn || null;
+  /**
+   * WHICH ENDPOINT, as opposed to which KIND.
+   *
+   * `provider` has always held the adapter kind — 'lmstudio', 'openai-compatible' — which was
+   * sufficient while one provider was configured and became wrong the moment a registry could hold
+   * several. Two endpoints of the same kind share a `provider` value, so per-endpoint totals were
+   * unobtainable and a consuming screen keying on the endpoint id found nothing at all.
+   */
+  const endpointCol = opts.endpointColumn || null;
   const now = typeof opts.now === 'function' ? opts.now : () => new Date();
 
   /** Column list and placeholders, built once from what the app actually has. */
   const cols = ['day', 'provider', 'model', 'calls', 'prompt_tokens', 'completion_tokens', 'total_tokens'];
   if (scopeCol) cols.splice(3, 0, scopeCol);
   if (routeCol) cols.splice(3, 0, routeCol);
+  if (endpointCol) cols.splice(3, 0, endpointCol);
 
   return {
     table,
@@ -95,6 +105,9 @@ function createUsageStore(opts = {}) {
       const total = Number(entry.totalTokens) || (prompt + completion);
 
       const values = [dayOf(now()), String(entry.provider || ''), String(entry.model || '')];
+      // ORDER MATCHES THE SPLICES ABOVE, last spliced first: each splice at index 3 pushes the
+      // previous one right, so the column list reads endpoint, route, scope.
+      if (endpointCol) values.push(entry.endpoint == null ? null : String(entry.endpoint));
       if (routeCol) values.push(entry.route == null ? null : String(entry.route));
       if (scopeCol) values.push(entry.scope == null ? null : entry.scope);
       values.push(1, prompt, completion, total);
@@ -130,7 +143,9 @@ function createUsageStore(opts = {}) {
     /** For the admin screen: recent days, newest first. */
     async byDay(days = 14) {
       const limit = Math.min(200, Math.max(1, Number(days) * 4));
-      const group = ['day', 'provider', 'model'].concat(routeCol ? [routeCol] : []);
+      const group = ['day', 'provider', 'model']
+        .concat(endpointCol ? [endpointCol] : [])
+        .concat(routeCol ? [routeCol] : []);
       return driver.all(
         `SELECT ${group.join(', ')},
                 SUM(calls) calls, SUM(prompt_tokens) prompt_tokens,
@@ -141,6 +156,59 @@ function createUsageStore(opts = {}) {
           LIMIT ?`, [limit]);
     },
 
+    /**
+     * Totals per ENDPOINT over a window.
+     *
+     * The question a registry screen asks — "what has this machine cost" — which `byProvider` could
+     * never answer, since it groups by adapter kind and two endpoints of one kind collapse together.
+     * Returns nothing useful unless an endpointColumn is configured, and says so rather than
+     * silently grouping by something else.
+     */
+    async byEndpoint(sinceDay) {
+      if (!endpointCol) throw new Error('createUsageStore: no endpointColumn was configured');
+      return driver.all(
+        `SELECT ${endpointCol} AS endpoint, SUM(calls) calls, SUM(prompt_tokens) prompt_tokens,
+                SUM(completion_tokens) completion_tokens, SUM(total_tokens) total_tokens
+           FROM ${table}
+          WHERE day >= ?
+          GROUP BY ${endpointCol}
+          ORDER BY total_tokens DESC`, [String(sinceDay)]);
+    },
+
+    /**
+     * Totals per ROUTE over a window.
+     *
+     * The actionable half of a spend report: a job can be pointed at a cheaper machine, run less
+     * often or switched off, while a machine is only ever the thing that happened to answer. Rows
+     * with no route come back under a NULL key — real spend that no job asked for, which must be
+     * shown rather than folded into a job that did not incur it.
+     */
+    async byRoute(sinceDay) {
+      if (!routeCol) throw new Error('createUsageStore: no routeColumn was configured');
+      return driver.all(
+        `SELECT ${routeCol} AS route, SUM(calls) calls, SUM(prompt_tokens) prompt_tokens,
+                SUM(completion_tokens) completion_tokens, SUM(total_tokens) total_tokens
+           FROM ${table}
+          WHERE day >= ?
+          GROUP BY ${routeCol}
+          ORDER BY total_tokens DESC`, [String(sinceDay)]);
+    },
+
+    /**
+     * Tokens spent today by ONE endpoint.
+     *
+     * WHAT A PER-ENDPOINT CEILING HAS TO COUNT. `tokensToday()` sums every endpoint, so comparing it
+     * against one endpoint's cap makes every cap a global one: two machines capped at 10k each stop
+     * at 10k between them rather than 10k apiece, which is not what a per-endpoint field says.
+     */
+    async tokensTodayFor(endpoint) {
+      if (!endpointCol) return this.tokensToday();
+      const r = await driver.get(
+        `SELECT COALESCE(SUM(total_tokens), 0) n FROM ${table} WHERE day = ? AND ${endpointCol} = ?`,
+        [dayOf(now()), String(endpoint)]);
+      return Number(r.n) || 0;
+    },
+
     /** Totals per provider over a window, for the usage screen's per-provider table. */
     async byProvider(sinceDay) {
       return driver.all(
@@ -243,12 +311,13 @@ function schemaFor(dialect, o = {}) {
     now: () => "datetime('now')"
   };
   const route = o.routeColumn ? `\n  ${o.routeColumn}${' '.repeat(Math.max(1, 14 - o.routeColumn.length))}TEXT,` : '';
+  const endpoint = o.endpointColumn ? `\n  ${o.endpointColumn}${' '.repeat(Math.max(1, 14 - o.endpointColumn.length))}TEXT,` : '';
   return {
     detail: `
   id                ${t.autoIncrementPk()},
   day               TEXT    NOT NULL,
   provider          TEXT    NOT NULL,
-  model             TEXT    NOT NULL,${route}
+  model             TEXT    NOT NULL,${endpoint}${route}
   calls             INTEGER NOT NULL DEFAULT 1,
   prompt_tokens     INTEGER NOT NULL DEFAULT 0,
   completion_tokens INTEGER NOT NULL DEFAULT 0,
@@ -260,7 +329,7 @@ function schemaFor(dialect, o = {}) {
     rollup: `
   day               TEXT    NOT NULL,
   provider          TEXT    NOT NULL,
-  model             TEXT    NOT NULL,${route}
+  model             TEXT    NOT NULL,${endpoint}${route}
   calls             INTEGER NOT NULL DEFAULT 0,
   prompt_tokens     INTEGER NOT NULL DEFAULT 0,
   completion_tokens INTEGER NOT NULL DEFAULT 0,

package/views/ai/provider-card.ejs

@@ -151,8 +151,9 @@
         <% } else if (sp && sp.latest && sp.latest.tokens_per_sec != null) { %>
           <div>
             <div class="text-body-secondary text-uppercase" style="font-size:.68rem;letter-spacing:.06em">Speed</div>
-            <%# ONE MEASUREMENT IS NOT A TREND, so it is shown as a number and no line. Two points
-                drawn as a chart invite reading a slope into a single pair of readings. %>
+            <%# ONE MEASUREMENT IS NOT A TREND, so it is shown as a number and no line. Two ARE a
+                trend — the smallest one there is, and "it moved from 51.5 to 51.9" is worth seeing —
+                so the line starts at two, which is what the guard above says. %>
             <span class="font-monospace" style="font-variant-numeric: tabular-nums"><%= sp.latest.tokens_per_sec %> tok/s</span>
           </div>
         <% } %>