@goodandready/dsh-clinebot 0.4.7 → 0.4.8

package/lib/config.js

@@ -12,7 +12,6 @@ import {
   getActiveModelIds,
 } from './models.js'
 
-
 // DSH settings.describe only publishes fields marked volatile. Without them the
 // namespace is omitted and the configuration page stays unavailable.
 if (typeof z.prototype?.volatile !== 'function') {
@@ -58,6 +57,21 @@ export const Config = z.object({
     maxTokens: z.number().default(8192),
   })).default([])
     .description('Custom user-defined model context length and max token overrides.').volatile(),
+  modelReasoningDefaults: z.dict(z.string()).default({})
+    .description('Configured default reasoning effort per model (low, medium, high, max).').volatile(),
+  customModels: z.array(z.object({
+    id: z.string(),
+    name: z.string(),
+    contextLength: z.number().default(128000),
+    maxTokens: z.number().default(8192),
+    category: z.string().default('general'),
+    isReasoning: z.boolean().default(false),
+  })).default([])
+    .description('User-defined custom gateway models.').volatile(),
+  proxyMode: z.boolean().default(true)
+    .description('When true, registers local transparent loopback proxy for failover and token tracking.').volatile(),
+  statsPath: z.string().default('~/.dsh/clinebot-stats.json')
+    .description('Local on-disk persistent path for token usage analytics.').volatile(),
   timeoutMs: z.number().default(DEFAULT_TIMEOUT_MS)
     .description('HTTP probe timeout in milliseconds.').volatile(),
   smokeTimeoutMs: z.number().default(DEFAULT_SMOKE_TIMEOUT_MS)
@@ -73,7 +87,6 @@ export const Config = z.object({
     .description('Manually pinned active account envName or empty for auto/default.').volatile(),
 })
 
-
 function isVolatileRef(value) {
   return !!value && typeof value === 'object' && !Array.isArray(value) && typeof value.get === 'function'
 }
@@ -111,9 +124,10 @@ export function volatileConfig(cfg) {
 export function publicConfig(cfg) {
   cfg = plainConfig(cfg)
   const dynamic = Array.isArray(cfg?.dynamicModels) ? cfg.dynamicModels : []
+  const custom = Array.isArray(cfg?.customModels) ? cfg.customModels : []
   const modelContextOverrides = Array.isArray(cfg?.modelContextOverrides) ? cfg.modelContextOverrides : []
   const isSynced = dynamic.length > 0
-  const allModels = getAllModels(dynamic, modelContextOverrides)
+  const allModels = getAllModels(dynamic, modelContextOverrides, custom)
   const allDefaultIds = allModels.map((m) => m.id)
 
   let disabledList = Array.isArray(cfg?.disabledModels) ? cfg.disabledModels : []
@@ -148,6 +162,10 @@ export function publicConfig(cfg) {
     planSynced: isSynced,
     planSyncedAt,
     modelContextOverrides,
+    modelReasoningDefaults: cfg?.modelReasoningDefaults && typeof cfg.modelReasoningDefaults === 'object' ? cfg.modelReasoningDefaults : {},
+    customModels: custom,
+    proxyMode: cfg?.proxyMode !== false,
+    statsPath: String(cfg?.statsPath || '~/.dsh/clinebot-stats.json'),
     disabledModels: disabledList,
     enabledModels: activeIds,
     timeoutMs: Number(cfg?.timeoutMs) || DEFAULT_TIMEOUT_MS,

package/lib/index.js

@@ -18,7 +18,9 @@ import { registerSettingsRoutes } from './routes/settings.js'
 import { registerAccountsRoutes } from './routes/accounts.js'
 import { registerModelsRoutes } from './routes/models.js'
 import { registerAuthRoutes } from './routes/auth.js'
+import { registerProxyRoutes } from './routes/proxy.js'
 import { registerSlashCommand } from './slash-command.js'
+import { recordUsage } from './stats-storage.js'
 
 export const name = '@goodandready/dsh-clinebot'
 export const inject = ['webServer', 'credentials']
@@ -135,6 +137,7 @@ export function apply(ctx, config) {
     registerAccountsRoutes(ctx, routeEnv)
     registerModelsRoutes(ctx, routeEnv)
     registerAuthRoutes(ctx, routeEnv)
+    registerProxyRoutes(ctx, routeEnv)
   }
 
   registerSlashCommand(ctx, {
@@ -198,6 +201,15 @@ export function apply(ctx, config) {
                   completionTokens,
                   model: options?.model,
                 })
+                recordUsage({
+                  model: options?.model,
+                  promptTokens,
+                  completionTokens,
+                  totalTokens: promptTokens + completionTokens,
+                  isError: true,
+                  is429,
+                  statsPath: live().statsPath,
+                })
                 if (is429 || isExceeded) {
                   handleStream429()
                 }
@@ -218,6 +230,13 @@ export function apply(ctx, config) {
                   completionTokens,
                   model: options?.model,
                 })
+                recordUsage({
+                  model: options?.model,
+                  promptTokens,
+                  completionTokens,
+                  totalTokens: promptTokens + completionTokens,
+                  statsPath: live().statsPath,
+                })
               }
             }
             yield chunk
@@ -230,6 +249,13 @@ export function apply(ctx, config) {
               completionTokens,
               model: options?.model,
             })
+            recordUsage({
+              model: options?.model,
+              promptTokens,
+              completionTokens,
+              totalTokens: promptTokens + completionTokens,
+              statsPath: live().statsPath,
+            })
           }
         } catch (err) {
           if (isCline) {
@@ -244,6 +270,15 @@ export function apply(ctx, config) {
               completionTokens,
               model: options?.model,
             })
+            recordUsage({
+              model: options?.model,
+              promptTokens,
+              completionTokens,
+              totalTokens: promptTokens + completionTokens,
+              isError: true,
+              is429: status === 429,
+              statsPath: live().statsPath,
+            })
             if (status === 429 || isQuotaExceededError(msg)) {
               handleStream429()
             }

package/lib/models.js

@@ -336,7 +336,7 @@ export function parsePlanIncludedModels(includedInput) {
  *
  * Applies user-defined modelContextOverrides (custom contextLength and maxTokens).
  */
-export function getAllModels(dynamicModels = [], modelContextOverrides = []) {
+export function getAllModels(dynamicModels = [], modelContextOverrides = [], customModels = []) {
   const normalizedDynamic = (Array.isArray(dynamicModels) ? dynamicModels : []).map(migrateModelEntry)
   const overridesMap = new Map()
   if (Array.isArray(modelContextOverrides)) {
@@ -374,9 +374,10 @@ export function getAllModels(dynamicModels = [], modelContextOverrides = []) {
     }
   }
 
+  let baseModels = []
   if (normalizedDynamic.length > 0) {
     const normalize = (s) => String(s || '').toLowerCase().replace(/[\s._-]+/g, '')
-    return normalizedDynamic.map((dm) => {
+    baseModels = normalizedDynamic.map((dm) => {
       const targetNorm = normalize(dm.id.replace(/^cline-pass\//, ''))
       const curated = CLINE_MODELS.find(
         (cm) => cm.id === dm.id || normalize(cm.id.replace(/^cline-pass\//, '')) === targetNorm || normalize(cm.name) === targetNorm
@@ -407,23 +408,47 @@ export function getAllModels(dynamicModels = [], modelContextOverrides = []) {
         unverified: false,
       })
     })
+  } else {
+    baseModels = CLINE_MODELS.map((m) => applyOverride({ ...m, unverified: true }))
+  }
+
+  if (Array.isArray(customModels) && customModels.length > 0) {
+    const existingIds = new Set(baseModels.map((m) => m.id))
+    for (const cm of customModels) {
+      if (cm && cm.id && !existingIds.has(cm.id)) {
+        const fullCustom = {
+          id: cm.id,
+          name: cm.name || cm.id,
+          description: cm.description || `Custom model ${cm.name || cm.id}`,
+          contextLength: cm.contextLength || 128000,
+          maxTokens: cm.maxTokens || 8192,
+          input: ['text'],
+          category: cm.category || 'general',
+          isCustom: true,
+          reasoningEfforts: cm.isReasoning ? ['low', 'medium', 'high', 'max'] : undefined,
+          unverified: false,
+        }
+        baseModels.push(applyOverride(fullCustom))
+        existingIds.add(cm.id)
+      }
+    }
   }
 
-  return CLINE_MODELS.map((m) => applyOverride({ ...m, unverified: true }))
+  return baseModels
 }
 
-export function findModel(id, dynamicModels = [], modelContextOverrides = []) {
+export function findModel(id, dynamicModels = [], modelContextOverrides = [], customModels = []) {
   const all = getAllModels(dynamicModels, modelContextOverrides)
   const found = all.find((m) => m.id === id)
   if (found) return found
   return CLINE_MODELS.find((m) => m.id === id) || null
 }
 
-export function isSupportedModel(id, dynamicModels = [], modelContextOverrides = []) {
+export function isSupportedModel(id, dynamicModels = [], modelContextOverrides = [], customModels = []) {
   return findModel(id, dynamicModels, modelContextOverrides) !== null
 }
 
-export function getDefaultModelIds(dynamicModels = [], modelContextOverrides = []) {
+export function getDefaultModelIds(dynamicModels = [], modelContextOverrides = [], customModels = []) {
   return getAllModels(dynamicModels, modelContextOverrides).map((m) => m.id)
 }
 

package/lib/provider-sync.js

@@ -1,30 +1,29 @@
 import os from 'node:os'
 import path from 'node:path'
-import { publicConfig, plainConfig, Config, LLM_PI_AI_NS } from './config.js'
-import { publicUsage } from './http.js'
 import {
   PROVIDER_ID,
   PROVIDER_DISPLAY_NAME,
   getAllModels,
-  loadModelsDiskCache,
   saveModelsDiskCache,
+  loadModelsDiskCache,
+  OBSOLETE_MODEL_ID_MAP,
+  migrateModelEntry,
 } from './models.js'
 import {
-  resolveKeyValue,
-  resolveAccountPool,
   probeHealth,
   fetchUsageLimits,
-  buildPiAiProvider,
   sessionStats,
-  getLastRotation,
   usageCache,
+  buildPiAiProvider,
   DEFAULT_API_KEY_ENV,
 } from './cline-client.js'
+import { publicConfig, plainConfig, Config, LLM_PI_AI_NS } from './config.js'
+import { publicUsage } from './http.js'
+import { resolveKeyValue } from './credential-refs.js'
+import { resolveAccountPool, getLastRotation } from './account-pool.js'
 
 export function resolvePathWithHome(p) {
-  if (!p || typeof p !== 'string') return ''
-  if (p === '~') return os.homedir()
-  if (p.startsWith('~/') || p.startsWith('~\\')) {
+  if (typeof p === 'string' && p.startsWith('~/')) {
     return path.join(os.homedir(), p.slice(2))
   }
   return p
@@ -88,7 +87,7 @@ export async function buildStatus(ctx, cfg) {
   ])
 
   const activeAcc = await resolveActiveAccountKey(ctx, cfg, pool)
-  const allModels = getAllModels(pub.dynamicModels, pub.modelContextOverrides)
+  const allModels = getAllModels(pub.dynamicModels, pub.modelContextOverrides, pub.customModels)
 
   let usage = null
   const keyToUse = activeAcc.value || key.value
@@ -97,19 +96,40 @@ export async function buildStatus(ctx, cfg) {
   }
 
   let quotaWarning = null
-  if (usage?.windows?.fiveHour) {
-    const pct = usage.windows.fiveHour.percentUsed
-    if (pct >= 95) {
+  if (usage?.windows) {
+    const fiveHour = usage.windows.fiveHour
+    const weekly = usage.windows.weekly
+    const monthly = usage.windows.monthly
+
+    if (fiveHour && typeof fiveHour.percentUsed === 'number') {
+      if (fiveHour.percentUsed >= 95) {
+        quotaWarning = {
+          level: 'exhausted',
+          message: `5-hour rolling limit is almost exhausted (${fiveHour.percentUsed}%). New requests may be rejected until quota reset.`,
+          resetsAt: fiveHour.resetsAt,
+        }
+      } else if (fiveHour.percentUsed >= 90) {
+        quotaWarning = {
+          level: 'warning',
+          message: `Low quota warning: ${fiveHour.percentUsed}% of 5-hour limit consumed (<10% remaining).`,
+          resetsAt: fiveHour.resetsAt,
+        }
+      }
+    }
+
+    if (!quotaWarning && weekly && typeof weekly.percentUsed === 'number' && weekly.percentUsed >= 90) {
       quotaWarning = {
-        level: 'exhausted',
-        message: `5-hour rolling limit is almost exhausted (${pct}%). New requests may be rejected until quota reset.`,
-        resetsAt: usage.windows.fiveHour.resetsAt,
+        level: weekly.percentUsed >= 99 ? 'exhausted' : 'warning',
+        message: `Low weekly quota warning: ${weekly.percentUsed}% consumed (${weekly.remainingPercent ?? (100 - weekly.percentUsed)}% remaining).`,
+        resetsAt: weekly.resetsAt,
       }
-    } else if (pct >= 80) {
+    }
+
+    if (!quotaWarning && monthly && typeof monthly.percentUsed === 'number' && monthly.percentUsed >= 90) {
       quotaWarning = {
-        level: 'warning',
-        message: `Notice: ${pct}% of the 5-hour rolling limit has been consumed.`,
-        resetsAt: usage.windows.fiveHour.resetsAt,
+        level: monthly.percentUsed >= 99 ? 'exhausted' : 'warning',
+        message: `Low monthly quota warning: ${monthly.percentUsed}% consumed (${monthly.remainingPercent ?? (100 - monthly.percentUsed)}% remaining).`,
+        resetsAt: monthly.resetsAt,
       }
     }
   }
@@ -127,7 +147,7 @@ export async function buildStatus(ctx, cfg) {
     accounts: pool.map((acc) => {
       const cacheKey = `cline:usage:${(acc.value || '').slice(-8)}`
       const cached = usageCache.get(cacheKey)?.data
-      const pct = cached?.windows?.fiveHour?.percentUsed
+      const pct = cached?.windows?.weekly?.percentUsed ?? cached?.windows?.monthly?.percentUsed ?? cached?.windows?.fiveHour?.percentUsed ?? null
       return {
         id: acc.id,
         label: acc.label,
@@ -156,17 +176,22 @@ export async function upsertPiAiProvider(ctx, cfg, activeModelIds) {
   }
 
   const pub = publicConfig(cfg)
-  const allModels = getAllModels(pub.dynamicModels, pub.modelContextOverrides)
+  const allModels = getAllModels(pub.dynamicModels, pub.modelContextOverrides, pub.customModels)
   const allowedSet = new Set(activeModelIds || pub.enabledModels)
   const modelsToRegister = allModels.filter((m) => allowedSet.has(m.id))
 
   const activeAcc = await resolveActiveAccountKey(ctx, cfg)
 
+  const port = ctx?.webServer?.port || process.env.PORT || 3080
+  const effectiveBaseUrl = pub.proxyMode !== false
+    ? `http://127.0.0.1:${port}/dsh-clinebot/v1`
+    : pub.baseUrl
+
   const providerObj = buildPiAiProvider({
-    baseUrl: pub.baseUrl,
+    baseUrl: effectiveBaseUrl,
     apiKeyEnv: activeAcc?.apiKeyEnv || pub.apiKeyEnv,
     models: modelsToRegister.length ? modelsToRegister : allModels,
-    customModels: pub.dynamicModels,
+    customModels: [...(pub.dynamicModels || []), ...(pub.customModels || [])],
     displayName: PROVIDER_DISPLAY_NAME,
   })
 

package/lib/routes/proxy.js

@@ -0,0 +1,262 @@
+/**
+ * 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 } 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 } 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' })
+      }
+
+      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()
+
+      // Inject model reasoning effort if model has default configured and payload omitted it
+      if (
+        pub.modelReasoningDefaults &&
+        body.model &&
+        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.4.8'
+        }
+
+        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')
+
+          try {
+            while (true) {
+              const { done, value } = await reader.read()
+              if (done) 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) {
+            ctx?.logger?.warn?.(`[dsh-clinebot:proxy] Error streaming SSE chunk: ${streamErr?.message || streamErr}`)
+          } finally {
+            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' })
+      }
+      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')
 }