@goodandready/dsh-clinebot 0.4.7 → 0.5.0

package/lib/routes/proxy.js

@@ -0,0 +1,290 @@
+/**
+ * Transparent Loopback Proxy & Zero-Downtime Failover (Issue #127)
+ *
+ * Exposes local OpenAI-compatible endpoints:
+ * - POST /dsh-clinebot/v1/chat/completions
+ * - GET  /dsh-clinebot/v1/models
+ *
+ * Implements:
+ * 1. Sticky session routing with least-used quota allocation.
+ * 2. Transparent upstream retry on 429 / quota exhaustion before first chunk is streamed.
+ * 3. Accurate streaming SSE token usage interception & persistent telemetry recording.
+ * 4. Model reasoning_effort default injection from config.
+ */
+
+import { writeJson, readBody, isLoopbackAddress } from '../http.js'
+import { publicConfig, plainConfig } from '../config.js'
+import { resolveAccountPool } from '../account-pool.js'
+import { resolveSessionAccount, markAccountCooldown } from '../session-router.js'
+import { recordUsage } from '../stats-storage.js'
+import { getAllModels, DEFAULT_MODEL_ID } from '../models.js'
+
+export function registerProxyRoutes(ctx, { live, getSettingsApi, syncProviderState }) {
+  // 1. POST /dsh-clinebot/v1/chat/completions
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-clinebot/v1/chat/completions',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') {
+        return writeJson(res, 405, { ok: false, error: 'POST only' })
+      }
+
+      if (!isLoopbackAddress(req.socket?.remoteAddress)) {
+        return writeJson(res, 403, { ok: false, error: 'Loopback access only' })
+      }
+
+      let bodyBuf
+      try {
+        bodyBuf = await readBody(req)
+      } catch (err) {
+        return writeJson(res, 400, { ok: false, error: String(err?.message || err) })
+      }
+
+      let body
+      try {
+        body = JSON.parse(bodyBuf.toString('utf8') || '{}')
+      } catch {
+        return writeJson(res, 400, { ok: false, error: 'Invalid JSON request body' })
+      }
+
+      const cfg = plainConfig(live())
+      const pub = publicConfig(cfg)
+
+      // Session identification
+      const sessionId = String(
+        req.headers['x-dsh-session-id'] ||
+        req.headers['x-session-id'] ||
+        body?.conversation_id ||
+        body?.chat_id ||
+        body?.user ||
+        ''
+      ).trim()
+
+      // Ensure model is set, fallback to defaultModel (#140)
+      body.model = String(body.model || pub.defaultModel || DEFAULT_MODEL_ID).trim()
+
+      // Inject model reasoning effort if model has default configured and payload omitted it
+      if (
+        pub.modelReasoningDefaults &&
+        pub.modelReasoningDefaults[body.model] &&
+        !body.reasoning_effort
+      ) {
+        body.reasoning_effort = pub.modelReasoningDefaults[body.model]
+      }
+
+      const pool = await resolveAccountPool(ctx, cfg)
+      const isStreaming = Boolean(body.stream) || String(req.headers.accept || '').includes('text/event-stream')
+
+      // Transparent retry loop (up to max configured accounts, min 1, max 3)
+      const maxRetries = Math.min(Math.max(1, pool.length), 3)
+      let attempt = 0
+      let lastError = null
+      let targetAccount = null
+
+      while (attempt < maxRetries) {
+        attempt++
+        const routeResult = resolveSessionAccount(sessionId, pool, pub.activeAccount)
+        targetAccount = routeResult.account
+
+        if (!targetAccount || !targetAccount.value) {
+          return writeJson(res, 503, {
+            error: {
+              message: 'No available ClinePass API keys configured in pool',
+              type: 'service_unavailable',
+              code: 'no_keys_available'
+            }
+          })
+        }
+
+        const upstreamUrl = `${pub.baseUrl}/chat/completions`
+        const requestHeaders = {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${targetAccount.value}`,
+          'Accept': isStreaming ? 'text/event-stream' : 'application/json',
+          'User-Agent': '@goodandready/dsh-clinebot/0.5.0'
+        }
+
+        let upstreamRes
+        try {
+          upstreamRes = await fetch(upstreamUrl, {
+            method: 'POST',
+            headers: requestHeaders,
+            body: JSON.stringify(body),
+            keepalive: true
+          })
+        } catch (fetchErr) {
+          lastError = fetchErr
+          // Network errors: retry with next account if available
+          continue
+        }
+
+        // If upstream rejected with 429 or 403 quota exhaustion before streaming, failover!
+        if (upstreamRes.status === 429 || upstreamRes.status === 402) {
+          const accountId = targetAccount.id || targetAccount.label
+          markAccountCooldown(accountId, 60000, null, 'upstream_429')
+          recordUsage({
+            model: body.model,
+            accountId,
+            is429: true,
+            isError: true,
+            statsPath: pub.statsPath
+          })
+          ctx?.logger?.warn?.(`[dsh-clinebot:proxy] Account "${accountId}" hit 429, attempting failover (attempt ${attempt}/${maxRetries})`)
+          continue
+        }
+
+        // Upstream responded with non-retryable response: stream or write JSON to client
+        if (isStreaming && upstreamRes.status === 200 && upstreamRes.body) {
+          res.statusCode = 200
+          res.setHeader('Content-Type', 'text/event-stream; charset=utf-8')
+          res.setHeader('Cache-Control', 'no-cache, no-transform')
+          res.setHeader('Connection', 'keep-alive')
+          if (typeof res.flushHeaders === 'function') {
+            res.flushHeaders()
+          }
+
+          let promptTokens = 0
+          let completionTokens = 0
+          let totalTokens = 0
+          let buffer = ''
+
+          const reader = upstreamRes.body.getReader()
+          const decoder = new TextDecoder('utf8')
+
+          let streamAborted = false
+          const onClientAbort = () => {
+            streamAborted = true
+            try {
+              reader.cancel().catch(() => {})
+            } catch {
+              /* ignore */
+            }
+          }
+          if (typeof req.on === 'function') {
+            req.on('close', onClientAbort)
+          }
+
+          try {
+            while (true) {
+              const { done, value } = await reader.read()
+              if (done || streamAborted) break
+
+              const chunkStr = decoder.decode(value, { stream: true })
+              res.write(value)
+
+              // Parse SSE lines for usage metrics
+              buffer += chunkStr
+              const lines = buffer.split('\n')
+              buffer = lines.pop() // keep incomplete last line
+
+              for (const line of lines) {
+                const trimmed = line.trim()
+                if (trimmed.startsWith('data: ') && trimmed !== 'data: [DONE]') {
+                  try {
+                    const data = JSON.parse(trimmed.slice(6))
+                    if (data?.usage) {
+                      promptTokens = Number(data.usage.prompt_tokens) || promptTokens
+                      completionTokens = Number(data.usage.completion_tokens) || completionTokens
+                      totalTokens = Number(data.usage.total_tokens) || totalTokens
+                    }
+                  } catch {
+                    /* ignore partial or non-json SSE lines */
+                  }
+                }
+              }
+            }
+          } catch (streamErr) {
+            if (!streamAborted) {
+              ctx?.logger?.warn?.(`[dsh-clinebot:proxy] Error streaming SSE chunk: ${streamErr?.message || streamErr}`)
+            }
+          } finally {
+            if (typeof req.off === 'function') {
+              req.off('close', onClientAbort)
+            }
+            res.end()
+            recordUsage({
+              model: body.model,
+              accountId: targetAccount.id || targetAccount.label,
+              promptTokens,
+              completionTokens,
+              totalTokens,
+              statsPath: pub.statsPath
+            })
+          }
+          return
+        }
+
+        // Non-streaming JSON response or error status from upstream
+        const resText = await upstreamRes.text()
+        let resJson = null
+        try {
+          resJson = JSON.parse(resText)
+        } catch {
+          resJson = null
+        }
+
+        if (resJson?.usage) {
+          recordUsage({
+            model: body.model,
+            accountId: targetAccount.id || targetAccount.label,
+            promptTokens: resJson.usage.prompt_tokens,
+            completionTokens: resJson.usage.completion_tokens,
+            totalTokens: resJson.usage.total_tokens,
+            isError: upstreamRes.status >= 400,
+            statsPath: pub.statsPath
+          })
+        }
+
+        res.statusCode = upstreamRes.status
+        res.setHeader('Content-Type', 'application/json; charset=utf-8')
+        res.end(resText)
+        return
+      }
+
+      // Exhausted all retries
+      writeJson(res, 429, {
+        error: {
+          message: 'All configured accounts in pool exceeded rate limits or quota',
+          type: 'rate_limit_exceeded',
+          code: 'rate_limit_exceeded',
+          details: lastError?.message || null
+        }
+      })
+    },
+  }), 'dsh-clinebot: /v1/chat/completions')
+
+  // 2. GET /dsh-clinebot/v1/models (OpenAI standard)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-clinebot/v1/models',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') {
+        return writeJson(res, 405, { ok: false, error: 'GET only' })
+      }
+
+      if (!isLoopbackAddress(req.socket?.remoteAddress)) {
+        return writeJson(res, 403, { ok: false, error: 'Loopback access only' })
+      }
+      const pub = publicConfig(live())
+      const dynamic = Array.isArray(pub.dynamicModels) ? pub.dynamicModels : []
+      const custom = Array.isArray(pub.customModels) ? pub.customModels : []
+      const overrides = Array.isArray(pub.modelContextOverrides) ? pub.modelContextOverrides : []
+      const allModels = getAllModels(dynamic, overrides, custom)
+
+      const modelsData = allModels.map(m => ({
+        id: m.id,
+        object: 'model',
+        created: 1700000000,
+        owned_by: 'clinebot',
+        permission: [],
+        root: m.id,
+        parent: null
+      }))
+
+      writeJson(res, 200, {
+        object: 'list',
+        data: modelsData
+      })
+    },
+  }), 'dsh-clinebot: /v1/models')
+}

package/lib/routes/settings.js

@@ -3,6 +3,7 @@ import { assertTrustedSettingsRequest } from '../access.js'
 import { publicConfig, plainConfig, Config } from '../config.js'
 import { buildStatus } from '../provider-sync.js'
 import { saveCredentialKey, smokeChat, DEFAULT_API_KEY_ENV } from '../cline-client.js'
+import { getStatsSummary, resetStats } from '../stats-storage.js'
 
 export function registerSettingsRoutes(ctx, { live, getSettingsApi, syncProviderState, triggerAutoDiscover }) {
   // 1. GET /dsh-clinebot/status
@@ -171,4 +172,37 @@ export function registerSettingsRoutes(ctx, { live, getSettingsApi, syncProvider
       }
     },
   }), 'dsh-clinebot: /save-key')
+
+  // 4. GET /dsh-clinebot/stats — persistent token analytics summary (Issue #129)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-clinebot/stats',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') return writeJson(res, 405, { ok: false, error: 'GET only' })
+      if (!assertTrustedSettingsRequest(req, res)) return
+      try {
+        const stats = getStatsSummary()
+        writeJson(res, 200, { ok: true, stats })
+      } catch (err) {
+        writeJson(res, 500, { ok: false, error: String(err?.message || err) })
+      }
+    },
+  }), 'dsh-clinebot: /stats')
+
+  // 5. POST /dsh-clinebot/stats/reset — reset persistent stats (Issue #129)
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact',
+    path: '/dsh-clinebot/stats/reset',
+    handler: async (req, res) => {
+      if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })
+      if (!assertTrustedSettingsRequest(req, res)) return
+      try {
+        const pub = publicConfig(live())
+        const stats = resetStats(pub.statsPath)
+        writeJson(res, 200, { ok: true, stats })
+      } catch (err) {
+        writeJson(res, 500, { ok: false, error: String(err?.message || err) })
+      }
+    },
+  }), 'dsh-clinebot: /stats/reset')
 }

package/lib/session-router.js

@@ -0,0 +1,236 @@
+/**
+ * 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()
+
+export const MAX_SESSIONS = 1000
+export const SESSION_TTL_MS = 24 * 60 * 60 * 1000 // 24 hours
+
+/**
+ * Evict expired sessions and trim capacity to maxLimit via LRU.
+ *
+ * @param {number} [now=Date.now()] Current timestamp
+ * @param {number} [maxLimit=MAX_SESSIONS] Capacity threshold
+ * @param {number} [ttlMs=SESSION_TTL_MS] Expiration TTL
+ */
+export function pruneSessions(now = Date.now(), maxLimit = MAX_SESSIONS, ttlMs = SESSION_TTL_MS) {
+  for (const [id, s] of sessions.entries()) {
+    if (now - s.lastUsedAt > ttlMs) {
+      sessions.delete(id)
+    }
+  }
+
+  while (sessions.size > maxLimit) {
+    let oldestId = null
+    let oldestTime = Infinity
+    for (const [id, s] of sessions.entries()) {
+      if (s.lastUsedAt < oldestTime) {
+        oldestTime = s.lastUsedAt
+        oldestId = id
+      }
+    }
+    if (oldestId) {
+      sessions.delete(oldestId)
+    } else {
+      break
+    }
+  }
+}
+
+/**
+ * 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' }
+  }
+
+  let existing = sessions.get(sessionId)
+  const now = Date.now()
+  if (existing) {
+    // TTL eviction check
+    if (now - existing.lastUsedAt > SESSION_TTL_MS) {
+      sessions.delete(sessionId)
+      existing = null
+    } else {
+      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 = now
+        return { account: assigned, isReassigned: false, reason: 'sticky_pinned' }
+      }
+      // Failover: account was deleted or entered cooldown mid-session
+    }
+  }
+
+  // Prune before adding a brand new session if capacity reached
+  if (!existing && sessions.size >= MAX_SESSIONS) {
+    pruneSessions(now, MAX_SESSIONS - 1, SESSION_TTL_MS)
+  }
+
+  // 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 : now,
+      lastUsedAt: 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,
+    maxSessions: MAX_SESSIONS,
+    sessionTtlMs: SESSION_TTL_MS,
+    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/slash-command.js

@@ -1,5 +1,6 @@
 import { publicConfig, plainConfig, Config } from './config.js'
 import { resolveActiveAccountKey, formatProgressBar } from './provider-sync.js'
+import { resolveAccountPool, rotateToNextAccount, getLastRotation } from './account-pool.js'
 import {
   getAllModels,
   isVisionModel,
@@ -8,8 +9,6 @@ import {
   DEFAULT_MODEL_ID,
 } from './models.js'
 import {
-  resolveAccountPool,
-  rotateToNextAccount,
   probeHealth,
   smokeChat,
   fetchUsageLimits,
@@ -18,7 +17,6 @@ import {
   clearProbeCache,
   usageCache,
   sessionStats,
-  getLastRotation,
 } from './cline-client.js'
 
 export function registerSlashCommand(ctx, { live, getSettingsApi, syncProviderState }) {