@goodandready/dsh-clinebot 0.5.7 → 0.5.9

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.5.9] - 2026-10-01
+
+### Fixed
+- **Updater Timeout Exit & SIGKILL Escalation (Issue #172)**: Ensured `installExact` child process cleanup waits for the operating system process to fully terminate via `exit`/`close` events before releasing profile locks or rejecting update promises. On timeout, sends `SIGTERM`, waits for a grace period, and escalates to `SIGKILL` for stubborn subprocesses.
+- **Proxy Client Disconnection SSE Abort Fixture (Issue #173)**: Validated client disconnection handling against a real Node.js loopback HTTP fixture with client TCP stream destruction, asserting upstream `reader.cancel()` and fetch `signal.aborted` without relying exclusively on synthetic mocks.
+- **Dependency Manifest & Lockfile Synchronization (Issue #174)**: Regenerated `package-lock.json` via clean npm resolution for all 21 dependencies to ensure deterministic, clean `npm ci` builds across environments, while maintaining proper exclusion of the lockfile from package archives.
+- **UI Locale Key Completeness & Reasoning/Quota Strings (Issue #175)**: Resolved missing locale keys across `en` and `zh` dictionaries for structured quota countdowns/warnings, reasoning tags and effort selectors, capability badges, smoke test diagnostic outputs, and ErrorBoundary alerts. Added regression test asserting 100% dictionary completeness and symmetry for client `t()` calls.
+- **Update Check State Machine & Error Handling (Issue #176)**: Implemented explicit update state machine (`idle`, `checking`, `current`, `available`, `error`) in `UpdateBanner` and `settings-page.js`. Eliminated false "✓ Up to date" status indicators on failed network checks or when `latestCheckFailed: true`, and added retry action.
+- **Documentation & Design Contract Modernization (Issue #177)**: Synchronized `README.md`, `README.ru.md`, `README.zh.md`, and `docs/design/DESIGN.md` with active runtime contracts: documented dynamic subscription catalog, custom models, active configuration schema (`disabledModels`, `proxyMode`, `accounts`), corrected route prefixes (`/dsh-clinebot/*`), and documented all 4 registered UI seats and release testing workflows.
+
+## [0.5.8] - 2026-09-30
+
+### Fixed
+- **Settings PUT Method & Form Error Recovery (Issue #156)**: Fixed `handleConfigPatch` in settings UI client to use `PUT /config` conforming to API routes and preserve unsaved form drafts on server errors.
+- **Client Telemetry Wire Envelope Normalization (Issue #159)**: Fixed `statsSummary` in status payload to align with persistent storage format and accurately display model token consumption and totals.
+- **Deduplication of Proxy & LLM Stream Telemetry (Issue #160)**: Avoided double-counting tokens and latency when requests pass through loopback proxy into `llm/stream`.
+- **Proxy Error Mapping & 429 Header Preservation (Issue #166)**: Differentiated network unreachable/ECONNREFUSED errors as HTTP 502 Bad Gateway instead of false 429, and preserved upstream `Retry-After` headers.
+- **Fetch Response Body Disposal Before Retry (Issue #167)**: Explicitly cancelled upstream HTTP response bodies before triggering retry or account failover on rate-limited or error attempts.
+- **Dynamic Models Catalog Synchronization (Issue #168)**: Pruned deleted upstream models and reconciled metadata diffs on subscription plan updates using `isCatalogDifferent`.
+- **Collision-Free Opaque Usage Cache Key (Issue #169)**: Replaced 8-character key suffix with SHA-256 hash of `baseUrl` and full API key to prevent cross-account cache collisions and protect key secrecy.
+- **Custom Models Resolution Across Routes & Slash Commands (Issue #170)**: Forwarded user-defined custom models through catalog lookup, validation, `/cline test`, `/cline models`, and context configuration routes.
+- **Local Proxy Bearer Token Redaction in Provider Settings (Issue #171)**: Omitted plaintext local proxy token from pi-ai provider descriptor and settings mutation payload, resolving authentication strictly through credential references.
+
 ## [0.5.7] - 2026-09-30
 
 ### Fixed

package/README.md

@@ -74,7 +74,7 @@ graph LR
     end
 
     subgraph PluginHost [dsh-clinebot Host Runtime]
-        HttpEndpoints["API: /api/plugins/dsh-clinebot/*"]
+        HttpEndpoints["API: /dsh-clinebot/*"]
         ClientCore["lib/cline-client.js"]
         ModelCatalog["lib/models.js (Curated + Dynamic Plan)"]
         SlashCmd["Command: /cline"]
@@ -108,7 +108,7 @@ graph LR
 ## ✨ Features & Module Breakdown
 
 * **`lib/models.js`**:
-  Manages the curated catalog (11 built-in models) with full reasoning effort mappings (`off: null`, `low`, `medium`, `high`, `max`), upstream 200k context limit declarations, and dynamic subscription plan model parsing (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
+  Manages the dynamic subscription catalog and fallback models with full reasoning effort mappings (`off: null`, `low`, `medium`, `high`, `max`), upstream 200k context limit declarations, user-defined custom models, and dynamic subscription plan model parsing (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
 * **`lib/cline-client.js`**:
   * `fetchUsageLimits`: queries `GET /users/me/plan/usage-limits`, `GET /users/me/plan`, and `GET /users/me` with in-memory caching.
   * `sessionStats` / `recordSessionRequest`: in-memory telemetry recording requests count, tokens, latency, and timestamps.
@@ -163,29 +163,42 @@ dsh-clinebot:
   enabled: true
   baseUrl: https://api.cline.bot/api/v1
   apiKeyEnv: CLINEBOT_API_KEY
-  defaultModel: cline-pass/deepseek-v4-flash
-  timeoutMs: 15000
-  smokeTimeoutMs: 25000
-  enabledModels:
-    - cline-pass/deepseek-v4-flash
-    - cline-pass/deepseek-v4-pro
-    - cline-pass/kimi-k3
-    - cline-pass/qwen3.7-max
-  dynamicModels: []
+  defaultModel: your-default-model
+  proxyMode: true
+  disabledModels: []
+  customModels: []
+  modelReasoningDefaults:
+    your-reasoning-model: high
+  modelContextOverrides: []
+  statsPath: ~/.dsh/clinebot-stats.json
+  timeoutMs: 30000
+  smokeTimeoutMs: 60000
+  streamIdleTimeoutMs: 60000
+  accounts:
+    - label: Team Key
+      apiKeyEnv: CLINEBOT_API_KEY_2
 ```
 
 ### Configuration Parameters
 
 | Parameter | Type | Default | Description |
 |:---|:---|:---|:---|
-| `enabled` | `boolean` | `true` | Enable or disable the ClineBot provider bridge |
+| `enabled` | `boolean` | `true` | Enable or disable the ClineBot provider bridge in DSH |
 | `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | ClinePass OpenAI-compatible base URL |
 | `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | Environment variable / credentials key name |
-| `defaultModel` | `string` | `"cline-pass/deepseek-v4-flash"` | Default selected model ID |
+| `defaultModel` | `string` | `"claude-3-7-sonnet"` | Default selected model ID for chat and smoke tests |
+| `disabledModels` | `array` | `[]` | List of model IDs hidden from the DSH chat picker (new subscription models are auto-enabled) |
+| `customModels` | `array` | `[]` | User-defined gateway models (`[{ id, name, contextLength, maxTokens, category, isReasoning }]`) |
+| `modelReasoningDefaults` | `object` | `{}` | Configured default reasoning effort per model (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | User-defined model context length and max token overrides |
-| `timeoutMs` | `number` | `15000` | HTTP request timeout in milliseconds |
-| `smokeTimeoutMs` | `number` | `25000` | Smoke test latency ping timeout |
-| `enabledModels` | `array` | `[...]` | List of models exposed in the DSH chat picker |
+| `proxyMode` | `boolean` | `true` | Enable local transparent loopback proxy for sticky sessions and automatic 429 failover |
+| `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | Persistent on-disk path for token usage analytics |
+| `accounts` | `array` | `[]` | Additional accounts for multi-account failover and quota rotation (`[{ label, apiKeyEnv }]`) |
+| `activeAccount` | `string` | `""` | Manually pinned active account env name (empty for least-used auto routing) |
+| `timeoutMs` | `number` | `30000` | HTTP probe timeout in milliseconds |
+| `smokeTimeoutMs` | `number` | `60000` | Timeout for smoke test chat completions in milliseconds |
+| `streamIdleTimeoutMs` | `number` | `60000` | Idle timeout between SSE stream chunks in milliseconds |
+| `enabledModels` | `array` | *(deprecated)* | Read-only in public config; rejected on `PUT /config` in favor of `disabledModels` |
 | `dynamicModels` | `array` | `[]` | Dynamic models automatically synced from the official plan |
 
 ---

package/README.ru.md

@@ -74,7 +74,7 @@ graph LR
     end
 
     subgraph PluginHost [Хост-часть dsh-clinebot]
-        HttpEndpoints["API: /api/plugins/dsh-clinebot/*"]
+        HttpEndpoints["API: /dsh-clinebot/*"]
         ClientCore["lib/cline-client.js"]
         ModelCatalog["lib/models.js (Встроенные + Динамические из плана)"]
         SlashCmd["Слэш-команда: /cline"]
@@ -107,7 +107,7 @@ graph LR
 
 ## ✨ Структура модулей и возможности
 
-* **`lib/models.js`**: каталог встроенных моделей ClinePass (11 моделей с полной поддержкой уровней размышлений `Off` / `Low` / `Medium` / `High` / `Max` и фиксацией лимита шлюза в 200k токенов) и парсер моделей подписки (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
+* **`lib/models.js`**: динамический каталог моделей подписки и встроенных шаблонов с поддержкой уровней рассуждения (`Off` / `Low` / `Medium` / `High` / `Max`), контекстных лимитов, пользовательских моделей (`customModels`) и парсинга тарифа (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
 * **`lib/cline-client.js`**:
   * `fetchUsageLimits`: параллельный опрос `GET /users/me/plan/usage-limits`, `GET /users/me/plan` и `GET /users/me` с кэшированием в памяти.
   * `sessionStats` / `recordSessionRequest`: счетчики сессии (запросы, токены, задержка, время).
@@ -158,29 +158,42 @@ dsh-clinebot:
   enabled: true
   baseUrl: https://api.cline.bot/api/v1
   apiKeyEnv: CLINEBOT_API_KEY
-  defaultModel: cline-pass/deepseek-v4-flash
-  timeoutMs: 15000
-  smokeTimeoutMs: 25000
-  enabledModels:
-    - cline-pass/deepseek-v4-flash
-    - cline-pass/deepseek-v4-pro
-    - cline-pass/kimi-k3
-    - cline-pass/qwen3.7-max
-  dynamicModels: []
+  defaultModel: your-default-model
+  proxyMode: true
+  disabledModels: []
+  customModels: []
+  modelReasoningDefaults:
+    your-reasoning-model: high
+  modelContextOverrides: []
+  statsPath: ~/.dsh/clinebot-stats.json
+  timeoutMs: 30000
+  smokeTimeoutMs: 60000
+  streamIdleTimeoutMs: 60000
+  accounts:
+    - label: Team Key
+      apiKeyEnv: CLINEBOT_API_KEY_2
 ```
 
 ### Параметры конфигурации
 
 | Параметр | Тип | По умолчанию | Описание |
 |:---|:---|:---|:---|
-| `enabled` | `boolean` | `true` | Включение моста провайдера ClineBot |
+| `enabled` | `boolean` | `true` | Включение моста провайдера ClineBot в DSH |
 | `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | Базовый URL OpenAI-совместимого API ClinePass |
 | `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | Имя переменной / ключа в хранилище credentials |
-| `defaultModel` | `string` | `"cline-pass/deepseek-v4-flash"` | Модель, выбираемая по умолчанию |
+| `defaultModel` | `string` | `"claude-3-7-sonnet"` | Модель, выбираемая по умолчанию для чата и smoke-тестов |
+| `disabledModels` | `array` | `[]` | Список отключённых моделей (новые модели подписки включаются автоматически) |
+| `customModels` | `array` | `[]` | Пользовательские модели шлюза (`[{ id, name, contextLength, maxTokens, category, isReasoning }]`) |
+| `modelReasoningDefaults` | `object` | `{}` | Значения thinking effort по умолчанию для моделей (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | Пользовательские переопределения размера контекста и лимита токенов |
-| `timeoutMs` | `number` | `15000` | Таймаут HTTP-запросов (мс) |
-| `smokeTimeoutMs` | `number` | `25000` | Таймаут тестового пинга (мс) |
-| `enabledModels` | `array` | `[...]` | Список моделей, активных в селекторе чата |
+| `proxyMode` | `boolean` | `true` | Включение локального прозрачного loopback-прокси с сессионным роутингом и failover |
+| `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | Путь к файлу персистентной аналитики использования токенов |
+| `accounts` | `array` | `[]` | Дополнительные аккаунты для ротации квоты и failover (`[{ label, apiKeyEnv }]`) |
+| `activeAccount` | `string` | `""` | Принудительно закреплённый аккаунт (пусто для автоматического выбора least-used) |
+| `timeoutMs` | `number` | `30000` | Таймаут HTTP-запросов (мс) |
+| `smokeTimeoutMs` | `number` | `60000` | Таймаут тестового пинга инференса (мс) |
+| `streamIdleTimeoutMs` | `number` | `60000` | Таймаут ожидания между чанками SSE-потока (мс) |
+| `enabledModels` | `array` | *(устарело)* | Только для чтения в public config; отклоняется при `PUT /config` в пользу `disabledModels` |
 | `dynamicModels` | `array` | `[]` | Динамические модели, автоматически синхронизированные из тарифа |
 
 ---

package/README.zh.md

@@ -74,7 +74,7 @@ graph LR
     end
 
     subgraph PluginHost [dsh-clinebot 宿主运行环境]
-        HttpEndpoints["API 路由: /api/plugins/dsh-clinebot/*"]
+        HttpEndpoints["API 路由: /dsh-clinebot/*"]
         ClientCore["lib/cline-client.js"]
         ModelCatalog["lib/models.js (内置精选 + 动态订阅解析)"]
         SlashCmd["斜杠指令: /cline"]
@@ -107,7 +107,7 @@ graph LR
 
 ## ✨ 核心模块与功能
 
-* **`lib/models.js`**：管理 11 款官方精选内置模型（提供完整的 `Off` / `Low` / `Medium` / `High` / `Max` 思考强度映射、上游 200k 上下文容量标注）以及套餐模型动态解析器（`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`）。
+* **`lib/models.js`**：管理动态订阅模型目录与内置精选模板（提供完整的 `Off` / `Low` / `Medium` / `High` / `Max` 思考强度映射、上游 200k 上下文容量标注、自定义模型支持）以及套餐模型动态解析器（`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`）。
 * **`lib/cline-client.js`**：
   * `fetchUsageLimits`：高效并发轮询 `GET /users/me/plan/usage-limits`、`GET /users/me/plan` 与 `GET /users/me` 并进行内存缓存。
   * `sessionStats` / `recordSessionRequest`：内存级会话度量记录器（请求次数、Token 估算、延迟、时间戳）。
@@ -160,29 +160,42 @@ dsh-clinebot:
   enabled: true
   baseUrl: https://api.cline.bot/api/v1
   apiKeyEnv: CLINEBOT_API_KEY
-  defaultModel: cline-pass/deepseek-v4-flash
-  timeoutMs: 15000
-  smokeTimeoutMs: 25000
-  enabledModels:
-    - cline-pass/deepseek-v4-flash
-    - cline-pass/deepseek-v4-pro
-    - cline-pass/kimi-k3
-    - cline-pass/qwen3.7-max
-  dynamicModels: []
+  defaultModel: your-default-model
+  proxyMode: true
+  disabledModels: []
+  customModels: []
+  modelReasoningDefaults:
+    your-reasoning-model: high
+  modelContextOverrides: []
+  statsPath: ~/.dsh/clinebot-stats.json
+  timeoutMs: 30000
+  smokeTimeoutMs: 60000
+  streamIdleTimeoutMs: 60000
+  accounts:
+    - label: Team Key
+      apiKeyEnv: CLINEBOT_API_KEY_2
 ```
 
 ### 配置参数说明
 
 | 参数项 | 类型 | 默认值 | 说明 |
 |:---|:---|:---|:---|
-| `enabled` | `boolean` | `true` | 是否启用 ClineBot 桥接插件 |
+| `enabled` | `boolean` | `true` | 是否在 DSH 中启用 ClineBot 桥接插件 |
 | `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | ClinePass OpenAI 兼容接口地址 |
 | `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | 凭据管理系统中的密钥名称 |
-| `defaultModel` | `string` | `"cline-pass/deepseek-v4-flash"` | 默认选中的模型 ID |
+| `defaultModel` | `string` | `"claude-3-7-sonnet"` | 默认选中的模型 ID（用于对话及探活） |
+| `disabledModels` | `array` | `[]` | 在选择器中隐藏的模型 ID 列表（新订阅模型默认自动启用） |
+| `customModels` | `array` | `[]` | 用户自定义网关模型 (`[{ id, name, contextLength, maxTokens, category, isReasoning }]`) |
+| `modelReasoningDefaults` | `object` | `{}` | 各模型默认思考强度配置 (`low`, `medium`, `high`, `max`) |
 | `modelContextOverrides` | `array` | `[]` | 用户自定义模型上下文窗口与最大 Token 数量覆盖 |
-| `timeoutMs` | `number` | `15000` | HTTP 请求超时时间（毫秒） |
-| `smokeTimeoutMs` | `number` | `25000` | 探活测试超时时间（毫秒） |
-| `enabledModels` | `array` | `[...]` | 允许在聊天下拉框中显示的可用模型列表 |
+| `proxyMode` | `boolean` | `true` | 启用透明本地环回代理以支持会话粘性路由与 429 自动故障转移 |
+| `statsPath` | `string` | `"~/.dsh/clinebot-stats.json"` | 本地持久化 Token 用量统计文件路径 |
+| `accounts` | `array` | `[]` | 额外轮转账号池 (`[{ label, apiKeyEnv }]`) |
+| `activeAccount` | `string` | `""` | 手动指定的主账号（为空时自动按最低配额消耗优先路由） |
+| `timeoutMs` | `number` | `30000` | HTTP 请求探测超时时间（毫秒） |
+| `smokeTimeoutMs` | `number` | `60000` | 探活测试超时时间（毫秒） |
+| `streamIdleTimeoutMs` | `number` | `60000` | SSE 流式输出块间空闲超时时间（毫秒） |
+| `enabledModels` | `array` | *(已废弃)* | 仅在 public config 中只读提供，`PUT /config` 时禁止写入并请使用 `disabledModels` |
 | `dynamicModels` | `array` | `[]` | 从官方套餐中自动同步的动态模型列表 |
 
 ---

package/lib/account-pool.js

@@ -1,4 +1,4 @@
-import { resolveKeyValue, usageCache, clearUsageCache, clearProbeCache, DEFAULT_API_KEY_ENV } from './cline-client.js'
+import { resolveKeyValue, usageCache, clearUsageCache, clearProbeCache, DEFAULT_API_KEY_ENV, DEFAULT_BASE_URL, buildUsageCacheKey } from './cline-client.js'
 
 /**
  * Resolve all accounts in pool with their status and keys.
@@ -32,9 +32,9 @@ function toPlainSnapshot(cfg) {
   return out
 }
 
-export function getAccountQuotaSnapshot(accValue) {
+export function getAccountQuotaSnapshot(accValue, baseUrl = DEFAULT_BASE_URL) {
   if (!accValue || typeof accValue !== 'string') return null
-  const cacheKey = `cline:usage:${accValue.slice(-8)}`
+  const cacheKey = buildUsageCacheKey(baseUrl, accValue)
   const cached = usageCache.get(cacheKey)?.data
   if (!cached?.windows) return null
 
@@ -67,6 +67,7 @@ export function getAccountQuotaSnapshot(accValue) {
 }
 
 export async function resolveAccountPool(ctx, cfg) {
+  const baseUrl = textSetting(cfg?.baseUrl) || DEFAULT_BASE_URL
   const apiKeyEnv = textSetting(cfg?.apiKeyEnv) || DEFAULT_API_KEY_ENV
   const defaultSlot = {
     id: 'default',
@@ -86,7 +87,7 @@ export async function resolveAccountPool(ctx, cfg) {
     const isPinned = activeAccount === 'auto'
       ? false
       : (activeAccount ? (activeAccount === envName || activeAccount === slotId) : i === 0)
-    const quota = keyInfo.value ? getAccountQuotaSnapshot(keyInfo.value) : null
+    const quota = keyInfo.value ? getAccountQuotaSnapshot(keyInfo.value, baseUrl) : null
     resolved.push({
       id: slotId,
       label: textSetting(slot.label) || (i === 0 ? 'Default' : `Account ${i + 1}`),
@@ -128,6 +129,7 @@ export function isAccountQuotaExhausted(usage) {
  * Prioritizes accounts with lowest percentUsed and respects resetsAt recovery.
  */
 export async function rotateToNextAccount(ctx, cfg, reason = 'rate_limit', settingsApi = null) {
+  const baseUrl = textSetting(cfg?.baseUrl) || DEFAULT_BASE_URL
   const pool = await resolveAccountPool(ctx, cfg)
   const configured = pool.filter((acc) => acc.present && acc.value)
   if (configured.length <= 1) {
@@ -148,7 +150,7 @@ export async function rotateToNextAccount(ctx, cfg, reason = 'rate_limit', setti
   let lowestUsagePct = Infinity
 
   for (const cand of candidates) {
-    const cacheKey = `cline:usage:${cand.value.slice(-8)}`
+    const cacheKey = buildUsageCacheKey(baseUrl, cand.value)
     const cached = usageCache.get(cacheKey)?.data
     const isExhausted = isAccountQuotaExhausted(cached)