@goodandready/dsh-subscriptions 0.6.60 → 0.6.62

package/lib/history.js

@@ -1,3 +1,4 @@
+import { calculateAnalytics } from './analytics.js'
 import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { homedir } from 'node:os'
@@ -261,6 +262,22 @@ export class HistoryStore {
     }
 
     const first = this.rows[0] // newest first
+    const recentDecisions = []
+    for (const r of this.rows) {
+      if (r && r.decisionTrace) {
+        recentDecisions.push({
+          ts: r.ts,
+          provider: r.provider,
+          ref: r.ref,
+          model: r.model || null,
+          decisionReason: r.decisionTrace.finalOutcome || (r.decisionTrace.attempts && r.decisionTrace.attempts[0] && r.decisionTrace.attempts[0].decisionReason) || 'selected',
+          attemptsCount: Array.isArray(r.decisionTrace.attempts) ? r.decisionTrace.attempts.length : 1,
+          cascaded: r.decisionTrace.finalOutcome === 'cascade_fallback' || r.kind === 'cascade',
+        })
+        if (recentDecisions.length >= 10) break
+      }
+    }
+
     return {
       totalRequests: total,
       requests24h: count24h,
@@ -279,6 +296,11 @@ export class HistoryStore {
         ? Math.round((totalCacheReadTokens / totalPromptTokens) * 1000) / 10
         : 0,
       accounts: this.accountsTelemetry(),
+      recentDecisions,
     }
   }
+
+  getAnalytics(accounts = [], nowMs = Date.now()) {
+    return calculateAnalytics(this.rows, accounts, nowMs)
+  }
 }

package/lib/models-catalog.js

@@ -0,0 +1,240 @@
+import { PROVIDERS, displayName } from './refs.js'
+
+export function isDeprecatedId(id) {
+  return /(^|[-_:])(test|preview|dev|alpha|beta|snapshot|experimental|legacy|deprecated)([-_:]|$)/i.test(String(id || ''))
+}
+import { getVendor } from './vendors/index.js'
+import { getAccountRemainingPercent } from './rotate.js'
+
+export const CAPABILITY_TAGS = {
+  VISION: 'vision',
+  TOOLS: 'tools',
+  REASONING: 'reasoning',
+  CODING: 'coding',
+  FAST: 'fast',
+  MATH: 'math',
+}
+
+/**
+ * Infer context window and capability tags for a given provider and model.
+ * @param {string} provider
+ * @param {string} modelId
+ * @returns {{ contextWindow: number, contextLabel: string, capabilities: string[] }}
+ */
+export function inferModelCapabilities(provider, modelId) {
+  const id = String(modelId || '').toLowerCase()
+  const p = String(provider || '').toLowerCase()
+  const caps = new Set([CAPABILITY_TAGS.TOOLS])
+  let contextWindow = 128000
+  let contextLabel = '128k'
+
+  // Vision detection
+  if (
+    id.includes('vision') ||
+    id.includes('gpt-4o') ||
+    id.includes('gpt-5') ||
+    id.includes('gpt-6') ||
+    id.includes('claude') ||
+    id.includes('gemini') ||
+    id.includes('grok-2') ||
+    id.includes('grok-3')
+  ) {
+    caps.add(CAPABILITY_TAGS.VISION)
+  }
+
+  // Reasoning detection
+  if (
+    id.includes('thinking') ||
+    id.includes('reasoning') ||
+    id.includes('o1') ||
+    id.includes('o3') ||
+    id.includes('gpt-5') ||
+    id.includes('gpt-6') ||
+    id.includes('claude-opus') ||
+    id.includes('claude-sonnet-5') ||
+    id.includes('claude-fable') ||
+    id.includes('claude-3-7') ||
+    id.includes('k1.5') ||
+    id.includes('r1')
+  ) {
+    caps.add(CAPABILITY_TAGS.REASONING)
+  }
+
+  // Coding detection
+  if (
+    id.includes('codex') ||
+    id.includes('coder') ||
+    id.includes('coding') ||
+    id.includes('sonnet') ||
+    id.includes('gpt-5') ||
+    id.includes('gpt-6') ||
+    id.includes('sol') ||
+    id.includes('terra') ||
+    id.includes('luna') ||
+    p === 'codex' ||
+    p === 'copilot' ||
+    p === 'cursor'
+  ) {
+    caps.add(CAPABILITY_TAGS.CODING)
+  }
+
+  // Fast / Speed detection
+  if (id.includes('flash') || id.includes('mini') || id.includes('haiku') || id.includes('small') || id.includes('fast')) {
+    caps.add(CAPABILITY_TAGS.FAST)
+  }
+
+  // Context window mapping
+  if (p === 'antigravity' && (id.includes('gemini-2.5') || id.includes('gemini-3'))) {
+    contextWindow = id.includes('pro') ? 2000000 : 1000000
+    contextLabel = id.includes('pro') ? '2M' : '1M'
+  } else if (id.includes('grok-3') || id.includes('1m')) {
+    contextWindow = 1000000
+    contextLabel = '1M'
+  } else if (
+    id.includes('claude-') ||
+    id.includes('o1') ||
+    id.includes('o3') ||
+    id.includes('gpt-5') ||
+    id.includes('gpt-6') ||
+    id.includes('kimi') ||
+    id.includes('200k')
+  ) {
+    contextWindow = 200000
+    contextLabel = '200k'
+  }
+
+  return {
+    contextWindow,
+    contextLabel,
+    capabilities: Array.from(caps),
+  }
+}
+
+/**
+ * Calculates pool-wide status and quota for a provider from the account list.
+ * @param {string} provider
+ * @param {Array<object>} accounts
+ * @param {number} [nowMs]
+ * @returns {object}
+ */
+export function calculatePoolStatus(provider, accounts = [], nowMs = Date.now()) {
+  const p = String(provider || '').toLowerCase()
+  const matching = (accounts || []).filter((a) => a && String(a.provider).toLowerCase() === p)
+
+  if (!matching.length) {
+    return {
+      status: 'unconfigured',
+      totalAccounts: 0,
+      healthyAccounts: 0,
+      quarantinedAccounts: 0,
+      cooldownAccounts: 0,
+      remainingPercent: null,
+      resetAt: null,
+    }
+  }
+
+  let healthyCount = 0
+  let quarantinedCount = 0
+  let cooldownCount = 0
+  let maxRemainingPercent = null
+  let nearestResetAt = null
+
+  for (const acc of matching) {
+    const isQuarantined = Boolean(acc.quarantineUntil && Number(acc.quarantineUntil) > nowMs)
+    const isCooldown = Boolean(acc.cooldownUntil && Number(acc.cooldownUntil) > nowMs)
+    const rem = getAccountRemainingPercent(acc)
+    const isExhausted = (rem !== null && rem <= 0) || (acc.usagePercent != null && Number(acc.usagePercent) >= 100)
+    const hasToken = Boolean(acc.configured && acc.writable !== false)
+
+    if (isQuarantined) quarantinedCount++
+    if (isCooldown) cooldownCount++
+
+    if (hasToken && !isQuarantined && !isCooldown && !isExhausted) {
+      healthyCount++
+      if (rem !== null) {
+        maxRemainingPercent = maxRemainingPercent === null ? rem : Math.max(maxRemainingPercent, rem)
+      }
+    }
+
+    const resetAt = acc.quota?.resetAt ? Number(acc.quota.resetAt) : null
+    if (resetAt && resetAt > nowMs) {
+      if (!nearestResetAt || resetAt < nearestResetAt) {
+        nearestResetAt = resetAt
+      }
+    }
+  }
+
+  let status = 'available'
+  if (healthyCount === 0) {
+    if (quarantinedCount === matching.length) {
+      status = 'quarantined'
+    } else if (cooldownCount === matching.length) {
+      status = 'cooldown'
+    } else {
+      status = 'exhausted'
+    }
+  } else if (healthyCount < matching.length) {
+    status = 'degraded'
+  }
+
+  return {
+    status,
+    totalAccounts: matching.length,
+    healthyAccounts: healthyCount,
+    quarantinedAccounts: quarantinedCount,
+    cooldownAccounts: cooldownCount,
+    remainingPercent: maxRemainingPercent !== null ? Math.round(maxRemainingPercent) : null,
+    resetAt: nearestResetAt,
+  }
+}
+
+/**
+ * Builds the enriched model catalog across all supported subscription vendors.
+ * @param {object} options
+ * @param {Array<object>} options.accounts
+ * @param {object} [options.liveConfig]
+ * @param {boolean} [options.hideDeprecated]
+ * @param {number} [options.nowMs]
+ * @returns {Array<object>}
+ */
+export function buildEnrichedCatalog({
+  accounts = [],
+  liveConfig = {},
+  hideDeprecated = false,
+  nowMs = Date.now(),
+} = {}) {
+  const result = []
+
+  for (const provId of PROVIDERS) {
+    const vendor = getVendor(provId)
+    const pool = calculatePoolStatus(provId, accounts, nowMs)
+    const modelsKey = `${provId}Models`
+    let rawList = liveConfig && Array.isArray(liveConfig[modelsKey]) && liveConfig[modelsKey].length
+      ? liveConfig[modelsKey]
+      : (vendor.defaults ? vendor.defaults().models : [])
+
+    if (!Array.isArray(rawList)) rawList = []
+
+    for (const item of rawList) {
+      const modelId = typeof item === 'string' ? item : (item.id || item.slug || item.name)
+      if (!modelId) continue
+      if (hideDeprecated && isDeprecatedId(modelId)) continue
+
+      const modelName = (typeof item === 'object' && (item.name || item.display_name)) ? (item.name || item.display_name) : modelId
+      const caps = inferModelCapabilities(provId, modelId)
+
+      result.push({
+        id: modelId,
+        name: modelName,
+        provider: provId,
+        providerName: displayName(provId),
+        contextWindow: caps.contextWindow,
+        contextLabel: caps.contextLabel,
+        capabilities: caps.capabilities,
+        pool,
+      })
+    }
+  }
+
+  return result
+}

package/lib/rotate.js

@@ -63,7 +63,7 @@ export function getAccountRemainingPercent(acc) {
   return null
 }
 
-export function pickAccount(accounts, nowMs, opts) {
+export function pickAccountWithTrace(accounts, nowMs, opts) {
   const list = Array.isArray(accounts) ? accounts : []
   const now = Number(nowMs) || 0
   const thrRaw = opts && opts.switchAtRemaining != null ? Number(opts.switchAtRemaining) : 0
@@ -72,6 +72,8 @@ export function pickAccount(accounts, nowMs, opts) {
   const targetTag = opts && opts.tag
   const targetSession = opts && opts.sessionId
 
+  const evaluations = []
+
   function isQuotaExhausted(acc) {
     if (!thr || thr <= 0) return false
     const q = acc.quota
@@ -96,7 +98,7 @@ export function pickAccount(accounts, nowMs, opts) {
     return true
   }
 
-  // Sticky Session Pinning (#170)
+  // Sticky Session Pinning (#170, #517)
   if (targetSession) {
     const pinnedRef = getPinnedAccountRef(targetSession)
     if (pinnedRef) {
@@ -108,8 +110,42 @@ export function pickAccount(accounts, nowMs, opts) {
           (pinned.quota.remainingPercent != null && Number(pinned.quota.remainingPercent) <= 0)
         ) && (!pinned.quota.resetAt || Number(pinned.quota.resetAt) > now))
         if (!isCooldown && !isPinnedZero && !isQuotaExhausted(pinned) && !isUsageExhausted(pinned)) {
-          return pinned
+          evaluations.push({
+            ref: pinnedRef,
+            eligible: true,
+            tier: 0,
+            reason: 'session_pinned',
+            pinned: true,
+          })
+          return {
+            account: pinned,
+            trace: {
+              chosenRef: pinnedRef,
+              decisionReason: 'session_pinned',
+              tier: 0,
+              evaluations,
+              selectionMetrics: {
+                pinned: true,
+                remainingPercent: getAccountRemainingPercent(pinned),
+                healthScore: pinned.healthScore ?? 100,
+              },
+            },
+          }
+        } else {
+          evaluations.push({
+            ref: pinnedRef,
+            eligible: false,
+            reason: isCooldown ? 'pinned_cooldown' : isPinnedZero ? 'pinned_zero_quota' : 'pinned_exhausted',
+            pinned: true,
+          })
         }
+      } else if (pinned) {
+        evaluations.push({
+          ref: pinnedRef,
+          eligible: false,
+          reason: !pinned.hasToken ? 'pinned_no_token' : 'pinned_quarantine',
+          pinned: true,
+        })
       }
     }
   }
@@ -121,7 +157,12 @@ export function pickAccount(accounts, nowMs, opts) {
   const tiers = [[], [], []]
 
   for (const acc of list) {
-    if (!acc || !acc.hasToken) continue
+    if (!acc) continue
+    const ref = acc.ref || acc.id || 'unknown'
+    if (!acc.hasToken) {
+      evaluations.push({ ref, eligible: false, tier: null, reason: 'no_token' })
+      continue
+    }
 
     if (!opts || opts.autoPacing !== false) {
       if (acc.pacingRisk === undefined) {
@@ -143,34 +184,62 @@ export function pickAccount(accounts, nowMs, opts) {
     }
 
     // VIP Slot Reservation (#175)
-    if (acc.vipOnly && !isVipRequest) continue
+    if (acc.vipOnly && !isVipRequest) {
+      evaluations.push({ ref, eligible: false, tier: null, reason: 'vip_reserved' })
+      continue
+    }
 
     // Tag-based filtering (#173)
-    if (targetTag && Array.isArray(acc.tags) && !acc.tags.includes(targetTag)) continue
+    if (targetTag && Array.isArray(acc.tags) && !acc.tags.includes(targetTag)) {
+      evaluations.push({ ref, eligible: false, tier: null, reason: 'tag_mismatch' })
+      continue
+    }
 
     const isCooldown = acc.cooldownUntil && Number(acc.cooldownUntil) > now && cooldownBlocks(acc, opts && opts.family)
+    if (isCooldown) {
+      evaluations.push({ ref, eligible: false, tier: null, reason: 'cooldown', until: acc.cooldownUntil })
+      continue
+    }
+
     const inQuarantine = isQuarantined(acc, now)
+    if (inQuarantine) {
+      evaluations.push({ ref, eligible: false, tier: null, reason: 'quarantine', until: acc.quarantineUntil, quarantineReason: acc.quarantineReason })
+      continue
+    }
+
     const isHardExhausted = (acc.usagePercent != null && Number(acc.usagePercent) >= 100 && (!acc.quota || !acc.quota.resetAt || Number(acc.quota.resetAt) > now))
+    if (isHardExhausted) {
+      evaluations.push({ ref, eligible: false, tier: null, reason: 'hard_exhausted', usagePercent: acc.usagePercent })
+      continue
+    }
+
     const isZeroQuota = Boolean(acc.quota && (
       (acc.quota.remaining != null && Number(acc.quota.remaining) <= 0) ||
       (acc.quota.remainingPercent != null && Number(acc.quota.remainingPercent) <= 0)
     ) && (!acc.quota.resetAt || Number(acc.quota.resetAt) > now))
-
-    if (isCooldown || inQuarantine || isHardExhausted || isZeroQuota) {
+    if (isZeroQuota) {
+      evaluations.push({ ref, eligible: false, tier: null, reason: 'zero_quota' })
       continue
     }
 
     const softExhausted = isQuotaExhausted(acc) || isUsageExhausted(acc)
     if (softExhausted) {
       tiers[2].push(acc)
+      evaluations.push({ ref, eligible: true, tier: 2, reason: 'soft_exhausted', remainingPercent: getAccountRemainingPercent(acc) })
       continue
     }
 
-    if (!acc.quota) tiers[1].push(acc)
-    else tiers[0].push(acc)
+    if (!acc.quota) {
+      tiers[1].push(acc)
+      evaluations.push({ ref, eligible: true, tier: 1, reason: 'healthy_unknown_quota' })
+    } else {
+      tiers[0].push(acc)
+      evaluations.push({ ref, eligible: true, tier: 0, reason: 'healthy_known_quota', remainingPercent: getAccountRemainingPercent(acc) })
+    }
   }
 
-  for (const tier of tiers) {
+  for (let tierIdx = 0; tierIdx < tiers.length; tierIdx++) {
+    const tier = tiers[tierIdx]
     if (tier.length) {
       tier.sort((a, b) => {
         // #485: Smart Quota Drainer - prioritize higher burn urgency first
@@ -206,14 +275,46 @@ export function pickAccount(accounts, nowMs, opts) {
       })
 
       const chosen = tier[0]
+      const chosenRef = chosen.ref || chosen.id
       if (targetSession && chosen) {
-        pinSession(targetSession, chosen.ref || chosen.id)
+        pinSession(targetSession, chosenRef)
+      }
+      return {
+        account: chosen,
+        trace: {
+          chosenRef,
+          decisionReason: tierIdx === 0 ? 'healthy_tier0' : tierIdx === 1 ? 'healthy_tier1' : 'tier2_fallback',
+          tier: tierIdx,
+          evaluations,
+          selectionMetrics: {
+            tier: tierIdx,
+            burnUrgency: chosen.burnUrgency != null ? Number(chosen.burnUrgency) : null,
+            pacingRisk: chosen.pacingRisk != null ? Number(chosen.pacingRisk) : null,
+            remainingPercent: getAccountRemainingPercent(chosen),
+            resetAt: chosen.quota?.resetAt || null,
+            weight: chosen.weight || (chosen.isPro ? 5 : 1),
+            healthScore: chosen.healthScore ?? 100,
+          },
+        },
       }
-      return chosen
     }
   }
 
-  return null
+  return {
+    account: null,
+    trace: {
+      chosenRef: null,
+      decisionReason: 'no_usable_account',
+      tier: null,
+      evaluations,
+      selectionMetrics: null,
+    },
+  }
+}
+
+export function pickAccount(accounts, nowMs, opts) {
+  const res = pickAccountWithTrace(accounts, nowMs, opts)
+  return res ? res.account : null
 }
 
 export function markCooldown(account, nowMs, cooldownMs, family) {

package/lib/routes/status.js

@@ -1,3 +1,6 @@
+import { defaultConcurrencyQueue } from '../concurrency-queue.js'
+import { calculateAnalytics } from '../analytics.js'
+import { buildEnrichedCatalog } from '../models-catalog.js'
 // #374: Sensitive GET routes protected by same-origin check
 import { readFileSync } from 'node:fs'
 import { getRecentAlerts, clearAlerts } from '../alerts.js'
@@ -36,12 +39,19 @@ export function registerStatusRoutes(ctx, state) {
   }
 
   async function configResponse() {
+    const accts = await accountsView()
     return {
       ok: true,
       revision: getCurrentRevision(),
       config: publicConfig(live()),
-      accounts: await accountsView(),
+      accounts: accts,
       providers: PROVIDERS.map((id) => ({ id, name: displayName(id) })),
+      modelsCatalog: buildEnrichedCatalog({
+        accounts: accts,
+        liveConfig: live(),
+        hideDeprecated: !!live().hideDeprecatedModels,
+      }),
+      queue: defaultConcurrencyQueue.stats(),
     }
   }
 
@@ -239,6 +249,30 @@ export function registerStatusRoutes(ctx, state) {
   }), 'dsh-subscriptions: /status')
 
 
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/models',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'GET') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req, ctx)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      const accts = await accountsView()
+      writeJson(res, 200, {
+        ok: true,
+        models: buildEnrichedCatalog({
+          accounts: accts,
+          liveConfig: live(),
+          hideDeprecated: !!live().hideDeprecatedModels,
+        }),
+      })
+    }),
+  }), 'dsh-subscriptions: /models')
+
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-subscriptions/diagnostics',
@@ -507,4 +541,43 @@ export function registerStatusRoutes(ctx, state) {
     }),
   }), 'dsh-subscriptions: /alerts')
 
+
+  // #511: Detailed cache and subscription analytics endpoint
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/analytics',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'GET') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req, ctx)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      const accounts = await accountsView()
+      const analytics = typeof history.getAnalytics === 'function'
+        ? history.getAnalytics(accounts)
+        : calculateAnalytics(history.all(), accounts)
+      writeJson(res, 200, { ok: true, analytics })
+    }),
+  }), 'dsh-subscriptions: /analytics')
+
+  // #518: Concurrency and request queue status
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-subscriptions/queue',
+    handler: safeJsonHandler(async (req, res) => {
+      if (req.method !== 'GET') {
+        writeJson(res, 405, { ok: false, error: { code: 'method', message: 'GET only' } })
+        return
+      }
+      if (!isTrustedSettingsRequest(req, ctx)) {
+        writeJson(res, 403, { ok: false, error: { code: 'forbidden', message: 'same-origin only' } })
+        return
+      }
+      const queueStats = defaultConcurrencyQueue.stats()
+      writeJson(res, 200, { ok: true, queue: queueStats })
+    }),
+  }), 'dsh-subscriptions: /queue')
 }

package/lib/session-pin.js

@@ -46,3 +46,7 @@ export function getPinnedAccountRef(sessionId) {
   }
   return entry.accountRef
 }
+
+export function clearSessionPins() {
+  sessionPins.clear()
+}