@goodandready/dsh-clinebot 0.3.8 → 0.3.10

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,8 @@ 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() {
@@ -155,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
@@ -179,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) {
@@ -196,126 +195,144 @@ 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,
-    })
+  const doFetch = async () => {
+    const { signal, cancel } = abortAfter(timeoutMs)
+    try {
+      const headers = {
+        Authorization: `Bearer ${apiKey}`,
+        Accept: 'application/json',
+      }
 
-    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)}`,
+      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 limitsData = await limitsRes.json().catch(() => ({}))
-    const rawLimits = limitsData?.data?.limits || limitsData?.limits || []
+      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
+      }
 
-    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,
+      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,
+        }
       }
-    }
 
-    const fiveHour = parseWindow('5-hour')
-    const weekly = parseWindow('weekly')
-    const monthly = parseWindow('monthly')
+      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 = []
+      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 }).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
-      }
+      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 (planRes && planRes.ok) {
-        const planData = await planRes.json().catch(() => ({}))
-        const planObj = planData?.data?.plan || planData?.plan
-        if (planObj?.displayName) {
-          planDisplayName = planObj.displayName
+        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 with Stale-While-Revalidate caching.
+ * Health check probe with SWR caching.
  */
 export async function probeHealth(baseUrl, {
   timeoutMs = DEFAULT_TIMEOUT_MS,
@@ -323,15 +340,16 @@ export async function probeHealth(baseUrl, {
   bypassCache = false,
   ttlMs = 25000,
 } = {}) {
-  const root = normalizeBaseUrl(baseUrl)
-  const cacheKey = `probe:${root}`
+  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 fetchImpl(root, { method: 'GET', signal, keepalive: true }).catch(async () => {
+      const res = await retryWithBackoff(async () => {
         return await fetchImpl(root, { method: 'HEAD', signal, keepalive: true })
       })
       const latencyMs = Date.now() - start
@@ -365,7 +383,6 @@ export async function probeHealth(baseUrl, {
     if (cached.expiresAt > now) {
       return cached.data
     }
-    // Stale-While-Revalidate: trigger async refresh and return stale snapshot immediately
     if (!cached.isRevalidating) {
       cached.isRevalidating = true
       doProbe().catch(() => {})
@@ -476,8 +493,27 @@ export function buildPiAiProvider({
       input: hasImage ? ['text', 'image'] : ['text'],
       provider: PROVIDER_ID,
     }
+    const validEfforts = ['off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']
     if (Array.isArray(item.reasoningEfforts) && item.reasoningEfforts.length) {
-      res.reasoningEfforts = [...item.reasoningEfforts]
+      const efforts = {}
+      for (const effort of item.reasoningEfforts) {
+        const key = String(effort).trim().toLowerCase()
+        if (validEfforts.includes(key)) {
+          efforts[key] = key
+        }
+      }
+      res.reasoningEfforts = Object.keys(efforts).length ? efforts : false
+    } else if (item.reasoningEfforts && typeof item.reasoningEfforts === 'object' && !Array.isArray(item.reasoningEfforts)) {
+      const efforts = {}
+      for (const [k, v] of Object.entries(item.reasoningEfforts)) {
+        const key = String(k).trim().toLowerCase()
+        if (validEfforts.includes(key)) {
+          efforts[key] = typeof v === 'string' && v.trim() ? v.trim() : key
+        }
+      }
+      res.reasoningEfforts = Object.keys(efforts).length ? efforts : false
+    } else {
+      res.reasoningEfforts = false
     }
     return res
   })
@@ -492,7 +528,7 @@ export function buildPiAiProvider({
 }
 
 /**
- * Safely resolve key value from DSH credentials or process.env.
+ * 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
@@ -551,7 +587,28 @@ export async function resolveAccountPool(ctx, cfg) {
 }
 
 /**
- * Rotate active account to next available configured account upon rate-limiting (429) or quota exhaustion.
+ * 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)
@@ -562,8 +619,33 @@ export async function rotateToNextAccount(ctx, cfg, reason = 'rate_limit', setti
 
   const active = String(cfg?.activeAccount || configured[0].apiKeyEnv)
   const currentIndex = configured.findIndex((acc) => acc.apiKeyEnv === active)
-  const nextIndex = (currentIndex + 1) % configured.length
-  const nextAcc = configured[nextIndex]
+
+  // 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) {
@@ -571,7 +653,9 @@ export async function rotateToNextAccount(ctx, cfg, reason = 'rate_limit', setti
       const next = { ...cfg, activeAccount: nextAcc.apiKeyEnv }
       await settingsApi.replace(next)
       updated = true
-    } catch {}
+    } catch (err) {
+      ctx?.logger?.warn?.('[dsh-clinebot] Failed to persist rotated activeAccount via settingsApi: ' + (err?.message || err))
+    }
   } else {
     const settings = (ctx?.get && ctx.get('settings')) || ctx?.settings
     if (settings?.mutate) {
@@ -580,10 +664,16 @@ export async function rotateToNextAccount(ctx, cfg, reason = 'rate_limit', setti
           { op: 'set', path: ['activeAccount'], value: nextAcc.apiKeyEnv },
         ])
         updated = true
-      } catch {}
+      } catch (err) {
+        ctx?.logger?.warn?.('[dsh-clinebot] Failed to persist rotated activeAccount via settings.mutate: ' + (err?.message || err))
+      }
     }
   }
 
+  // Reset cached quota and host probes so new account immediately revalidates
+  clearUsageCache()
+  clearProbeCache()
+
   return {
     rotated: true,
     previousAccount: active,

package/lib/http.js

@@ -28,7 +28,67 @@ export function readBody(req, maxBytes = 256 * 1024) {
   })
 }
 
-/** Reject cross-site writes. LAN / reverse-proxy UIs are allowed. */
+function header(request, name) {
+  const value = request?.headers?.[name.toLowerCase()]
+  return Array.isArray(value) ? value[0] : value
+}
+
+function isLoopbackAddress(value) {
+  const address = String(value || '').toLowerCase().replace(/^\[|\]$/g, '')
+  return address === 'localhost' || address === 'localhost.' || address === '::1'
+    || address.startsWith('127.')
+    || address.startsWith('::ffff:127.')
+}
+
+/** Reject cross-site writes while allowing local, LAN, and reverse-proxy UIs. */
 export function isTrustedSettingsRequest(request) {
-  return request.headers['sec-fetch-site'] !== 'cross-site'
+  const secFetchSite = header(request, 'sec-fetch-site')
+  if (secFetchSite === 'cross-site') {
+    return false
+  }
+
+  const host = header(request, 'x-forwarded-host') || header(request, 'host')
+  const origin = header(request, 'origin')
+  if (origin) {
+    try {
+      const url = new URL(origin)
+      if (host && url.host.toLowerCase() === host.toLowerCase()) {
+        return true
+      }
+      if (isLoopbackAddress(url.hostname) && isLoopbackAddress(request?.socket?.remoteAddress)) {
+        return true
+      }
+      return false
+    } catch {
+      return false
+    }
+  }
+
+  const referer = header(request, 'referer')
+  if (referer) {
+    try {
+      const url = new URL(referer)
+      if (host && url.host.toLowerCase() === host.toLowerCase()) {
+        return true
+      }
+      if (isLoopbackAddress(url.hostname) && isLoopbackAddress(request?.socket?.remoteAddress)) {
+        return true
+      }
+      return false
+    } catch {
+      return false
+    }
+  }
+
+  // Requests without origin/referer (e.g. curl or internal requests): allow if loopback
+  if (isLoopbackAddress(request?.socket?.remoteAddress)) {
+    return true
+  }
+
+  // If sec-fetch-site is explicitly same-origin or same-site, allow
+  if (secFetchSite === 'same-origin' || secFetchSite === 'same-site') {
+    return true
+  }
+
+  return false
 }