@goodandready/dsh-clinebot 0.4.7 → 0.4.8

package/lib/session-router.js

@@ -0,0 +1,188 @@
+/**
+ * Session Router & Least-Used Sticky Balancing (Issue #128)
+ *
+ * Implements sticky session pinning with least-used quota routing:
+ * 1. An account with the highest available quota (lowest percentUsed) is selected on session start.
+ * 2. The account is pinned to the session for all subsequent requests in that session.
+ * 3. Mid-session failover occurs strictly if the pinned account encounters HTTP 429 or quota depletion.
+ * 4. Automatic cooldown recovery restores accounts once their rate-limit / reset timestamp has elapsed.
+ */
+
+// In-memory sessions: sessionId -> { accountId, assignedAt, lastUsedAt }
+const sessions = new Map()
+
+// In-memory cooldowns: accountId -> { until: timestamp, reason: string }
+const cooldowns = new Map()
+
+/**
+ * Check if an account is currently in cooldown or rate-limited.
+ * Performs automatic recovery if the cooldown duration has passed.
+ *
+ * @param {string} accountId
+ * @returns {boolean} true if account is currently blocked
+ */
+export function isAccountInCooldown(accountId) {
+  if (!accountId) return false
+  const entry = cooldowns.get(accountId)
+  if (!entry) return false
+
+  if (Date.now() >= entry.until) {
+    cooldowns.delete(accountId)
+    return false
+  }
+  return true
+}
+
+/**
+ * Mark an account as in cooldown (rate-limited or quota exhausted).
+ *
+ * @param {string} accountId
+ * @param {number} [durationMs=60000] Default 60s cooldown if resetsAt is not provided
+ * @param {string|number|null} [resetsAt] ISO string or timestamp of quota window reset
+ * @param {string} [reason='rate_limit']
+ */
+export function markAccountCooldown(accountId, durationMs = 60000, resetsAt = null, reason = 'rate_limit') {
+  if (!accountId) return
+
+  let until = Date.now() + durationMs
+
+  if (resetsAt) {
+    const resetTime = typeof resetsAt === 'number' ? resetsAt : new Date(resetsAt).getTime()
+    if (!Number.isNaN(resetTime) && resetTime > Date.now()) {
+      until = resetTime
+    }
+  }
+
+  cooldowns.set(accountId, { until, reason })
+}
+
+/**
+ * Clear cooldown for an account manually.
+ *
+ * @param {string} accountId
+ */
+export function clearAccountCooldown(accountId) {
+  if (accountId) {
+    cooldowns.delete(accountId)
+  }
+}
+
+/**
+ * Select the best account from the pool based on least-used quota.
+ * Lowest percentUsed is prioritized.
+ *
+ * @param {Array<Object>} accounts Pool of accounts
+ * @returns {Object|null} Selected account or null
+ */
+export function selectLeastUsedAccount(accounts = []) {
+  if (!Array.isArray(accounts) || accounts.length === 0) {
+    return null
+  }
+
+  // Filter available accounts that have keys present and are not in cooldown
+  const available = accounts.filter(acc => {
+    if (!acc || acc.present === false) return false
+    return !isAccountInCooldown(acc.id || acc.label)
+  })
+
+  const candidatePool = available.length > 0 ? available : accounts.filter(a => a && a.present !== false)
+  if (candidatePool.length === 0) {
+    return accounts[0] || null
+  }
+
+  // Sort by lowest percentUsed (least used). If percentUsed is null/undefined, treat as 0% used
+  const sorted = [...candidatePool].sort((a, b) => {
+    const aUsed = typeof a.percentUsed === 'number' ? a.percentUsed : 0
+    const bUsed = typeof b.percentUsed === 'number' ? b.percentUsed : 0
+    return aUsed - bUsed
+  })
+
+  return sorted[0]
+}
+
+/**
+ * Resolve or assign an account for a given session.
+ *
+ * @param {string|null} sessionId Unique session or conversation identifier
+ * @param {Array<Object>} accounts Configured accounts pool
+ * @param {string} [defaultActiveId] Fallback active account ID
+ * @returns {{ account: Object|null, isReassigned: boolean, reason: string }}
+ */
+export function resolveSessionAccount(sessionId, accounts = [], defaultActiveId = '') {
+  const safeAccounts = Array.isArray(accounts) ? accounts : []
+  if (safeAccounts.length === 0) {
+    return { account: null, isReassigned: false, reason: 'empty_pool' }
+  }
+
+  // If no sessionId is provided, use least-used account or default active
+  if (!sessionId) {
+    const best = selectLeastUsedAccount(safeAccounts) || safeAccounts.find(a => a.id === defaultActiveId) || safeAccounts[0]
+    return { account: best, isReassigned: false, reason: 'no_session_id' }
+  }
+
+  const existing = sessions.get(sessionId)
+  if (existing) {
+    const assigned = safeAccounts.find(a => (a.id || a.label) === existing.accountId)
+    // If assigned account is still valid and NOT in cooldown, keep sticky pin
+    if (assigned && !isAccountInCooldown(assigned.id || assigned.label)) {
+      existing.lastUsedAt = Date.now()
+      return { account: assigned, isReassigned: false, reason: 'sticky_pinned' }
+    }
+    // Failover: account was deleted or entered cooldown mid-session
+  }
+
+  // New session or mid-session failover: pick least-used account
+  const chosen = selectLeastUsedAccount(safeAccounts) || safeAccounts.find(a => a.id === defaultActiveId) || safeAccounts[0]
+  if (chosen) {
+    const chosenId = chosen.id || chosen.label
+    sessions.set(sessionId, {
+      accountId: chosenId,
+      assignedAt: existing ? existing.assignedAt : Date.now(),
+      lastUsedAt: Date.now()
+    })
+  }
+
+  return {
+    account: chosen,
+    isReassigned: Boolean(existing),
+    reason: existing ? 'mid_session_failover' : 'new_session_assigned'
+  }
+}
+
+/**
+ * Explicitly release a session.
+ *
+ * @param {string} sessionId
+ */
+export function releaseSession(sessionId) {
+  if (sessionId) {
+    sessions.delete(sessionId)
+  }
+}
+
+/**
+ * Clear all sessions and cooldowns (for test environments).
+ */
+export function resetSessionRouter() {
+  sessions.clear()
+  cooldowns.clear()
+}
+
+/**
+ * Return current session router diagnostics.
+ */
+export function getSessionRouterStatus() {
+  return {
+    activeSessionsCount: sessions.size,
+    cooldownsCount: cooldowns.size,
+    cooldowns: Object.fromEntries(
+      Array.from(cooldowns.entries()).map(([k, v]) => [
+        k,
+        {
+          remainingMs: Math.max(0, v.until - Date.now()),
+          reason: v.reason
+        }
+      ])
+    )
+  }
+}

package/lib/stats-storage.js

@@ -0,0 +1,217 @@
+/**
+ * Persistent JSON Token Analytics Storage (Issue #129)
+ *
+ * Persists token consumption and request telemetry to ~/.dsh/clinebot-stats.json.
+ * Survives dsh-web service restarts and tracks historical consumption by day, month, model, and account.
+ */
+
+import { readFileSync, writeFileSync, renameSync, mkdirSync, existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import path from 'node:path'
+
+let inMemoryStats = createEmptyStats()
+let saveTimer = null
+let activeStatsPath = ''
+
+/**
+ * Create a fresh, empty stats object.
+ */
+export function createEmptyStats() {
+  return {
+    version: 1,
+    createdAt: Date.now(),
+    updatedAt: Date.now(),
+    totals: {
+      requests: 0,
+      successful: 0,
+      failed: 0,
+      rateLimited429: 0,
+      promptTokens: 0,
+      completionTokens: 0,
+      totalTokens: 0
+    },
+    byDay: {},
+    byMonth: {},
+    byModel: {},
+    byAccount: {}
+  }
+}
+
+/**
+ * Resolve '~' in paths to user's home directory.
+ */
+export function resolvePath(targetPath) {
+  if (!targetPath) {
+    return path.join(homedir(), '.dsh', 'clinebot-stats.json')
+  }
+  if (targetPath.startsWith('~/') || targetPath === '~') {
+    return path.join(homedir(), targetPath.slice(1))
+  }
+  return path.resolve(targetPath)
+}
+
+/**
+ * Load stats from disk.
+ *
+ * @param {string} [customPath]
+ * @returns {Object} Loaded stats
+ */
+export function loadStats(customPath) {
+  const filePath = resolvePath(customPath)
+  activeStatsPath = filePath
+
+  try {
+    if (existsSync(filePath)) {
+      const raw = readFileSync(filePath, 'utf8')
+      const parsed = JSON.parse(raw)
+      if (parsed && typeof parsed === 'object' && parsed.totals) {
+        inMemoryStats = {
+          ...createEmptyStats(),
+          ...parsed,
+          totals: { ...createEmptyStats().totals, ...parsed.totals },
+          byDay: parsed.byDay || {},
+          byMonth: parsed.byMonth || {},
+          byModel: parsed.byModel || {},
+          byAccount: parsed.byAccount || {}
+        }
+        return inMemoryStats
+      }
+    }
+  } catch {
+    // If reading fails or file is corrupted, fallback to clean stats
+  }
+
+  inMemoryStats = createEmptyStats()
+  return inMemoryStats
+}
+
+/**
+ * Synchronously write stats to disk using atomic rename.
+ *
+ * @param {string} [customPath]
+ */
+export function saveStatsSync(customPath) {
+  const filePath = resolvePath(customPath || activeStatsPath)
+  activeStatsPath = filePath
+
+  try {
+    const dir = path.dirname(filePath)
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true })
+    }
+
+    inMemoryStats.updatedAt = Date.now()
+    const tempPath = `${filePath}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`
+    const data = JSON.stringify(inMemoryStats, null, 2)
+
+    writeFileSync(tempPath, data, 'utf8')
+    renameSync(tempPath, filePath)
+  } catch {
+    // Best-effort disk persistence
+  }
+}
+
+/**
+ * Queue a debounced write to avoid disk thrashing during rapid streaming tokens.
+ *
+ * @param {string} [customPath]
+ * @param {number} [debounceMs=500]
+ */
+export function queueSaveStats(customPath, debounceMs = 500) {
+  if (saveTimer) {
+    clearTimeout(saveTimer)
+  }
+  saveTimer = setTimeout(() => {
+    saveTimer = null
+    saveStatsSync(customPath)
+  }, debounceMs)
+}
+
+/**
+ * Record a completion event with usage metrics.
+ *
+ * @param {Object} params
+ * @param {string} [params.model]
+ * @param {string} [params.accountId]
+ * @param {number} [params.promptTokens=0]
+ * @param {number} [params.completionTokens=0]
+ * @param {number} [params.totalTokens=0]
+ * @param {boolean} [params.isError=false]
+ * @param {boolean} [params.is429=false]
+ * @param {string} [params.statsPath]
+ */
+export function recordUsage({
+  model = 'unknown',
+  accountId = 'default',
+  promptTokens = 0,
+  completionTokens = 0,
+  totalTokens = 0,
+  isError = false,
+  is429 = false,
+  statsPath
+} = {}) {
+  const now = new Date()
+  const dayKey = now.toISOString().slice(0, 10) // 'YYYY-MM-DD'
+  const monthKey = dayKey.slice(0, 7) // 'YYYY-MM'
+
+  const safePrompt = Math.max(0, Number(promptTokens) || 0)
+  const safeComp = Math.max(0, Number(completionTokens) || 0)
+  const safeTotal = Math.max(safePrompt + safeComp, Number(totalTokens) || 0)
+
+  // Totals
+  inMemoryStats.totals.requests += 1
+  if (isError) {
+    inMemoryStats.totals.failed += 1
+  } else {
+    inMemoryStats.totals.successful += 1
+  }
+  if (is429) {
+    inMemoryStats.totals.rateLimited429 += 1
+  }
+  inMemoryStats.totals.promptTokens += safePrompt
+  inMemoryStats.totals.completionTokens += safeComp
+  inMemoryStats.totals.totalTokens += safeTotal
+
+  // Helper to increment bucket
+  function incrementBucket(container, key) {
+    if (!container[key]) {
+      container[key] = {
+        requests: 0,
+        promptTokens: 0,
+        completionTokens: 0,
+        totalTokens: 0
+      }
+    }
+    container[key].requests += 1
+    container[key].promptTokens += safePrompt
+    container[key].completionTokens += safeComp
+    container[key].totalTokens += safeTotal
+  }
+
+  incrementBucket(inMemoryStats.byDay, dayKey)
+  incrementBucket(inMemoryStats.byMonth, monthKey)
+  incrementBucket(inMemoryStats.byModel, model)
+  incrementBucket(inMemoryStats.byAccount, accountId)
+
+  queueSaveStats(statsPath)
+}
+
+/**
+ * Retrieve current statistics summary.
+ *
+ * @returns {Object}
+ */
+export function getStatsSummary() {
+  return JSON.parse(JSON.stringify(inMemoryStats))
+}
+
+/**
+ * Reset statistics to initial state and persist.
+ *
+ * @param {string} [customPath]
+ */
+export function resetStats(customPath) {
+  inMemoryStats = createEmptyStats()
+  saveStatsSync(customPath)
+  return inMemoryStats
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-clinebot",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "DeepSeek Harness companion for ClineBot / ClinePass: dynamic subscription models sync, quota exhaustion warnings, session metrics, dedicated settings page, live usage limits, and /cline slash-command.",
   "license": "MIT",
   "type": "module",