@goodandready/dsh-subscriptions 0.6.60 → 0.6.62

package/README.md

@@ -98,6 +98,8 @@ graph LR
 * **Automatic 429 Failover**: When an account encounters a rate limit (`HTTP 429`, `RATE_LIMIT`, `QUOTA_EXCEEDED`), traffic instantly fails over to the next healthy account in the pool.
 * **Preemptive Quota Switching (`switchAtRemaining`)**: Automatically rotates to the next account before hitting zero if the rate-limit window reset is imminent.
 * **Dynamic Cooldown Calculation**: Parses upstream headers (`Retry-After`, `x-ratelimit-reset`, ISO dates, epoch timestamps) and auto-restores cooled-down accounts when their window resets.
+* **Synchronous Decision Tracing & Routing Explanation (#517)**: Real-time decision traces capture every account selection, rotation step, failure reason, and cascade fallback without post-hoc reconstruction, exposed in WebUI telemetry and diagnostics.
+* **Dynamic Model Catalog & Live Quota Visualizer (#507)**: Dynamic model catalog with pool-level health calculation (individual quarantine degrades rather than disables the pool), context window badges, capability tags (`vision`, `tools`, `reasoning`, `coding`, `fast`), and live reset countdowns.
 
 ---
 
@@ -242,6 +244,10 @@ dsh-subscriptions:
   codexFastMode: false      # v0.4.17: service_tier priority (1.5x speed tier)
   composerQuota: 'off'      # v0.4.18: composer indicator: off | percent | bar | forecast
   enableToasts: true        # v0.6.59: real-time in-app toast alerts on quarantine and quota events
+  enableQueue: true         # v0.6.62: bounded concurrency queue to prevent bursts of 429 errors
+  accountMaxConcurrency: 2  # v0.6.62: max concurrent active streams per account
+  maxQueueSize: 20          # v0.6.62: max queue depth before load shedding / reject
+  queueTimeoutMs: 30000     # v0.6.62: max queue wait duration in ms before timeout
   # Per-slot fields (v0.4.9): expiresAt (ms epoch), proxyUrl (http/https/socks5://)
   accounts:
     codex:

package/README.ru.md

@@ -98,6 +98,8 @@ graph LR
 * **Автоматическое переключение при 429**: при превышении лимита запросов трафик мгновенно переключается на следующий свободный аккаунт.
 * **Упреждающее переключение квот (`switchAtRemaining`)**: смена аккаунта до падения в ошибку, если окно сброса близко.
 * **Динамический расчёт Cooldown**: парсинг заголовков `Retry-After`, `x-ratelimit-reset`, дат ISO и миллисекундных меток с автоматическим возвратом остывших аккаунтов в строй.
+* **Трассировка решений ротации и объяснение маршрутизации (#517)**: Синхронная фиксация причин выбора аккаунтов, отказов и каскадных переходов в реальном времени с кодами причин без ретроспективной реконструкции; визуализация в телеметрии настроек и диагностике.
+* **Динамический каталог моделей с пуловой доступностью и квотами (#507)**: Обогащенная витрина моделей с расчетом здоровья пула (карантин одного аккаунта не блокирует модель при наличии живых), тегами возможностей (`vision`, `tools`, `reasoning`, `coding`, `fast`), размером контекста и таймером сброса квот.
 
 ---
 
@@ -215,6 +217,10 @@ dsh-subscriptions:
   codexFastMode: false      # v0.4.17: service_tier priority (скоростной тир 1.5x)
   composerQuota: 'off'      # v0.4.18: индикатор в строке ввода: off | percent | bar | forecast
   enableToasts: true        # v0.6.59: всплывающие уведомления при событиях карантина и квот
+  enableQueue: true         # v0.6.62: ограниченная очередь параллельных запросов к аккаунту
+  accountMaxConcurrency: 2  # v0.6.62: макс. число параллельных стримов на аккаунт
+  maxQueueSize: 20          # v0.6.62: макс. глубина очереди до сброса нагрузки
+  queueTimeoutMs: 30000     # v0.6.62: таймаут ожидания слота в очереди в мс
   # Поля слота (v0.4.9): expiresAt (ms), proxyUrl (http/https/socks5://)
   accounts:
     codex:

package/README.zh.md

@@ -91,6 +91,8 @@ graph LR
 ### 多账号轮换与限流保护
 * 每个供应商可挂多个账号（如 `CODEX_OAUTH_1`、`CODEX_OAUTH_2`）。
 * 遇到 429/配额耗尽自动切换到下一个健康账号；支持按剩余量提前切换和动态冷却恢复。
+* **轮换决策追踪与路由解释 (#517)**：实时同步记录账号选择、轮换切换、失败原因与级联回退的完整决策链路（无需事后推导），并在 WebUI 遥测与诊断报告中可视化展示。
+* **动态模型目录与配额可用性 (#507)**：基于账号池计算模型综合可用性（单个账号隔离不影响具备可用账号的模型），展示上下文窗口、能力标签（视觉、工具、推理、编码、快速）及动态配额倒计时。
 
 ### 安全与无头登录
 * OAuth 令牌绝不通过 HTTP API 返回，也不在 Web 界面渲染；仅存放于宿主加密凭据存储。
@@ -124,6 +126,10 @@ graph LR
 * **手动隔离管理（暂停与预热探测）**：支持在设置面板的账户卡片中一键暂停隔离活跃账户（`POST /dsh-subscriptions/quarantine/park`），或立即触发真实上游预热微探测（`probeWarmup`）并在验证成功后即时解除隔离（`POST /dsh-subscriptions/quarantine/probe`）。
 * **动态额度重置倒计时**：在顶部会话栏 `SubsPill` 和账户卡片中秒级动态更新，精准展示滚动配额窗口（`five_hour`、`seven_day`、`primary_window`）的剩余解锁时间。
 * **应用内即时弹窗提醒（Toast）**：当账户进入隔离、健康恢复解除隔离或额度达到预警线时，在聊天界面弹出轻量级浮动提醒。通过 `enableToasts: true` 控制。
+  enableQueue: true         # v0.6.62: 账户并发请求排队与限流
+  accountMaxConcurrency: 2  # v0.6.62: 单账户最大并行活跃流
+  maxQueueSize: 20          # v0.6.62: 队列最大等待深度
+  queueTimeoutMs: 30000     # v0.6.62: 队列最大等待超时时间（毫秒）
 * **自动化 Webhook 告警集成**：通过 `notifyQuarantineEntered` 与 `notifyQuarantineReleased` 自动向外部通知系统派发隔离生命周期事件。
 
 ### Antigravity 客户端密钥架构与无感 CLI 令牌刷新 (v0.6.60)

package/lib/adapter-manager.js

@@ -92,6 +92,20 @@ export function createAdapterManager({
         method: 'POST',
         status: 200,
         kind: 'cascade',
+        decisionTrace: {
+          attempts: [
+            {
+              attempt: 1,
+              kind: 'cascade_fallback',
+              fromProvider: provider,
+              toProvider: nextVendor,
+              model: targetModel,
+              reason: 'primary_pool_exhausted',
+            },
+          ],
+          finalOutcome: 'cascade_fallback',
+          chosenRef: String(nextVendor).toUpperCase() + '_CASCADE_FALLBACK',
+        },
       })
     } catch { /* ignore cascade history recording error */ }
   }

package/lib/adapter.js

@@ -1,3 +1,4 @@
+import { inferModelCapabilities, isDeprecatedId } from './models-catalog.js'
 import { fetchWithTimeout } from "./http.js"
 import { LlmAdapter, LlmError, attributionHeaders } from '@deepseek-ai/dsh-llm'
 import { displayName } from './refs.js'
@@ -10,10 +11,7 @@ import { quotaSnapshot, parseBody } from './ratelimit.js'
 import { toTokenUsage } from './wire.js'
 import { isSwitchableError } from './rotate.js'
 
-// #94: heuristic for test/preview/beta/legacy model ids.
-function isDeprecatedId(id) {
-  return /(^|[-_:])(test|preview|dev|alpha|beta|snapshot|experimental|legacy|deprecated)([-_:]|$)/i.test(id)
-}
+// #94: isDeprecatedId imported from ./models-catalog.js
 
 function asLlmError(err) {
   if (err instanceof LlmError) return err
@@ -74,8 +72,19 @@ export class SubscriptionAdapter extends LlmAdapter {
     if (typeof this.deps.hideDeprecatedModels === 'function' && this.deps.hideDeprecatedModels()) {
       models = models.filter((m) => !isDeprecatedId(String((m && m.id) || '')))
     }
-    // Defensive: ensure every model has the provider field set
-    models = models.map((m) => (m ? { ...m, provider: (!m.provider || m.provider === "custom") ? provider : m.provider } : m))
+    // Enrich models with provider and confirmed capability tags (#507)
+    models = models.map((m) => {
+      if (!m) return m
+      const prov = (!m.provider || m.provider === "custom") ? provider : m.provider
+      const caps = inferModelCapabilities(prov, m.id)
+      return {
+        ...m,
+        provider: prov,
+        contextWindow: m.contextWindow || caps.contextWindow,
+        contextLabel: caps.contextLabel,
+        capabilities: Array.isArray(m.capabilities) && m.capabilities.length ? m.capabilities : caps.capabilities,
+      }
+    })
     return models
   }
 
@@ -127,8 +136,10 @@ export class SubscriptionAdapter extends LlmAdapter {
       const effectiveDrainSafetyPercent = options.drainSafetyPercent !== undefined
         ? options.drainSafetyPercent
         : (typeof deps.drainSafetyPercent === 'function' ? deps.drainSafetyPercent() : (deps.drainSafetyPercent ?? 5))
+      const decisionTrace = {}
       const streamOptions = {
         ...options,
+        _decisionTrace: decisionTrace,
         autoPacing: effectiveAutoPacing,
         drainBeforeReset: effectiveDrainBeforeReset,
         drainSafetyPercent: effectiveDrainSafetyPercent,
@@ -218,6 +229,7 @@ export class SubscriptionAdapter extends LlmAdapter {
                   kind: 'stream',
                   ...(outcome === 'error' && errorCaught ? { error: errorCaught.message || String(errorCaught) } : {}),
                   ...(outcome === 'runaway' ? { reason: finishReason || (opts && opts._runawayState && opts._runawayState.reason) || 'runaway_loop_detected' } : {}),
+                  ...(decisionTrace && decisionTrace.attempts && decisionTrace.attempts.length ? { decisionTrace } : {}),
                 })
               } catch { /* ignore quota capture failure */ }
             }

package/lib/analytics.js

@@ -0,0 +1,338 @@
+// Subscription and cache analytics, performance aggregates, and quota forecasting.
+// Enforces 0 Cyrillic characters.
+
+export function calculatePercentile(values, percentile) {
+  if (!Array.isArray(values) || values.length === 0) return null
+  const sorted = [...values].sort((a, b) => a - b)
+  const index = Math.min(
+    sorted.length - 1,
+    Math.max(0, Math.ceil((percentile / 100) * sorted.length) - 1)
+  )
+  return sorted[index]
+}
+
+export function calculateCacheMetrics(entries = []) {
+  let promptTokens = 0
+  let completionTokens = 0
+  let cacheReadTokens = 0
+  let cacheCreationTokens = 0
+  let requestsWithCacheRead = 0
+
+  for (const r of entries) {
+    if (!r) continue
+    const prompt = typeof r.inputTokens === 'number'
+      ? r.inputTokens
+      : (r.tokens && typeof r.tokens.prompt === 'number' ? r.tokens.prompt : 0)
+    const completion = typeof r.outputTokens === 'number'
+      ? r.outputTokens
+      : (r.tokens && typeof r.tokens.completion === 'number' ? r.tokens.completion : 0)
+    const read = typeof r.cacheReadTokens === 'number'
+      ? r.cacheReadTokens
+      : (r.tokens && typeof r.tokens.cacheRead === 'number' ? r.tokens.cacheRead : 0)
+    const creation = typeof r.cacheCreationTokens === 'number'
+      ? r.cacheCreationTokens
+      : (r.tokens && typeof r.tokens.cacheCreation === 'number' ? r.tokens.cacheCreation : 0)
+
+    promptTokens += prompt
+    completionTokens += completion
+    cacheReadTokens += read
+    cacheCreationTokens += creation
+    if (read > 0) requestsWithCacheRead++
+  }
+
+  const totalTokens = promptTokens + completionTokens
+  const cacheTotal = promptTokens + cacheReadTokens
+  const cacheHitRate = cacheTotal > 0
+    ? Math.round((cacheReadTokens / cacheTotal) * 1000) / 10
+    : 0
+
+  return {
+    promptTokens,
+    completionTokens,
+    totalTokens,
+    cacheReadTokens,
+    cacheCreationTokens,
+    cacheHitRate,
+    requestsWithCacheRead,
+    cacheHitCount: requestsWithCacheRead,
+  }
+}
+
+export function calculatePerformanceMetrics(entries = []) {
+  const ttftList = []
+  const tpsList = []
+  const latencyList = []
+
+  let ttftSum = 0
+  let tpsSum = 0
+  let latencySum = 0
+
+  for (const r of entries) {
+    if (!r) continue
+    if (typeof r.ttftMs === 'number' && r.ttftMs >= 0) {
+      ttftList.push(r.ttftMs)
+      ttftSum += r.ttftMs
+    }
+    if (typeof r.tps === 'number' && r.tps > 0) {
+      tpsList.push(r.tps)
+      tpsSum += r.tps
+    }
+    if (typeof r.ms === 'number' && r.ms > 0) {
+      latencyList.push(r.ms)
+      latencySum += r.ms
+    }
+  }
+
+  const count = entries.length
+  return {
+    ttft: {
+      count: ttftList.length,
+      avgMs: ttftList.length > 0 ? Math.round(ttftSum / ttftList.length) : null,
+      p95Ms: calculatePercentile(ttftList, 95),
+      minMs: ttftList.length > 0 ? Math.min(...ttftList) : null,
+      maxMs: ttftList.length > 0 ? Math.max(...ttftList) : null,
+    },
+    tps: {
+      count: tpsList.length,
+      avg: tpsList.length > 0 ? Math.round((tpsSum / tpsList.length) * 10) / 10 : null,
+      p95: calculatePercentile(tpsList, 95),
+      min: tpsList.length > 0 ? Math.min(...tpsList) : null,
+      max: tpsList.length > 0 ? Math.max(...tpsList) : null,
+    },
+    latency: {
+      count: latencyList.length,
+      avgMs: latencyList.length > 0 ? Math.round(latencySum / latencyList.length) : 0,
+      p95Ms: calculatePercentile(latencyList, 95),
+      minMs: latencyList.length > 0 ? Math.min(...latencyList) : 0,
+      maxMs: latencyList.length > 0 ? Math.max(...latencyList) : 0,
+      totalRequests: count,
+    },
+  }
+}
+
+export function calculateHourlyBuckets(entries = [], nowMs = Date.now()) {
+  const buckets = []
+  const ONE_HOUR = 3600000
+
+  for (let i = 23; i >= 0; i--) {
+    const end = nowMs - (i * ONE_HOUR)
+    const start = end - ONE_HOUR
+    const dateObj = new Date(start)
+    const hourNum = dateObj.getHours()
+    const hourStr = String(hourNum).padStart(2, '0') + ':00'
+
+    buckets.push({
+      hour: hourNum,
+      label: hourStr,
+      start,
+      end,
+      requests: 0,
+      successCount: 0,
+      errorCount: 0,
+      promptTokens: 0,
+      completionTokens: 0,
+      cacheReadTokens: 0,
+      totalTokens: 0,
+    })
+  }
+
+  const cutoff = nowMs - (24 * ONE_HOUR)
+  for (const r of entries) {
+    if (!r || !r.ts || r.ts < cutoff || r.ts > nowMs) continue
+    const age = nowMs - r.ts
+    const bucketIndex = 23 - Math.floor(age / ONE_HOUR)
+    if (bucketIndex >= 0 && bucketIndex < 24) {
+      const b = buckets[bucketIndex]
+      b.requests++
+      const st = Number(r.status || 0)
+      if (st >= 200 && st < 400) b.successCount++
+      else if (st >= 400) b.errorCount++
+
+      const prompt = Number(r.inputTokens || (r.tokens && r.tokens.prompt) || 0)
+      const completion = Number(r.outputTokens || (r.tokens && r.tokens.completion) || 0)
+      const cacheRead = Number(r.cacheReadTokens || (r.tokens && r.tokens.cacheRead) || 0)
+
+      b.promptTokens += prompt
+      b.completionTokens += completion
+      b.cacheReadTokens += cacheRead
+      b.totalTokens += (prompt + completion)
+    }
+  }
+
+  return buckets
+}
+
+export function calculateAccountBreakdown(entries = [], accounts = []) {
+  const map = {}
+  const labels = {}
+  for (const a of accounts) {
+    if (a && a.ref) {
+      labels[a.ref] = a.label || a.ref
+    }
+  }
+
+  for (const r of entries) {
+    if (!r || !r.ref) continue
+    const ref = r.ref
+    if (!map[ref]) {
+      map[ref] = {
+        ref,
+        provider: r.provider || 'unknown',
+        label: labels[ref] || r.accountLabel || ref,
+        totalRequests: 0,
+        successRequests: 0,
+        errorRequests: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        ttftSum: 0,
+        ttftCount: 0,
+        tpsSum: 0,
+        tpsCount: 0,
+        latencySum: 0,
+      }
+    }
+    const acc = map[ref]
+    acc.totalRequests++
+    const st = Number(r.status || 0)
+    if (st >= 200 && st < 400) acc.successRequests++
+    else if (st >= 400) acc.errorRequests++
+
+    const prompt = Number(r.inputTokens || (r.tokens && r.tokens.prompt) || 0)
+    const completion = Number(r.outputTokens || (r.tokens && r.tokens.completion) || 0)
+    const cacheRead = Number(r.cacheReadTokens || (r.tokens && r.tokens.cacheRead) || 0)
+    const cacheCreation = Number(r.cacheCreationTokens || (r.tokens && r.tokens.cacheCreation) || 0)
+
+    acc.promptTokens += prompt
+    acc.completionTokens += completion
+    acc.cacheReadTokens += cacheRead
+    acc.cacheCreationTokens += cacheCreation
+
+    if (typeof r.ttftMs === 'number' && r.ttftMs >= 0) {
+      acc.ttftSum += r.ttftMs
+      acc.ttftCount++
+    }
+    if (typeof r.tps === 'number' && r.tps > 0) {
+      acc.tpsSum += r.tps
+      acc.tpsCount++
+    }
+    if (typeof r.ms === 'number' && r.ms > 0) {
+      acc.latencySum += r.ms
+    }
+  }
+
+  const result = {}
+  for (const [ref, acc] of Object.entries(map)) {
+    const totalCache = acc.promptTokens + acc.cacheReadTokens
+    result[ref] = {
+      ref,
+      provider: acc.provider,
+      label: acc.label,
+      totalRequests: acc.totalRequests,
+      successRequests: acc.successRequests,
+      errorRequests: acc.errorRequests,
+      promptTokens: acc.promptTokens,
+      completionTokens: acc.completionTokens,
+      cacheReadTokens: acc.cacheReadTokens,
+      cacheCreationTokens: acc.cacheCreationTokens,
+      cacheHitRate: totalCache > 0 ? Math.round((acc.cacheReadTokens / totalCache) * 1000) / 10 : 0,
+      avgTtftMs: acc.ttftCount > 0 ? Math.round(acc.ttftSum / acc.ttftCount) : null,
+      avgTps: acc.tpsCount > 0 ? Math.round((acc.tpsSum / acc.tpsCount) * 10) / 10 : null,
+      avgLatencyMs: acc.totalRequests > 0 ? Math.round(acc.latencySum / acc.totalRequests) : 0,
+    }
+  }
+  return result
+}
+
+export function calculateQuotaForecast(accounts = [], entries = [], nowMs = Date.now()) {
+  const ONE_HOUR = 3600000
+  const ONE_DAY = 24 * ONE_HOUR
+  const forecast = []
+
+  for (const acc of accounts) {
+    if (!acc || !acc.ref) continue
+    const quota = acc.quota
+    const ref = acc.ref
+
+    // Calculate recent usage over the past 24 hours for this account
+    let tokens24h = 0
+    let requests24h = 0
+    let tokens1h = 0
+    let requests1h = 0
+
+    for (const r of entries) {
+      if (!r || r.ref !== ref || !r.ts) continue
+      const age = nowMs - r.ts
+      if (age <= ONE_DAY) {
+        const total = Number(r.inputTokens || (r.tokens && r.tokens.prompt) || 0) +
+                      Number(r.outputTokens || (r.tokens && r.tokens.completion) || 0)
+        tokens24h += total
+        requests24h++
+        if (age <= ONE_HOUR) {
+          tokens1h += total
+          requests1h++
+        }
+      }
+    }
+
+    const burnRateTokensPerHour = requests1h > 0 ? tokens1h : Math.round(tokens24h / 24)
+
+    let willExhaustBeforeReset = false
+    let projectedExhaustionAt = null
+    let hoursToExhaustion = null
+    let remainingMs = null
+
+    if (quota && typeof quota.percentage === 'number') {
+      const remainingPercent = Math.max(0, Math.min(100, quota.percentage))
+      const resetAt = typeof quota.resetAt === 'number' ? quota.resetAt : null
+
+      if (resetAt && resetAt > nowMs) {
+        remainingMs = resetAt - nowMs
+      }
+
+      // If quota is low and active burn rate exists
+      if (burnRateTokensPerHour > 0 && remainingPercent > 0) {
+        // Approximate burn rate percentage per hour based on 24h consumption
+        // If 24h consumed tokens24h and quota dropped, estimate burn % per hour
+        const estimatedPercentPerHour = tokens24h > 0 ? Math.max(0.5, (100 - remainingPercent) / 24) : 0
+        if (estimatedPercentPerHour > 0) {
+          hoursToExhaustion = Math.round((remainingPercent / estimatedPercentPerHour) * 10) / 10
+          const msToExhaustion = hoursToExhaustion * ONE_HOUR
+          if (remainingMs !== null && msToExhaustion < remainingMs) {
+            willExhaustBeforeReset = true
+            projectedExhaustionAt = nowMs + msToExhaustion
+          }
+        }
+      }
+    }
+
+    forecast.push({
+      ref,
+      provider: acc.provider,
+      label: acc.label || ref,
+      quotaPercent: quota && typeof quota.percentage === 'number' ? quota.percentage : null,
+      resetAt: quota && typeof quota.resetAt === 'number' ? quota.resetAt : null,
+      burnRateTokensPerHour,
+      requests24h,
+      tokens24h,
+      hoursToExhaustion,
+      willExhaustBeforeReset,
+      projectedExhaustionAt,
+    })
+  }
+
+  return forecast
+}
+
+export function calculateAnalytics(entries = [], accounts = [], nowMs = Date.now()) {
+  return {
+    generatedAt: new Date(nowMs).toISOString(),
+    totalRequests: entries.length,
+    cache: calculateCacheMetrics(entries),
+    performance: calculatePerformanceMetrics(entries),
+    hourly: calculateHourlyBuckets(entries, nowMs),
+    accounts: calculateAccountBreakdown(entries, accounts),
+    forecast: calculateQuotaForecast(accounts, entries, nowMs),
+  }
+}