@goodandready/dsh-clinebot 0.3.7 → 0.3.9

package/lib/cline-client.js

@@ -2,7 +2,7 @@
  * ClineBot / ClinePass client helpers for DeepSeek Harness.
  *
  * Implements OpenAI-compatible chat completions interface, usage quota tracking,
- * and secure credential storage via DSH credentials service.
+ * Stale-While-Revalidate caching, smart failover, and secure credential storage.
  */
 
 import {
@@ -19,6 +19,7 @@ export const DEFAULT_BASE_URL = 'https://api.cline.bot/api/v1'
 export const DEFAULT_API_KEY_ENV = 'CLINEBOT_API_KEY'
 export const DEFAULT_TIMEOUT_MS = 15000
 export const DEFAULT_SMOKE_TIMEOUT_MS = 25000
+export const USAGE_CACHE_TTL_MS = 60000
 
 export { PROVIDER_ID, PROVIDER_DISPLAY_NAME, DEFAULT_MODEL_ID }
 
@@ -130,8 +131,14 @@ function abortAfter(ms) {
   return { signal: ac.signal, cancel: () => clearTimeout(timer) }
 }
 
-// In-memory cache for quota queries to avoid hammering the ClinePass endpoint
-const usageCache = new Map()
+// In-memory caches for quota queries and host health probes
+export const usageCache = new Map()
+export const probeCache = new Map()
+
+export function clearProbeCache() {
+  probeCache.clear()
+}
+
 export function clearUsageCache() {
   usageCache.clear()
 }
@@ -149,7 +156,6 @@ export async function retryWithBackoff(fn, {
   while (true) {
     try {
       const res = await fn()
-      // If HTTP response-like object with 5xx or 429 status and can retry
       if (res && typeof res.status === 'number' && [429, 502, 503, 504].includes(res.status) && attempt < maxRetries) {
         attempt++
         const retryAfter = res.headers?.get ? Number(res.headers.get('retry-after')) * 1000 : 0
@@ -173,14 +179,13 @@ export async function retryWithBackoff(fn, {
 
 /**
  * Fetch official ClinePass rate limits and account quota.
- * Endpoints:
- * - GET /users/me/plan/usage-limits (5-hour, weekly, monthly rolling limits)
- * - GET /users/me (account metadata)
+ * Uses Stale-While-Revalidate (SWR) caching with keep-alive and network retry.
  */
 export async function fetchUsageLimits(baseUrl, apiKey, {
   timeoutMs = DEFAULT_TIMEOUT_MS,
   fetchImpl = fetch,
   bypassCache = false,
+  ttlMs = USAGE_CACHE_TTL_MS,
 } = {}) {
   const base = normalizeBaseUrl(baseUrl)
   if (!apiKey) {
@@ -190,153 +195,202 @@ export async function fetchUsageLimits(baseUrl, apiKey, {
   const cacheKey = `cline:usage:${apiKey.slice(-8)}`
   const now = Date.now()
 
-  if (!bypassCache && usageCache.has(cacheKey)) {
-    const cached = usageCache.get(cacheKey)
-    if (cached.expiresAt > now) {
-      return cached.data
-    }
-  }
-
-  const { signal, cancel } = abortAfter(timeoutMs)
-  try {
-    const headers = {
-      Authorization: `Bearer ${apiKey}`,
-      Accept: 'application/json',
-    }
-
-    // 1. Fetch usage limits
-    const limitsRes = await fetchImpl(`${base}/users/me/plan/usage-limits`, {
-      method: 'GET',
-      headers,
-      signal,
-    })
-
-    if (!limitsRes.ok) {
-      const errText = await limitsRes.text().catch(() => '')
-      return {
-        ok: false,
-        status: limitsRes.status,
-        error: `ClinePass limits error (HTTP ${limitsRes.status}): ${errText.slice(0, 150)}`,
+  const doFetch = async () => {
+    const { signal, cancel } = abortAfter(timeoutMs)
+    try {
+      const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: 'application/json',
       }
-    }
-
-    const limitsData = await limitsRes.json().catch(() => ({}))
-    const rawLimits = limitsData?.data?.limits || limitsData?.limits || []
 
-    const parseWindow = (type) => {
-      const found = Array.isArray(rawLimits) ? rawLimits.find((l) => l.type === type) : null
-      if (!found) return null
-      const percentUsed = typeof found.percentUsed === 'number'
-        ? Math.max(0, Math.min(100, Math.round(found.percentUsed * 10) / 10))
-        : 0
-      const remainingPercent = Math.max(0, Math.round((100 - percentUsed) * 10) / 10)
-      return {
-        type,
-        percentUsed,
-        remainingPercent,
-        resetsAt: found.resetsAt || null,
+      let limitsRes
+      try {
+        limitsRes = await fetchImpl(`${base}/users/me/plan/usage-limits`, {
+          method: 'GET',
+          headers,
+          signal,
+          keepalive: true,
+        })
+      } catch (netErr) {
+        // Quick 1-retry fallback on transient network drop
+        await new Promise((r) => setTimeout(r, 250))
+        limitsRes = await fetchImpl(`${base}/users/me/plan/usage-limits`, {
+          method: 'GET',
+          headers,
+          signal,
+          keepalive: true,
+        })
       }
-    }
 
-    const fiveHour = parseWindow('5-hour')
-    const weekly = parseWindow('weekly')
-    const monthly = parseWindow('monthly')
-
-    // 2. Fetch user metadata and plan details (optional, best-effort)
-    let userEmail = null
-    let createdAt = null
-    let planDisplayName = 'ClinePass ($9.99/mo)'
-    let dynamicModels = []
+      if (!limitsRes.ok) {
+        const errText = await limitsRes.text().catch(() => '')
+        const outcome = {
+          ok: false,
+          status: limitsRes.status,
+          error: `ClinePass limits error (HTTP ${limitsRes.status}): ${errText.slice(0, 150)}`,
+          checkedAt: Date.now(),
+        }
+        if (!usageCache.has(cacheKey)) {
+          usageCache.set(cacheKey, { data: outcome, expiresAt: Date.now() + 5000, isRevalidating: false })
+        }
+        return outcome
+      }
 
-    try {
-      const [meRes, planRes] = await Promise.all([
-        fetchImpl(`${base}/users/me`, { method: 'GET', headers, signal }).catch(() => null),
-        fetchImpl(`${base}/users/me/plan`, { method: 'GET', headers, signal }).catch(() => null),
-      ])
-
-      if (meRes && meRes.ok) {
-        const meData = await meRes.json().catch(() => ({}))
-        const me = meData?.data || meData?.user || meData
-        userEmail = me?.email || null
-        createdAt = me?.createdAt || null
+      const limitsData = await limitsRes.json().catch(() => ({}))
+      const rawLimits = limitsData?.data?.limits || limitsData?.limits || []
+
+      const parseWindow = (type) => {
+        const found = Array.isArray(rawLimits) ? rawLimits.find((l) => l.type === type) : null
+        if (!found) return null
+        const percentUsed = typeof found.percentUsed === 'number'
+          ? Math.max(0, Math.min(100, Math.round(found.percentUsed * 10) / 10))
+          : 0
+        const remainingPercent = Math.max(0, Math.round((100 - percentUsed) * 10) / 10)
+        return {
+          type,
+          percentUsed,
+          remainingPercent,
+          resetsAt: found.resetsAt || null,
+        }
       }
 
-      if (planRes && planRes.ok) {
-        const planData = await planRes.json().catch(() => ({}))
-        const planObj = planData?.data?.plan || planData?.plan
-        if (planObj?.displayName) {
-          planDisplayName = planObj.displayName
+      const fiveHour = parseWindow('5-hour')
+      const weekly = parseWindow('weekly')
+      const monthly = parseWindow('monthly')
+
+      let userEmail = null
+      let createdAt = null
+      let planDisplayName = 'ClinePass ($9.99/mo)'
+      let dynamicModels = []
+
+      try {
+        const [meRes, planRes] = await Promise.all([
+          fetchImpl(`${base}/users/me`, { method: 'GET', headers, signal, keepalive: true }).catch(() => null),
+          fetchImpl(`${base}/users/me/plan`, { method: 'GET', headers, signal, keepalive: true }).catch(() => null),
+        ])
+
+        if (meRes?.ok) {
+          const meData = await meRes.json().catch(() => ({}))
+          userEmail = meData?.data?.email || meData?.email || null
+          createdAt = meData?.data?.createdAt || meData?.createdAt || null
         }
-        const includedArr = planObj?.features?.included
-        if (Array.isArray(includedArr)) {
-          const incStr = includedArr.find((s) => typeof s === 'string' && s.toLowerCase().includes('includes'))
-          if (incStr) {
-            dynamicModels = parsePlanIncludedModels(incStr)
+
+        if (planRes?.ok) {
+          const planData = await planRes.json().catch(() => ({}))
+          const plan = planData?.data || planData
+          if (plan?.title || plan?.name) {
+            planDisplayName = `${plan.title || plan.name} ($${((plan.priceInCents || 999) / 100).toFixed(2)}/mo)`
+          }
+          if (Array.isArray(plan?.includedModels)) {
+            dynamicModels = parsePlanIncludedModels(plan.includedModels)
           }
         }
+      } catch {
+        /* best-effort secondary details */
       }
-    } catch {
-      /* ignore user metadata / plan failure */
-    }
 
-    const result = {
-      ok: true,
-      plan: planDisplayName,
-      user: {
-        email: userEmail,
-        createdAt,
-      },
-      windows: {
-        fiveHour: fiveHour || { type: '5-hour', percentUsed: 0, remainingPercent: 100, resetsAt: null },
-        weekly: weekly || { type: 'weekly', percentUsed: 0, remainingPercent: 100, resetsAt: null },
-        monthly: monthly || { type: 'monthly', percentUsed: 0, remainingPercent: 100, resetsAt: null },
-      },
-      dynamicModels,
-      checkedAt: now,
+      const result = {
+        ok: true,
+        plan: planDisplayName,
+        user: { email: userEmail, createdAt },
+        windows: { fiveHour, weekly, monthly },
+        dynamicModels,
+        checkedAt: Date.now(),
+      }
+
+      usageCache.set(cacheKey, { data: result, expiresAt: Date.now() + ttlMs, isRevalidating: false })
+      return result
+    } catch (err) {
+      const outcome = {
+        ok: false,
+        error: String(err?.message || err),
+        checkedAt: Date.now(),
+      }
+      if (!usageCache.has(cacheKey)) {
+        usageCache.set(cacheKey, { data: outcome, expiresAt: Date.now() + 5000, isRevalidating: false })
+      }
+      return outcome
+    } finally {
+      cancel()
     }
+  }
 
-    // Cache for 60 seconds
-    usageCache.set(cacheKey, { expiresAt: now + 60000, data: result })
-    return result
-  } catch (err) {
-    return {
-      ok: false,
-      error: String(err?.message || err),
+  if (!bypassCache && usageCache.has(cacheKey)) {
+    const cached = usageCache.get(cacheKey)
+    if (cached.expiresAt > now) {
+      return cached.data
     }
-  } finally {
-    cancel()
+    // SWR: return stale data immediately, revalidate asynchronously
+    if (!cached.isRevalidating) {
+      cached.isRevalidating = true
+      doFetch().catch(() => {})
+    }
+    return cached.data
   }
+
+  return doFetch()
 }
 
 /**
- * Quick network probe to verify server availability.
+ * Health check probe with SWR caching.
  */
-export async function probeHealth(baseUrl, { timeoutMs = DEFAULT_TIMEOUT_MS, fetchImpl = fetch } = {}) {
-  const root = normalizeBaseUrl(baseUrl)
-  const { signal, cancel } = abortAfter(timeoutMs)
-  const start = Date.now()
-  try {
-    const res = await fetchImpl(root, { method: 'GET', signal }).catch(async () => {
-      return await fetchImpl(root, { method: 'HEAD', signal })
-    })
-    const latencyMs = Date.now() - start
-    const reachable = res.status > 0 && res.status < 500
-    return {
-      ok: reachable,
-      status: res.status,
-      latencyMs,
-      error: reachable ? null : `HTTP status ${res.status}`,
+export async function probeHealth(baseUrl, {
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  fetchImpl = fetch,
+  bypassCache = false,
+  ttlMs = 25000,
+} = {}) {
+  const base = normalizeBaseUrl(baseUrl)
+  const root = base.replace(/\/api\/v1$/i, '')
+  const cacheKey = `cline:health:${root}`
+  const now = Date.now()
+
+  const doProbe = async () => {
+    const { signal, cancel } = abortAfter(timeoutMs)
+    const start = Date.now()
+    try {
+      const res = await retryWithBackoff(async () => {
+        return await fetchImpl(root, { method: 'HEAD', signal, keepalive: true })
+      })
+      const latencyMs = Date.now() - start
+      const reachable = res.status > 0 && res.status < 500
+      const outcome = {
+        ok: reachable,
+        status: res.status,
+        latencyMs,
+        error: reachable ? null : `HTTP status ${res.status}`,
+        checkedAt: Date.now(),
+      }
+      probeCache.set(cacheKey, { data: outcome, expiresAt: Date.now() + ttlMs, isRevalidating: false })
+      return outcome
+    } catch (err) {
+      const latencyMs = Date.now() - start
+      const outcome = {
+        ok: false,
+        latencyMs,
+        error: String(err?.message || err),
+        checkedAt: Date.now(),
+      }
+      probeCache.set(cacheKey, { data: outcome, expiresAt: Date.now() + 5000, isRevalidating: false })
+      return outcome
+    } finally {
+      cancel()
     }
-  } catch (err) {
-    const latencyMs = Date.now() - start
-    return {
-      ok: false,
-      latencyMs,
-      error: String(err?.message || err),
+  }
+
+  if (!bypassCache && probeCache.has(cacheKey)) {
+    const cached = probeCache.get(cacheKey)
+    if (cached.expiresAt > now) {
+      return cached.data
     }
-  } finally {
-    cancel()
+    if (!cached.isRevalidating) {
+      cached.isRevalidating = true
+      doProbe().catch(() => {})
+    }
+    return cached.data
   }
+
+  return doProbe()
 }
 
 /**
@@ -368,6 +422,7 @@ export async function smokeChat(baseUrl, apiKey, {
         stream: false,
       }),
       signal,
+      keepalive: true,
     })
 
     const latencyMs = Date.now() - start
@@ -385,12 +440,18 @@ export async function smokeChat(baseUrl, apiKey, {
 
     const payload = data?.data && typeof data.data === 'object' ? data.data : data
     const content = payload?.choices?.[0]?.message?.content || payload?.choices?.[0]?.message?.reasoning
+    const promptTokens = Number(data?.usage?.prompt_tokens) || Number(payload?.usage?.prompt_tokens) || 0
+    const completionTokens = Number(data?.usage?.completion_tokens) || Number(payload?.usage?.completion_tokens) || 0
+    const totalTokens = Number(data?.usage?.total_tokens) || Number(payload?.usage?.total_tokens) || (promptTokens + completionTokens)
     return {
       ok: true,
       status: res.status,
       latencyMs,
       model: payload?.model || model,
       preview: typeof content === 'string' ? content.trim().slice(0, 150) : 'OK',
+      promptTokens,
+      completionTokens,
+      totalTokens,
     }
   } catch (err) {
     const latencyMs = Date.now() - start
@@ -446,3 +507,151 @@ export function buildPiAiProvider({
     models: modelList,
   }
 }
+
+/**
+ * Safely resolve key value from DSH credentials service or process.env.
+ */
+export async function resolveKeyValue(ctx, apiKeyEnv) {
+  const refName = String(apiKeyEnv || DEFAULT_API_KEY_ENV).trim() || DEFAULT_API_KEY_ENV
+  const creds = (ctx?.get && ctx.get('credentials')) || ctx?.credentials
+  if (creds && typeof creds.resolve === 'function') {
+    try {
+      const ref = await toCredentialRef(refName)
+      const hit = await creds.resolve(ref)
+      if (hit?.value) {
+        return { envName: refName, value: hit.value, source: 'credentials' }
+      }
+    } catch {
+      /* miss */
+    }
+  }
+
+  const fromEnv = resolveApiKey(refName)
+  if (fromEnv.value) {
+    return { ...fromEnv, source: 'env' }
+  }
+
+  return { envName: refName, value: '', source: 'none' }
+}
+
+/**
+ * Resolve all accounts in pool with their status and keys.
+ */
+export async function resolveAccountPool(ctx, cfg) {
+  const apiKeyEnv = cfg?.apiKeyEnv || DEFAULT_API_KEY_ENV
+  const defaultSlot = {
+    id: 'default',
+    label: 'Default',
+    apiKeyEnv,
+  }
+  const accounts = Array.isArray(cfg?.accounts) ? cfg.accounts : []
+  const allSlots = [defaultSlot, ...accounts]
+  const activeAccount = String(cfg?.activeAccount || '')
+  const resolved = []
+
+  for (let i = 0; i < allSlots.length; i++) {
+    const slot = allSlots[i]
+    const envName = slot.apiKeyEnv || (i === 0 ? apiKeyEnv : `CLINEBOT_API_KEY_${i + 1}`)
+    const keyInfo = await resolveKeyValue(ctx, envName)
+    resolved.push({
+      id: slot.id || (i === 0 ? 'default' : `account-${i + 1}`),
+      label: slot.label || (i === 0 ? 'Default' : `Account ${i + 1}`),
+      apiKeyEnv: envName,
+      present: Boolean(keyInfo.value),
+      source: keyInfo.source,
+      value: keyInfo.value,
+      isPinned: activeAccount ? activeAccount === envName : i === 0,
+    })
+  }
+
+  return resolved
+}
+
+/**
+ * Check if a cached quota entry is currently exhausted.
+ * Checks 5-hour rolling limit and verifies if resetsAt timestamp has already elapsed.
+ */
+export function isAccountQuotaExhausted(usage) {
+  if (!usage?.windows?.fiveHour) return false
+  const fiveHour = usage.windows.fiveHour
+  if (typeof fiveHour.percentUsed !== 'number' || fiveHour.percentUsed < 95) {
+    return false
+  }
+  // Auto-recovery: if resetsAt is present and in the past, the account is recovered
+  if (fiveHour.resetsAt) {
+    const resetTime = new Date(fiveHour.resetsAt).getTime()
+    if (!Number.isNaN(resetTime) && Date.now() >= resetTime) {
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * Smart Quota-Aware Failover: rotates active account upon 429 or quota exhaustion.
+ * Prioritizes accounts with lowest percentUsed and respects resetsAt recovery.
+ */
+export async function rotateToNextAccount(ctx, cfg, reason = 'rate_limit', settingsApi = null) {
+  const pool = await resolveAccountPool(ctx, cfg)
+  const configured = pool.filter((acc) => acc.present && acc.value)
+  if (configured.length <= 1) {
+    return { rotated: false, reason, message: 'Pool has only 1 configured account' }
+  }
+
+  const active = String(cfg?.activeAccount || configured[0].apiKeyEnv)
+  const currentIndex = configured.findIndex((acc) => acc.apiKeyEnv === active)
+
+  // Candidate pool excluding current account if possible
+  const candidates = configured.filter((acc) => acc.apiKeyEnv !== active)
+  if (!candidates.length) {
+    return { rotated: false, reason, message: 'No alternative accounts configured' }
+  }
+
+  // Assess quota for candidates if cached in memory
+  let bestCandidate = null
+  let lowestUsagePct = Infinity
+
+  for (const cand of candidates) {
+    const cacheKey = `cline:usage:${cand.value.slice(-8)}`
+    const cached = usageCache.get(cacheKey)?.data
+    const isExhausted = isAccountQuotaExhausted(cached)
+
+    if (!isExhausted) {
+      const pct = cached?.windows?.fiveHour?.percentUsed ?? 50
+      if (pct < lowestUsagePct) {
+        lowestUsagePct = pct
+        bestCandidate = cand
+      }
+    }
+  }
+
+  // Fallback if all candidates are either exhausted or uncached: pick next in round-robin
+  const nextAcc = bestCandidate || candidates[currentIndex % candidates.length] || candidates[0]
+
+  let updated = false
+  if (settingsApi?.replace) {
+    try {
+      const next = { ...cfg, activeAccount: nextAcc.apiKeyEnv }
+      await settingsApi.replace(next)
+      updated = true
+    } catch {}
+  } else {
+    const settings = (ctx?.get && ctx.get('settings')) || ctx?.settings
+    if (settings?.mutate) {
+      try {
+        await settings.mutate('dsh-clinebot', [
+          { op: 'set', path: ['activeAccount'], value: nextAcc.apiKeyEnv },
+        ])
+        updated = true
+      } catch {}
+    }
+  }
+
+  return {
+    rotated: true,
+    previousAccount: active,
+    activeAccount: nextAcc.apiKeyEnv,
+    reason,
+    updatedSettings: updated,
+  }
+}