@goodandready/dsh-clinebot 0.3.6 → 0.3.8

package/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to `@goodandready/dsh-clinebot` will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.8] - 2026-09-12
+
+### Added
+- **Stale-While-Revalidate (SWR) Network Probe** (Issue #18): Introduced in-memory SWR caching (`probeCache`) with 25s TTL for host health probes (`probeHealth`), reducing settings card status endpoint latency from ~500ms to <1ms on repeated calls while revalidating asynchronously in the background.
+- **HTTP Keep-Alive Connection Reuse**: Added persistent `keepalive: true` connection options across all HTTP calls (`probeHealth`, `smokeChat`, `fetchUsageLimits`) to eliminate recurrent TCP/TLS handshakes to `api.cline.bot`.
+- **Auto-Failover Account Rotation**: Implemented `rotateToNextAccount` to automatically rotate active accounts in the configured pool when encountering HTTP 429 rate limits or 100% quota exhaustion, instantly synchronizing DSH `llm-pi-ai` credentials without restarting.
+- **Accurate Token Telemetry**: Extracted real usage metrics (`prompt_tokens`, `completion_tokens`, `total_tokens`) from chat completion responses, replacing static estimation counters.
+- **Expanded Slash-Commands**: Extended `/cline` chat command with `/cline test [model]` (live smoke verification), `/cline ping` (real-time host connectivity test), and `/cline rotate` (manual failover).
+- **Curated Models Catalog Expansion**: Added Claude 3.7 Sonnet (Hybrid Reasoning), GPT-4.5 Preview, o3-mini, Gemini 2.5 Pro / Flash, and Qwen 2.5 Coder 32B to the official `CLINE_MODELS` catalogue.
+- **Debounced Model Picker Toggles**: Added 280ms debounce for model exclusion persistence in `lib/client.js`, providing 0ms UI checkbox responsiveness and preventing network request thrashing.
+
+## [0.3.7] - 2026-09-10
+
+### Fixed
+- **Canonical Settings Namespace Registration** (Issue #16): Moved settings declaration in `lib/index.js` to `ctx.inject(['settings'], (sctx) => { sctx.settings.register(NS, Config, { base: config }) })`, guaranteeing synchronous/asynchronous namespace availability and reactive config watching via `live()`.
+- **Top-Level Section Removal**: Removed the unauthorized fallback to `settings.section` in `lib/client.js`, strictly confining the plugin UI to the standard `settings.plugin.item` slot under Settings → Plugins → Plugin Settings.
+- **Safe Service Resolution**: Replaced direct property access `ctx.credentials` with safe proxy lookup `(ctx?.get && ctx.get('credentials')) || ctx?.credentials`.
+- **Client Mirror Invalidation & Scope Sync**: Added `refreshMirrorUntilVisible(ctx)` in `lib/client.js` to trigger settings mirror re-reads until the namespace is visible in the web client, and synchronized multi-account changes directly through `scope.set('activeAccount', accountEnv)`.
+- **Duplicate-Safe Locales**: Wrapped client dictionary registration with duplicate-safe guards (`ctx.locale.register()`) preventing registration collision errors.
+
 ## [0.3.6] - 2026-09-09
 
 ### Fixed

package/docs/design/DESIGN.md

@@ -7,17 +7,19 @@
 The plugin consists of two runtime boundaries conforming to DSH authoring standards:
 
 ### 2.1 Host Runtime (`lib/index.js`, `lib/cline-client.js`, `lib/models.js`, `lib/http.js`)
-* **Cordis Service Registration**: Injects `['settings', 'webServer', 'credentials']`.
-* **Credential Isolation**: The plugin NEVER stores plain API keys in its configuration. The setting `apiKeyEnv` holds the credential identifier (default: `CLINEBOT_API_KEY`), resolved via `ctx.credentials.resolve()` or `process.env`.
+* **Cordis Service Registration**: Declares `inject = ['settings', 'webServer', 'credentials']` and registers the settings namespace dynamically via `ctx.inject(['settings'], (sctx) => { sctx.settings.register(NS, Config, { base: config }) })`. This guarantees that the configuration schema, default values, and reactive watchers are declared and available to the host and client settingsScope without timing issues.
+* **Safe Service Resolution**: Service lookups utilize defensive proxy resolution `(ctx?.get && ctx.get('credentials')) || ctx?.credentials` to prevent `undefined` properties on Cordis proxies.
+* **Credential Isolation**: The plugin NEVER stores plain API keys in its configuration. The setting `apiKeyEnv` holds the credential identifier (default: `CLINEBOT_API_KEY`), resolved via `ctx.get('credentials').resolve()` or `process.env`.
 * **State Synchronization & Auto-Registration**: Mutates the core `llm-pi-ai` settings space (`op: 'set', path: ['providers', 'clinebot']`) declaratively and automatically when enabled or key is saved.
 * **Auto-Discovery & `disabledModels`**: Features automatic background polling of subscription plan models (`GET /api/v1/users/me/plan`). User preferences are tracked via `disabledModels: []`, ensuring newly added plan models appear enabled by default in the DSH chat picker without manual re-synchronization.
 
 ### 2.2 Client Runtime (`lib/client.js`)
 * Self-registering module via `window.__ModuleLoader__.load({ id: '@goodandready/dsh-clinebot', factory })`.
 * Injects `['slots', 'locale', 'settingsScope']`.
-* Slots into `settings.plugin.item` (primary) with `key: NS` and `locale: NS`, and graceful fallback to `settings.section` if not declared.
-* Registers localized `en` and `ru` dictionaries via `ctx.locale.register()`.
-* Reactive binding via `ctx.settingsScope.bind({ namespace: NS })` with `useSyncExternalStore` guarding against `unavailable` / `loading` snapshot states.
+* Slots strictly and exclusively into `settings.plugin.item` (`key: NS`, `locale: NS`). Standalone top-level `settings.section` registration is omitted to maintain clean primary navigation in DSH and prevent side-list pollution.
+* Uses `refreshMirrorUntilVisible(ctx)` to invalidate and re-read the client settings mirror until the namespace is reported ready by the host.
+* Registers localized `en` and `ru` dictionaries with duplicate-safe guards (`ctx.locale.register()`).
+* Reactive binding via `((ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope).bind({ namespace: NS })` with `useSyncExternalStore` guarding against `unavailable` / `loading` snapshot states. Form mutations write directly to `scope.set()`.
 * Uses native design tokens (`--dsw-alias-...`) with full dark/light theme support.
 * Injects isolated style tag tagged with `data-dsh-plugin="dsh-clinebot"`.
 
@@ -70,3 +72,11 @@ graph LR
 * **Reasoning Effort Support**: Models declaring `reasoningEfforts: ['low', 'medium', 'high', 'max']` expose native thinking controls within the DSH model picker, accompanied by UI badges (`🧠 Reasoning`).
 * **Offline Cold-Start Cache**: Discovered plan models are serialized locally to `modelsCachePath` (`~/.dsh/clinebot-models-cache.json`), ensuring models remain immediately available on cold boot even if the upstream network or Cline API is temporarily unavailable.
 
+
+## 6. Performance, Resilience & Telemetry (v0.3.8)
+* **Stale-While-Revalidate (SWR) Network Probing**: `probeHealth()` utilizes an in-memory SWR cache (`probeCache`) with 25s TTL. Repeated `/status` queries return instantaneously (<1ms latency) with fresh host availability, asynchronously refreshing network latency in the background without blocking the client UI thread.
+* **HTTP Keep-Alive Connection Reuse**: Outbound fetch calls to `api.cline.bot` enforce persistent connection keepalive (`keepalive: true`), eliminating recurrent TLS handshake and TCP connection establishment latency.
+* **Auto-Failover Account Rotation**: When an active account encounters HTTP 429 (Rate Limit) or 100% quota depletion, `rotateToNextAccount()` automatically selects the next configured account in the pool, applies the update to DSH settings, and re-synchronizes credentials in `llm-pi-ai` in real time.
+* **Accurate Token Telemetry**: Real usage metadata (`prompt_tokens`, `completion_tokens`, `total_tokens`) is parsed directly from chat completion responses and tracked in session telemetry (`sessionStats`).
+* **Expanded Slash Commands**: Slash command `/cline` supports `/cline test [model]` (smoke test with latency, response and token metrics), `/cline ping` (real-time host connectivity test), and `/cline rotate` (round-robin active account rotation).
+* **Debounced Model Selection**: Model exclusion checkboxes in `lib/client.js` utilize immediate optimistic UI rendering paired with a 280ms debounced persistence layer, ensuring smooth interaction without request thrashing.

package/lib/client.js

@@ -1,5 +1,4 @@
-// Dedicated Settings Page: Settings → ClineBot (settings.section)
-// & Plugin Card (settings.plugin.item).
+// Plugin Settings Card (settings.plugin.item).
 window.__ModuleLoader__.load({
   id: '@goodandready/dsh-clinebot',
   factory: (require) => {
@@ -357,9 +356,10 @@ window.__ModuleLoader__.load({
       const t = props?.t || makeT(ru, en)
 
       const scope = React.useMemo(() => {
-        if (!ctx?.settingsScope?.bind) return undefined
+        const s = (ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope
+        if (!s?.bind) return undefined
         try {
-          return ctx.settingsScope.bind({ namespace: NS })
+          return s.bind({ namespace: NS })
         } catch (_) {
           return undefined
         }
@@ -377,11 +377,11 @@ window.__ModuleLoader__.load({
       }, [scope])
 
       const getSnapshot = React.useCallback(() => {
-        if (!scope?.getSnapshot) return SNAPSHOT_READY
+        if (!scope?.getSnapshot) return SNAPSHOT_LOADING
         try {
-          return scope.getSnapshot() || SNAPSHOT_READY
+          return scope.getSnapshot() || SNAPSHOT_LOADING
         } catch (_) {
-          return SNAPSHOT_READY
+          return SNAPSHOT_LOADING
         }
       }, [scope])
 
@@ -390,7 +390,7 @@ window.__ModuleLoader__.load({
         getSnapshot,
         React.useCallback(() => SNAPSHOT_LOADING, [])
       )
-      const snapshotStatus = snapshot?.status || 'ready'
+      const snapshotStatus = snapshot?.status || 'loading'
 
       const [status, setStatus] = React.useState(null)
       const [draft, setDraft] = React.useState(null)
@@ -420,6 +420,12 @@ window.__ModuleLoader__.load({
         load().catch((e) => setErr(String(e.message || e)))
       }, [load])
 
+      React.useEffect(() => {
+        if (snapshotStatus === 'ready' && snapshot?.value && typeof snapshot.value === 'object') {
+          setDraft((prev) => (prev ? { ...prev, ...snapshot.value } : snapshot.value))
+        }
+      }, [snapshotStatus, snapshot?.value])
+
       // Save Key handler
       async function handleSaveKey() {
         if (!apiKeyInput.trim()) {
@@ -570,6 +576,9 @@ window.__ModuleLoader__.load({
 
       // Pin active account
       async function handlePinAccount(accountEnv) {
+        if (scope && snapshotStatus === "ready") {
+          try { await scope.set("activeAccount", accountEnv) } catch (_) {}
+        }
         setBusy(`pin-${accountEnv}`)
         setErr('')
         try {
@@ -588,8 +597,33 @@ window.__ModuleLoader__.load({
         }
       }
 
-      // Toggle model exclusion (disabledModels logic)
-      async function handleToggleModel(id) {
+      // Debounced persistence for model exclusion to avoid stuttering and request thrashing
+      const debounceTimerRef = typeof React.useRef === 'function' ? React.useRef(null) : { current: null }
+
+      React.useEffect(() => {
+        return () => {
+          if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current)
+        }
+      }, [])
+
+      function debounceSaveDisabledModels(nextDisabled) {
+        if (debounceTimerRef.current) clearTimeout(debounceTimerRef.current)
+        debounceTimerRef.current = setTimeout(async () => {
+          if (scope && snapshotStatus === 'ready') {
+            try { await scope.set('disabledModels', nextDisabled) } catch (_) {}
+          }
+          try {
+            await fetch(`${ROUTE_PREFIX}/models/toggle`, {
+              method: 'POST',
+              headers: { 'Content-Type': 'application/json' },
+              body: JSON.stringify({ disabledModels: nextDisabled }),
+            })
+          } catch {}
+        }, 280)
+      }
+
+      // Toggle model exclusion (disabledModels logic) with instant UI state update & debounced network persist
+      function handleToggleModel(id) {
         if (!draft) return
         const currentDisabled = new Set(draft.disabledModels || [])
         if (currentDisabled.has(id)) {
@@ -604,21 +638,11 @@ window.__ModuleLoader__.load({
         const nextEnabled = allIds.filter((mId) => !currentDisabled.has(mId))
 
         setDraft({ ...draft, disabledModels: nextDisabled, enabledModels: nextEnabled })
-
-        if (scope && snapshotStatus === 'ready') {
-          try { await scope.set('disabledModels', nextDisabled) } catch (_) {}
-        }
-        try {
-          await fetch(`${ROUTE_PREFIX}/models/toggle`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ disabledModels: nextDisabled }),
-          })
-        } catch {}
+        debounceSaveDisabledModels(nextDisabled)
       }
 
-      // Select all / filter models
-      async function handleSetModelsFilter(type) {
+      // Select all / filter models with instant UI state update & debounced network persist
+      function handleSetModelsFilter(type) {
         if (!status?.availableModels) return
         const all = status.availableModels
         let allowed = new Set()
@@ -636,16 +660,7 @@ window.__ModuleLoader__.load({
         const nextEnabled = Array.from(allowed)
 
         setDraft({ ...draft, disabledModels: nextDisabled, enabledModels: nextEnabled })
-        if (scope && snapshotStatus === 'ready') {
-          try { await scope.set('disabledModels', nextDisabled) } catch (_) {}
-        }
-        try {
-          await fetch(`${ROUTE_PREFIX}/models/toggle`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ disabledModels: nextDisabled }),
-          })
-        } catch {}
+        debounceSaveDisabledModels(nextDisabled)
       }
 
       if (snapshotStatus === 'unavailable') {
@@ -1212,49 +1227,92 @@ window.__ModuleLoader__.load({
       )
     }
 
+    function refreshMirrorUntilVisible(ctx) {
+      const visible = () => {
+        try {
+          const s = (ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope
+          const view = s?.describe?.()?.getSnapshot?.()?.view
+          return !!view && Array.isArray(view.namespaces) && view.namespaces.some((row) => row.ns === NS)
+        } catch (_) {
+          return false
+        }
+      }
+      if (visible()) return () => {}
+      let tries = 0
+      const timer = setInterval(() => {
+        if (visible() || tries >= 15) { clearInterval(timer); return }
+        tries += 1
+        try {
+          const s = (ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope
+          s?.describe?.()?.load?.()
+        } catch (_) {}
+      }, 1000)
+      return () => clearInterval(timer)
+    }
+
     function apply(ctx) {
+      const addLocale = (locale, dictionary) => {
+        try {
+          return ctx.locale.register(NS, locale, dictionary)
+        } catch (_) {
+          return () => {}
+        }
+      }
       if (ctx.locale && ctx.locale.register) {
-        try { ctx.locale.register(NS, { en, ru }) } catch (_) {}
+        if (typeof ctx.effect === 'function') {
+          ctx.effect(() => {
+            const undo = [addLocale('en', en), addLocale('ru', ru)]
+            return () => { for (const off of undo) off() }
+          }, 'dsh-clinebot: dictionaries')
+        } else {
+          addLocale('en', en)
+          addLocale('ru', ru)
+        }
       }
-      const t = (ctx.locale && ctx.locale.bind) ? ctx.locale.bind(NS) : makeT(ru, en)
 
-      let placed = false
-      try {
-        const res = ctx.slots.inject('settings.plugin.item', () => {
-          placed = true
-          return ctx.slots.register(
-            {
-              name: 'settings.plugin.item',
-              key: NS,
-              locale: NS,
-              inject: () => ({ ctx }),
-            },
-            (props) => React.createElement(ErrorBoundary, null, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
-          )
-        })
-        if (res === null) placed = false
-      } catch (_) {
-        placed = false
+      if (typeof ctx.effect === 'function') {
+        ctx.effect(
+          () => refreshMirrorUntilVisible(ctx),
+          'dsh-clinebot: re-read the settings mirror until our namespace appears',
+        )
       }
 
-      // Fallback to settings.section if settings.plugin.item is not declared
-      if (!placed) {
-        try {
-          ctx.slots.inject('settings.section', () => {
-            return ctx.slots.register(
-              {
-                name: 'settings.section',
-                id: '@goodandready/dsh-clinebot',
-                order: 28,
-                locale: NS,
-                label: () => t('title'),
-                inject: () => ({ ctx }),
-              },
-              (props) => React.createElement(ErrorBoundary, null, React.createElement(SettingsPage, { ...props, ctx: (props && props.ctx) || ctx }))
-            )
-          })
-        } catch (_) {}
+      function registerSlotWhenReady(slotName, registerFn) {
+        if (!ctx.slots) return
+        if (typeof ctx.slots.inject === 'function') {
+          try {
+            ctx.slots.inject(slotName, () => {
+              try {
+                return registerFn()
+              } catch (err) {
+                console.warn('[dsh-clinebot] Error registering slot ' + slotName + ':', err)
+              }
+            })
+            return
+          } catch (err) {
+            console.warn('[dsh-clinebot] Failed to inject slot ' + slotName + ':', err)
+          }
+        }
+        if (typeof ctx.slots.register === 'function') {
+          try {
+            registerFn()
+          } catch (err) {
+            console.warn('[dsh-clinebot] Failed direct registration for ' + slotName + ':', err)
+          }
+        }
       }
+
+      registerSlotWhenReady('settings.plugin.item', () =>
+        ctx.slots.register(
+          {
+            name: 'settings.plugin.item',
+            key: NS,
+            locale: NS,
+            inject: () => ({ ctx }),
+          },
+          (props) => React.createElement(ErrorBoundary, null, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
+        )
+      )
     }
 
     module.exports = { apply, inject: ['slots', 'locale', 'settingsScope'] }

package/lib/cline-client.js

@@ -132,6 +132,12 @@ function abortAfter(ms) {
 
 // In-memory cache for quota queries to avoid hammering the ClinePass endpoint
 const usageCache = new Map()
+export const probeCache = new Map()
+
+export function clearProbeCache() {
+  probeCache.clear()
+}
+
 export function clearUsageCache() {
   usageCache.clear()
 }
@@ -309,34 +315,65 @@ export async function fetchUsageLimits(baseUrl, apiKey, {
 }
 
 /**
- * Quick network probe to verify server availability.
+ * Quick network probe to verify server availability with Stale-While-Revalidate caching.
  */
-export async function probeHealth(baseUrl, { timeoutMs = DEFAULT_TIMEOUT_MS, fetchImpl = fetch } = {}) {
+export async function probeHealth(baseUrl, {
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  fetchImpl = fetch,
+  bypassCache = false,
+  ttlMs = 25000,
+} = {}) {
   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}`,
+  const cacheKey = `probe:${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 () => {
+        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()
+    // Stale-While-Revalidate: trigger async refresh and return stale snapshot immediately
+    if (!cached.isRevalidating) {
+      cached.isRevalidating = true
+      doProbe().catch(() => {})
+    }
+    return cached.data
   }
+
+  return doProbe()
 }
 
 /**
@@ -368,6 +405,7 @@ export async function smokeChat(baseUrl, apiKey, {
         stream: false,
       }),
       signal,
+      keepalive: true,
     })
 
     const latencyMs = Date.now() - start
@@ -385,12 +423,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 +490,105 @@ export function buildPiAiProvider({
     models: modelList,
   }
 }
+
+/**
+ * Safely resolve key value from DSH credentials 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
+}
+
+/**
+ * Rotate active account to next available configured account upon rate-limiting (429) or quota exhaustion.
+ */
+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)
+  const nextIndex = (currentIndex + 1) % configured.length
+  const nextAcc = configured[nextIndex]
+
+  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,
+  }
+}

package/lib/index.js

@@ -122,9 +122,10 @@ function resolvePathWithHome(p) {
 
 async function resolveKeyValue(ctx, apiKeyEnv) {
   const refName = String(apiKeyEnv || DEFAULT_API_KEY_ENV).trim() || DEFAULT_API_KEY_ENV
-  if (ctx?.credentials && typeof ctx.credentials.resolve === 'function') {
+  const creds = (ctx?.get && ctx.get('credentials')) || ctx?.credentials
+  if (creds && typeof creds.resolve === 'function') {
     try {
-      const hit = await ctx.credentials.resolve(credentialRef(refName))
+      const hit = await creds.resolve(credentialRef(refName))
       if (hit?.value) {
         return { envName: refName, value: hit.value, source: 'credentials' }
       }
@@ -204,19 +205,70 @@ async function checkRegisteredInPiAi(ctx) {
   }
 }
 
+/**
+ * Rotate active account to next available configured account upon rate-limiting (429) or quota exhaustion.
+ */
+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 pub = publicConfig(cfg)
+  const currentEnv = pub.activeAccount || configured[0].apiKeyEnv
+  const currentIndex = configured.findIndex((acc) => acc.apiKeyEnv === currentEnv)
+  const nextIndex = (currentIndex + 1) % configured.length
+  const nextAcc = configured[nextIndex]
+
+  let updated = false
+  if (settingsApi?.replace) {
+    try {
+      const next = Config({ ...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(NS, [
+          { op: 'set', path: ['activeAccount'], value: nextAcc.apiKeyEnv },
+        ])
+        updated = true
+      } catch {}
+    }
+  }
+
+  return {
+    rotated: true,
+    previousAccount: currentEnv,
+    activeAccount: nextAcc.apiKeyEnv,
+    reason,
+    updatedSettings: updated,
+  }
+}
+
 async function buildStatus(ctx, cfg) {
   const pub = publicConfig(cfg)
-  const key = await resolveKeyValue(ctx, pub.apiKeyEnv)
-  // Non-blocking quick health probe with low timeout so settings page loads instantly
   const probeTimeout = Math.min(2500, pub.timeoutMs || 2500)
-  const health = await probeHealth(pub.baseUrl, { timeoutMs: probeTimeout })
-  const isRegistered = await checkRegisteredInPiAi(ctx)
+
+  // Concurrent resolution of keys, health probe (SWR cached), accounts pool and DSH registration
+  const [key, pool, isRegistered, health] = await Promise.all([
+    resolveKeyValue(ctx, pub.apiKeyEnv),
+    resolveAccountPool(ctx, cfg),
+    checkRegisteredInPiAi(ctx),
+    probeHealth(pub.baseUrl, { timeoutMs: probeTimeout }),
+  ])
+
+  const activeAcc = await resolveActiveAccountKey(ctx, cfg)
   const allModels = getAllModels(pub.dynamicModels)
 
   let usage = null
-  if (key.value) {
+  const keyToUse = activeAcc.value || key.value
+  if (keyToUse) {
     // Uses 60s cache; if cache miss, times out quickly
-    usage = await fetchUsageLimits(pub.baseUrl, key.value, { timeoutMs: probeTimeout }).catch(() => null)
+    usage = await fetchUsageLimits(pub.baseUrl, keyToUse, { timeoutMs: probeTimeout }).catch(() => null)
   }
 
   // Evaluate warning state
@@ -238,10 +290,6 @@ async function buildStatus(ctx, cfg) {
     }
   }
 
-  // Resolve all accounts in pool
-  const pool = await resolveAccountPool(ctx, cfg)
-  const activeAcc = await resolveActiveAccountKey(ctx, cfg)
-
   return {
     ok: true,
     providerId: PROVIDER_ID,
@@ -323,7 +371,8 @@ function formatProgressBar(pct, totalWidth = 10) {
 }
 
 export function apply(ctx, config) {
-  let liveCfg = Config(structuredClone(config || {}))
+  let getConfig = () => config
+  const live = () => (getConfig() ? Config(structuredClone(getConfig())) : config)
   let settingsApi
 
   // Declarative sync helper: auto-registers or unregisters provider based on config & key availability
@@ -355,7 +404,7 @@ export function apply(ctx, config) {
       if ((!pub.dynamicModels || !pub.dynamicModels.length) && cacheFile) {
         const fromDisk = await loadModelsDiskCache(cacheFile)
         if (Array.isArray(fromDisk) && fromDisk.length && settingsApi?.replace) {
-          const next = Config({ ...liveCfg, dynamicModels: fromDisk })
+          const next = Config({ ...live(), dynamicModels: fromDisk })
           await settingsApi.replace(next)
           await syncProviderState(next)
         }
@@ -376,7 +425,7 @@ export function apply(ctx, config) {
 
         if (hasNew && settingsApi?.replace) {
           const next = Config({
-            ...liveCfg,
+            ...live(),
             dynamicModels: usageData.dynamicModels,
           })
           await settingsApi.replace(next)
@@ -391,23 +440,37 @@ export function apply(ctx, config) {
     }
   }
 
-  const settingsService = ctx.get('settings')
-  if (typeof settingsService?.register === 'function') {
-    const scope = settingsService.register(NS, Config, { base: config })
-    settingsApi = scope
-    liveCfg = Config(scope.get() ?? config)
-    ctx.effect(() => scope.watch((next) => {
-      liveCfg = Config(next ?? config)
-      syncProviderState(liveCfg)
-    }), 'dsh-clinebot: settings')
+  if (typeof ctx.inject === 'function') {
+    ctx.inject(['settings'], (sctx) => {
+      const scope = sctx.settings.register(NS, Config, { base: config })
+      settingsApi = scope
+      getConfig = () => (scope?.get?.() ?? config) ?? config
+      sctx.effect(() => scope.watch((next) => {
+        syncProviderState(live())
+      }), 'dsh-clinebot: settings')
+      sctx.effect(() => () => {
+        getConfig = () => config
+        settingsApi = undefined
+      })
+    })
+  } else {
+    const settingsService = (ctx?.get && ctx.get('settings')) || ctx?.settings
+    if (typeof settingsService?.register === 'function') {
+      const scope = settingsService.register(NS, Config, { base: config })
+      settingsApi = scope
+      getConfig = () => (scope?.get?.() ?? config) ?? config
+      if (typeof ctx.effect === 'function') {
+        ctx.effect(() => scope.watch((next) => {
+          syncProviderState(live())
+        }), 'dsh-clinebot: settings')
+      }
+    }
   }
 
-  const live = () => liveCfg
-
   // On startup: ensure provider is synced to llm-pi-ai if key is present
-  syncProviderState(liveCfg)
+  syncProviderState(live())
   // Background discover plan models on startup
-  setTimeout(() => autoDiscoverPlanModels(liveCfg), 500)
+  setTimeout(() => autoDiscoverPlanModels(live()), 500)
 
   // Web server HTTP route handlers
   if (ctx.webServer?.register) {
@@ -602,10 +665,19 @@ export function apply(ctx, config) {
             latencyMs: outcome.latencyMs,
             ok: outcome.ok,
             error: outcome.error,
-            promptTokens: 5,
-            completionTokens: 10,
+            promptTokens: outcome.promptTokens || 5,
+            completionTokens: outcome.completionTokens || 10,
           })
-          writeJson(res, outcome.ok ? 200 : 502, outcome)
+
+          let failover = null
+          if (outcome.status === 429) {
+            failover = await rotateToNextAccount(ctx, live(), 'smoke_429', settingsApi)
+            if (failover.rotated) {
+              await syncProviderState(live())
+            }
+          }
+
+          writeJson(res, outcome.ok ? 200 : 502, { ...outcome, failover })
         } catch (err) {
           recordSessionRequest({ ok: false, error: String(err?.message || err) })
           writeJson(res, 500, { ok: false, error: String(err?.message || err) })
@@ -786,7 +858,7 @@ export function apply(ctx, config) {
 
     const unregister = commands.register({
       name: 'cline',
-      description: 'Check ClinePass subscription quota, models, accounts and session stats (/cline [quota|models|accounts|switch <name>])',
+      description: 'Check ClinePass subscription quota, models, accounts and test connectivity (/cline [quota|models|accounts|switch <name>|test [model]|ping|rotate])',
       execute: async (rawArgs) => {
         const pub = publicConfig(live())
         const subcmd = String(rawArgs || '').trim().toLowerCase().split(/\s+/)[0] || 'quota'
@@ -841,6 +913,65 @@ export function apply(ctx, config) {
           return `⚠️ Не удалось применить настройку (сервис настроек недоступен).`
         }
 
+        // 4. Subcommand /cline rotate (auto-failover next)
+        if (subcmd === 'rotate') {
+          const res = await rotateToNextAccount(ctx, live(), 'slash_command', settingsApi)
+          if (res.rotated) {
+            await syncProviderState(live())
+            return `🔄 **Ротация аккаунта**: переключено с \`${res.previousAccount}\` на \`${res.activeAccount}\`. Провайдер DSH обновлён!`
+          }
+          return `⚠️ Ротация не выполнена: ${res.message || 'нет доступных альтернативных аккаунтов в пуле'}.`
+        }
+
+        // 5. Subcommand /cline ping (fresh host reachability probe)
+        if (subcmd === 'ping') {
+          const health = await probeHealth(pub.baseUrl, { bypassCache: true, timeoutMs: 5000 })
+          if (health.ok) {
+            return `🏓 **Cline API Pong**: \`${pub.baseUrl}\` доступен (задержка: **${health.latencyMs} мс**, HTTP ${health.status})`
+          }
+          return `❌ **Cline API Ping Failed**: ${health.error || 'Хост недоступен'}`
+        }
+
+        // 6. Subcommand /cline test [model]
+        if (subcmd === 'test' || subcmd === 'smoke') {
+          const activeKey = await resolveActiveAccountKey(ctx, live())
+          if (!activeKey.value) {
+            return '⚠️ **ClineBot**: API-ключ не настроен. Откройте **Настройки → ClineBot**.'
+          }
+          const modelToTest = param || pub.defaultModel || DEFAULT_MODEL_ID
+          const outcome = await smokeChat(pub.baseUrl, activeKey.value, {
+            model: modelToTest,
+            timeoutMs: pub.smokeTimeoutMs,
+          })
+          recordSessionRequest({
+            latencyMs: outcome.latencyMs,
+            ok: outcome.ok,
+            error: outcome.error,
+            promptTokens: outcome.promptTokens || 5,
+            completionTokens: outcome.completionTokens || 10,
+          })
+
+          let failoverNotice = ''
+          if (outcome.status === 429) {
+            const failover = await rotateToNextAccount(ctx, live(), 'smoke_429', settingsApi)
+            if (failover.rotated) {
+              await syncProviderState(live())
+              failoverNotice = `
+🔄 **Auto-failover**: Обнаружен HTTP 429! Активный аккаунт автоматически переключен на \`${failover.activeAccount}\`.`
+            }
+          }
+
+          if (outcome.ok) {
+            return [
+              `### 🟢 Smoke Test Успешен: \`${outcome.model}\``,
+              `* **Задержка**: ${outcome.latencyMs} мс`,
+              `* **Токены**: prompt: ${outcome.promptTokens}, completion: ${outcome.completionTokens} (всего: ${outcome.totalTokens})`,
+              `* **Превью**: _"${outcome.preview}"_`,
+            ].join('\n')
+          }
+          return `❌ **Smoke Test Ошибка**: ${outcome.error} (HTTP ${outcome.status || 'timeout'})${failoverNotice}`
+        }
+
         // 4. Default /cline quota
         const activeKey = await resolveActiveAccountKey(ctx, live())
         if (!activeKey.value) {
@@ -901,15 +1032,21 @@ export function apply(ctx, config) {
     },
     runSmokeTest: async (model) => {
       const pub = publicConfig(live())
-      const key = await resolveKeyValue(ctx, pub.apiKeyEnv)
-      const res = await smokeChat(pub.baseUrl, key.value, { model: model || pub.defaultModel })
+      const activeKey = await resolveActiveAccountKey(ctx, live())
+      const res = await smokeChat(pub.baseUrl, activeKey.value, { model: model || pub.defaultModel })
       recordSessionRequest({
         latencyMs: res.latencyMs,
         ok: res.ok,
         error: res.error,
-        promptTokens: 5,
-        completionTokens: 10,
+        promptTokens: res.promptTokens || 5,
+        completionTokens: res.completionTokens || 10,
       })
+      if (res.status === 429) {
+        const failover = await rotateToNextAccount(ctx, live(), 'service_429', settingsApi)
+        if (failover.rotated) {
+          await syncProviderState(live())
+        }
+      }
       return res
     },
   }

package/lib/models.js

@@ -136,6 +136,75 @@ export const CLINE_MODELS = Object.freeze([
     recommended: false,
     isCustom: false,
   },
+  {
+    id: 'cline-pass/claude-3-7-sonnet',
+    name: 'Claude 3.7 Sonnet',
+    description: 'Hybrid reasoning and standard generation model with high coding proficiency.',
+    contextLength: 200000,
+    maxTokens: 8192,
+    input: ['text', 'image'],
+    category: 'coding',
+    recommended: true,
+    isCustom: false,
+    reasoningEfforts: ['low', 'medium', 'high'],
+  },
+  {
+    id: 'cline-pass/gpt-4.5-preview',
+    name: 'GPT-4.5 Preview',
+    description: 'Advanced flagship frontier model with deep world knowledge and intuition.',
+    contextLength: 128000,
+    maxTokens: 16384,
+    input: ['text', 'image'],
+    category: 'general',
+    recommended: true,
+    isCustom: false,
+  },
+  {
+    id: 'cline-pass/o3-mini',
+    name: 'o3-mini',
+    description: 'Fast, cost-effective reasoning model specialized for STEM and coding.',
+    contextLength: 200000,
+    maxTokens: 65536,
+    input: ['text'],
+    category: 'reasoning',
+    recommended: true,
+    isCustom: false,
+    reasoningEfforts: ['low', 'medium', 'high'],
+  },
+  {
+    id: 'cline-pass/gemini-2.5-pro',
+    name: 'Gemini 2.5 Pro',
+    description: 'State-of-the-art multimodal reasoning model with extended context.',
+    contextLength: 1000000,
+    maxTokens: 8192,
+    input: ['text', 'image'],
+    category: 'multimodal',
+    recommended: true,
+    isCustom: false,
+    reasoningEfforts: ['low', 'medium', 'high'],
+  },
+  {
+    id: 'cline-pass/gemini-2.5-flash',
+    name: 'Gemini 2.5 Flash',
+    description: 'Ultra-fast multimodal model optimized for real-time agent workflows.',
+    contextLength: 1000000,
+    maxTokens: 8192,
+    input: ['text', 'image'],
+    category: 'general',
+    recommended: false,
+    isCustom: false,
+  },
+  {
+    id: 'cline-pass/qwen-2.5-coder-32b',
+    name: 'Qwen 2.5 Coder 32B',
+    description: 'Open-weights powerhouse for code generation, refactoring and bug fixing.',
+    contextLength: 131072,
+    maxTokens: 8192,
+    input: ['text'],
+    category: 'coding',
+    recommended: false,
+    isCustom: false,
+  },
 ])
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-clinebot",
-  "version": "0.3.6",
+  "version": "0.3.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",