@sixzjd/dsh-usage-dashboard 0.0.0-stage → 0.6.0

package/lib/catalog.js

@@ -0,0 +1,230 @@
+/**
+ * Model display-name resolution for routing aliases.
+ *
+ * Some providers expose models under opaque route keys instead of real model
+ * names. Qoder does this: the durable log records `{provider:"qoder",
+ * model:"qfmodel"}`, while the actual model behind that route is
+ * `Qwen3.8-Flash`. The route key is what the host writes into `request/header`
+ * and what the upstream expects back, so it cannot be replaced at the source
+ * without breaking the request — the real name only exists in the plugin's own
+ * discovery catalog.
+ *
+ * This module reads that catalog so the panel can label a call with the model
+ * it actually ran. It changes DISPLAY ONLY: grouping, totals and pricing keep
+ * using the route key, so relabelling can never move a request between rows or
+ * change what is counted.
+ *
+ * The catalog is another plugin's private cache file, not a published seam.
+ * Everything here is therefore written to fail closed: a missing file, an
+ * unexpected shape, an unreadable directory or an ambiguous mapping all resolve
+ * to "no alias", which leaves the original route key on screen rather than
+ * guessing.
+ */
+
+import { readFile, readdir } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+// Only files whose name ends in `-catalog.json` are considered. The same
+// directory holds `.qoder-probe.json` and `.qoder-host-heartbeat.json` (which
+// carries a pid), and both also start with `version: 1` — the name filter keeps
+// them out before the structural check even runs.
+const CATALOG_SUFFIX = '-catalog.json'
+
+// An alias worth showing must differ from the route key, and a display name
+// this long is not a model name — it guards against a catalog that has been
+// repurposed to carry prose.
+const MAX_ALIAS_LENGTH = 64
+const MAX_NAME_LENGTH = 120
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '' ? value.trim() : null
+}
+
+/**
+ * The DSH home, honouring the same override the harness itself documents
+ * (`$DSH_HOME`, then `~/.dsh`). A blank value counts as unset so it can never
+ * resolve the home to the current working directory.
+ */
+export function resolveDshHome(env = process.env) {
+  const configured = typeof env.DSH_HOME === 'string' ? env.DSH_HOME.trim() : ''
+  if (configured !== '') return configured
+  const home = typeof env.HOME === 'string' && env.HOME.trim() !== ''
+    ? env.HOME
+    : (homedir?.() ?? '')
+  if (home === '') return null
+  return join(home, '.dsh')
+}
+
+/** Every profile's Qoder catalog path, across all profiles under the home. */
+export async function findCatalogFiles(home) {
+  if (typeof home !== 'string' || home === '') return []
+  const profilesRoot = join(home, 'profiles')
+  let profiles
+  try {
+    profiles = await readdir(profilesRoot, { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const paths = []
+  for (const entry of profiles) {
+    if (!entry.isDirectory()) continue
+    // A leading dot marks plugin-owned state directories, which is exactly
+    // where the catalog lives; they are skipped by ordinary listing helpers.
+    const stateDir = join(profilesRoot, entry.name, '.dsh-qoder-connect', 'state')
+    let files
+    try {
+      files = await readdir(stateDir)
+    } catch {
+      continue
+    }
+    for (const file of files) {
+      if (file.endsWith(CATALOG_SUFFIX)) paths.push(join(stateDir, file))
+    }
+  }
+  return paths
+}
+
+/**
+ * Pull `id -> name` out of one catalog file's parsed contents.
+ *
+ * Shape: `{version: 1, entries: {"pat:<hash>": {models: [{id, name, ...}]}}}`.
+ * Entries are keyed per account and each holds a `pat:` identifier; only the
+ * model rows are read out, so no account material can reach a caller.
+ *
+ * Returns null when the file is not a catalog at all, which is how the
+ * structural check rejects unrelated JSON that happens to sit in the directory.
+ */
+export function parseCatalogFile(contents) {
+  if (!isRecord(contents) || contents.version !== 1) return null
+  if (!isRecord(contents.entries)) return null
+  const rows = []
+  let sawAnyEntry = false
+  for (const account of Object.values(contents.entries)) {
+    if (!isRecord(account)) continue
+    if (!Array.isArray(account.models)) continue
+    sawAnyEntry = true
+    const fetchedAt = Number.isFinite(account.fetchedAtMs) ? account.fetchedAtMs : 0
+    for (const model of account.models) {
+      if (!isRecord(model)) continue
+      const id = nonEmptyString(model.id)
+      const name = nonEmptyString(model.name)
+      if (id === null || name === null) continue
+      if (id.length > MAX_ALIAS_LENGTH || name.length > MAX_NAME_LENGTH) continue
+      rows.push({ id, name, fetchedAt })
+    }
+  }
+  // `entries` present but no usable model rows is not a catalog we understand.
+  return sawAnyEntry ? rows : null
+}
+
+/**
+ * Merge rows from every catalog into one lookup.
+ *
+ * The freshest fetch wins per id. Two ids that disagree on the same name with
+ * equal freshness is an ambiguous mapping, and an ambiguous mapping is dropped:
+ * showing the wrong real model is worse than showing the route key.
+ */
+export function buildAliasMap(catalogs) {
+  // id -> {name, fetchedAt}
+  const best = new Map()
+  const ambiguous = new Set()
+  for (const rows of catalogs) {
+    for (const row of rows) {
+      const current = best.get(row.id)
+      if (current === undefined) {
+        best.set(row.id, { name: row.name, fetchedAt: row.fetchedAt })
+        continue
+      }
+      if (current.name === row.name) {
+        if (row.fetchedAt > current.fetchedAt) current.fetchedAt = row.fetchedAt
+        continue
+      }
+      if (row.fetchedAt > current.fetchedAt) {
+        // A newer fetch replaced the label; the older one is simply stale.
+        best.set(row.id, { name: row.name, fetchedAt: row.fetchedAt })
+        ambiguous.delete(row.id)
+        continue
+      }
+      if (row.fetchedAt === current.fetchedAt) ambiguous.add(row.id)
+    }
+  }
+  const map = new Map()
+  for (const [id, entry] of best) {
+    if (ambiguous.has(id)) continue
+    // A name that adds no information is dropped. The comparison is
+    // case-insensitive on purpose: Qoder's `auto -> Auto` differs only in
+    // capitalisation, and relabelling `auto` as `Auto` is not a real model
+    // name - it just hides a key that was already readable.
+    if (entry.name.toLowerCase() === id.toLowerCase()) continue
+    map.set(id, entry.name)
+  }
+  return map
+}
+
+/**
+ * Read every catalog and return `routeKey -> displayName`.
+ *
+ * Never throws: an unreadable home yields an empty map, so a machine without
+ * the Qoder plugin behaves exactly like one with no aliases at all.
+ */
+export async function loadModelAliases(options = {}) {
+  const home = options.home ?? resolveDshHome(options.env ?? process.env)
+  const paths = options.paths ?? await findCatalogFiles(home)
+  const read = options.readFile ?? readFile
+  // Carry the path alongside the rows so `sources` needs no second read: a
+  // re-read would race with the owning plugin rewriting the file, and the
+  // answer would then disagree with the rows already in hand.
+  const catalogs = await Promise.all(paths.map(async (path) => {
+    try {
+      const text = await read(path, 'utf8')
+      const rows = parseCatalogFile(JSON.parse(text))
+      return rows === null ? null : { path, rows }
+    } catch {
+      // Absent, unparseable or an unexpected shape: this file contributes nothing.
+      return null
+    }
+  }))
+  const usable = catalogs.filter((entry) => entry !== null && entry.rows.length > 0)
+  return {
+    aliases: buildAliasMap(usable.map((entry) => entry.rows)),
+    // Which files actually contributed, so the panel can say where a name came
+    // from and a stale path stays discoverable in the UI.
+    sources: usable.map((entry) => entry.path),
+    filesFound: paths.length,
+  }
+}
+
+/** A resolver that returns the display name for a route key, or null. */
+export function createAliasResolver(initial) {
+  let aliases = initial instanceof Map ? initial : new Map()
+  return {
+    replace(next) {
+      aliases = next instanceof Map ? next : new Map()
+    },
+    size() {
+      return aliases.size
+    },
+    /**
+     * Resolve one model id by exact match, case-insensitively.
+     *
+     * Deliberately not matching the trailing segment of a namespaced id. The
+     * catalog carries no provider field, so `vendor/dmodel` matching the Qoder
+     * key `dmodel` would label another vendor's model with a Qoder name - a
+     * wrong label on screen, which is the one outcome this whole module exists
+     * to avoid. Qoder logs its route keys bare, so dropping the tail match
+     * costs no real resolution; verified against the live model rows.
+     */
+    resolve(modelId) {
+      if (typeof modelId !== 'string' || modelId === '') return null
+      const trimmed = modelId.trim()
+      const exact = aliases.get(trimmed)
+      if (exact !== undefined) return exact
+      return aliases.get(trimmed.toLowerCase()) ?? null
+    },
+  }
+}

package/lib/history.js

@@ -0,0 +1,150 @@
+/**
+ * Durable per-call usage history for dsh-usage-dashboard.
+ *
+ * Why this exists
+ * ---------------
+ * The panel's only data source is `sessionQuery`, which by construction only
+ * sees the logs that still exist on disk. That makes a DELETION look like a
+ * real drop in usage: the moment a conversation is deleted, every token it
+ * ever spent disappears from every total. On the machine that motivated this
+ * module, 362 deleted sessions were worth ~3.1B tokens against a 6.67B
+ * lifetime figure — the panel showed 3.5B and looked like it had lost half
+ * the history.
+ *
+ * The fix is to stop treating "the log still exists" as the definition of
+ * history. Every scan records what each call slot cost into a durable store;
+ * a later scan that no longer sees a session keeps paying its recorded rows
+ * forward. Deleting a conversation stops it from growing, never from counting.
+ *
+ * Two invariants make that safe:
+ *
+ *  - A retained row is keyed by `${sessionId}:${turn}:${step}` — the same slot
+ *    the fold uses — so rescanning a surviving session replaces rather than
+ *    duplicates it.
+ *  - A live log always wins. Retained rows load first and live log rows are
+ *    set afterwards, so a session that still exists is measured from its log
+ *    and never from a possibly stale copy of it.
+ *
+ * Rows are pruned by age, not by session count, so an idle month cannot push
+ * real history out of the store.
+ */
+
+const TABLE = 'usage_history'
+const VERSION = 1
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function safeInt(value) {
+  const n = Number(value)
+  if (!Number.isFinite(n) || n < 0) return 0
+  return Math.trunc(n)
+}
+
+function tokensOf(raw) {
+  return {
+    input: safeInt(raw?.input),
+    output: safeInt(raw?.output),
+    cacheRead: safeInt(raw?.cacheRead),
+    cacheWrite: safeInt(raw?.cacheWrite),
+  }
+}
+
+function isAllZero(tokens) {
+  return tokens.input === 0 && tokens.output === 0 && tokens.cacheRead === 0 && tokens.cacheWrite === 0
+}
+
+/** One retained row: the durable form of a single call slot. */
+function toRow(request) {
+  if (!isRecord(request)) return null
+  const id = typeof request.id === 'string' ? request.id : null
+  if (id === null || id === '') return null
+  const tokens = tokensOf(request.tokens)
+  if (isAllZero(tokens)) return null
+  return {
+    id,
+    sessionId: typeof request.sessionId === 'string' ? request.sessionId : id.split(':')[0],
+    time: Number.isFinite(request.time) ? Math.trunc(request.time) : null,
+    date: typeof request.date === 'string' ? request.date : null,
+    provider: typeof request.provider === 'string' ? request.provider : null,
+    modelId: typeof request.modelId === 'string' ? request.modelId : null,
+    tokens,
+  }
+}
+
+/**
+ * The in-memory index over retained rows.
+ *
+ * `absorb` takes a snapshot's request rows; `rows` returns what a fresh
+ * aggregator should reload through `loadRetained`. Persist `toJSON()` and hand
+ * it back to the constructor on the next start.
+ */
+export function createHistoryStore(initial = null) {
+  const rows = new Map()
+
+  if (isRecord(initial) && Array.isArray(initial.rows)) {
+    for (const raw of initial.rows) {
+      const row = toRow({ ...raw, id: raw?.id, sessionId: raw?.sessionId, date: raw?.date })
+      if (row !== null) rows.set(row.id, row)
+    }
+  }
+
+  /**
+   * Record every row of one snapshot.
+   *
+   * A row already present is REPLACED, which is what keeps a growing session
+   * from being counted twice: the latest scan of that slot is the truth.
+   */
+  function absorb(requests) {
+    if (!Array.isArray(requests)) return 0
+    let changed = 0
+    for (const request of requests) {
+      const row = toRow(request)
+      if (row === null) continue
+      const previous = rows.get(row.id)
+      if (previous !== undefined && sameRow(previous, row)) continue
+      rows.set(row.id, row)
+      changed += 1
+    }
+    return changed
+  }
+
+  function sameRow(a, b) {
+    return a.time === b.time && a.date === b.date && a.provider === b.provider
+      && a.modelId === b.modelId && a.tokens.input === b.tokens.input
+      && a.tokens.output === b.tokens.output && a.tokens.cacheRead === b.tokens.cacheRead
+      && a.tokens.cacheWrite === b.tokens.cacheWrite
+  }
+
+  /** Drop rows for sessions that no longer exist AND are older than a cut. */
+  function prune(keepSessionIds, beforeMs) {
+    const keep = keepSessionIds instanceof Set ? keepSessionIds : new Set(keepSessionIds ?? [])
+    let removed = 0
+    for (const [id, row] of rows) {
+      if (keep.has(row.sessionId)) continue
+      if (beforeMs !== null && row.time !== null && row.time >= beforeMs) continue
+      rows.delete(id)
+      removed += 1
+    }
+    return removed
+  }
+
+  function rows_() {
+    return [...rows.values()].map((row) => ({ ...row, tokens: { ...row.tokens } }))
+  }
+
+  function toJSON() {
+    return { version: VERSION, rows: rows_() }
+  }
+
+  function size() {
+    return rows.size
+  }
+
+  function sessionIds() {
+    return new Set([...rows.values()].map((row) => row.sessionId))
+  }
+
+  return { absorb, prune, rows: rows_, toJSON, size, sessionIds, table: TABLE }
+}

package/lib/index.js

@@ -0,0 +1,2 @@
+export { name, inject, apply } from './plugin.js'
+export { default } from './plugin.js'