@aria-framework/ai 0.12.0 → 0.13.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

@@ -207,6 +207,11 @@ module.exports = {
   // 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'),
   /**

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.0",
+  "version": "0.13.0",
   "license": "UNLICENSED",
   "private": false,
   "publishConfig": {

package/speedStore.js

@@ -33,6 +33,22 @@ function createSpeedStore(opts = {}) {
 
   const num = (v) => (v == null || v === '' || Number.isNaN(Number(v)) ? null : Number(v));
 
+  /**
+   * `YYYY-MM-DD HH:MM:SS` in UTC — what `datetime('now')` produces, and what every other timestamp
+   * column in a consuming app already holds.
+   *
+   * toISOString() was the obvious thing to write and the wrong thing to store. Apps parse these
+   * columns with `new Date(String(ts).replace(' ', 'T') + 'Z')`; given an ISO string there is no
+   * space to replace, so the 'Z' is appended to one already there and the result is Invalid Date —
+   * silently, because the helper checks isNaN and returns ''. Sorting is worse: 'T' (0x54) sorts
+   * after ' ' (0x20), so an ISO row and a datetime('now') row from the same second compare wrong.
+   */
+  const stamp = (d) => {
+    const p2 = (n) => String(n).padStart(2, '0');
+    return `${d.getUTCFullYear()}-${p2(d.getUTCMonth() + 1)}-${p2(d.getUTCDate())} `
+      + `${p2(d.getUTCHours())}:${p2(d.getUTCMinutes())}:${p2(d.getUTCSeconds())}`;
+  };
+
   return {
     table,
 
@@ -50,7 +66,7 @@ function createSpeedStore(opts = {}) {
          VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
         [
           String(entry.endpoint || ''),
-          (entry.at || now()).toISOString(),
+          stamp(entry.at || now()),
           num(entry.tokensPerSec),
           num(entry.coldMs),
           num(entry.runTokens),
@@ -80,15 +96,29 @@ function createSpeedStore(opts = {}) {
       const ids = (endpoints || []).map((e) => String(e)).filter(Boolean);
       if (!ids.length) return {};
       const capped = Math.max(1, Math.min(500, Number(limit) || DEFAULT_LIMIT));
-      const rows = await driver.all(
-        `SELECT * FROM ${table} WHERE endpoint IN (${ids.map(() => '?').join(', ')}) ORDER BY id DESC`,
-        ids
-      );
+      // LIMITED PER ENDPOINT, IN SQL. A single `WHERE endpoint IN (...) ORDER BY id DESC` reads
+      // every retained row for every endpoint and throws most of them away in JS — at the 200-row
+      // bound with eight endpoints that is 1600 rows, `error` text included, marshalled across the
+      // worker boundary to draw eight 88-pixel lines. It also cannot use the (endpoint, id DESC)
+      // index for a global ordering, so it sorts in a temp b-tree as well.
+      //
+      // UNION ALL of per-endpoint selects rather than a window function: it reads the same on both
+      // engines and needs no version floor.
+      // EACH BRANCH IN A SUBQUERY, and aliased. A bare `... ORDER BY id DESC LIMIT n UNION ALL ...`
+      // is a syntax error — the ORDER BY binds to the compound, not the branch — and Postgres
+      // additionally requires a name for a subquery in FROM. Both engines accept this form.
+      const sql = ids
+        .map((_, i) => `SELECT * FROM (SELECT * FROM ${table} WHERE endpoint = ? `
+          + `ORDER BY id DESC LIMIT ${capped}) AS s${i}`)
+        .join(' UNION ALL ');
+      const rows = await driver.all(sql, ids);
       const out = {};
       for (const row of rows) {
         const bucket = out[row.endpoint] || (out[row.endpoint] = { latest: null, points: [] });
-        if (!bucket.latest) bucket.latest = row;          // rows arrive newest first
-        if (bucket.points.length < capped) bucket.points.push(row);
+        // Newest first WITHIN each endpoint's block, which is all this needs — the blocks
+        // themselves may arrive in any order.
+        if (!bucket.latest) bucket.latest = row;
+        bucket.points.push(row);
       }
       // Reversed at the end so a caller draws left-to-right in time without thinking about it.
       for (const id of Object.keys(out)) out[id].points.reverse();
@@ -102,9 +132,15 @@ function createSpeedStore(opts = {}) {
      * history, and one checked hourly should not be able to bury it. Age-based pruning gets that
      * backwards for exactly the endpoints whose trend matters most.
      */
-    async prune({ keepPerEndpoint = 200 } = {}) {
+    async prune({ keepPerEndpoint = 200, endpoint = null } = {}) {
       const keep = Math.max(10, Math.min(5000, Number(keepPerEndpoint) || 200));
-      const ids = await driver.all(`SELECT DISTINCT endpoint FROM ${table}`, []);
+      // ONE ENDPOINT WHEN THE CALLER KNOWS WHICH. Pruning on write swept every endpoint in the
+      // table every time — 1 + 2N queries to delete at most one row belonging to one of them, since
+      // none of the others can have grown since their own last write. With eight endpoints that was
+      // seventeen worker round trips inside a request, for one deletion.
+      const ids = endpoint
+        ? [{ endpoint: String(endpoint) }]
+        : await driver.all(`SELECT DISTINCT endpoint FROM ${table}`, []);
       let removed = 0;
       for (const { endpoint } of ids) {
         const cutoff = await driver.get(

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>
         <% } %>