dsh-clinebot

📦 @goodandready/dsh-clinebot

Native ClineBot / ClinePass Provider Companion for DeepSeek Harness

0.6.16 accepts the full DSH 0.2.1 prerelease line (including 0.2.1-rc.3) and keeps the multimodal/model/price improvements. Chat runs on the native ctx.llm adapter; the legacy llm-pi-ai, loopback proxy and llm/stream path are removed.

🇬🇧 English • 🇷🇺 Русский • 🇨🇳 中文说明

⭐ If you like this plugin, please star it on GitHub — it shows me that the plugin is useful to you and motivates me to keep developing it. 🐛 If you find a bug or would like to request a feature, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.

⚡ Overview & The Problem

ClinePass (https://cline.bot) is a subscription service providing developers with 2–5x higher rate limits across premier open-weights coding and reasoning models through a single OpenAI-compatible endpoint (https://api.cline.bot/api/v1).

Integrating ClinePass into DeepSeek Harness (DSH) natively poses key challenges:

1. No `/v1/models` Discovery: GET /v1/models on api.cline.bot returns 404 Not Found. Dynamic discovery fails silently or leaves the provider with 0 models.
2. Model Identifier Formats: Models require the specific prefix cline-pass/ (e.g. cline-pass/deepseek-v4.1-flash, cline-pass/kimi-k3).
3. Quota Tracking: Rolling 5-hour and weekly limits need clear in-browser visualization.
4. Credential Security: Storing API keys directly in plain settings is insecure.

`@goodandready/dsh-clinebot` provides a complete solution:

• 🚀 One-Click In-App Updater: Upgrade @goodandready/dsh-clinebot directly from the DSH UI or trigger secure loopback updates via /dsh-clinebot/update.
• ⚡ SWR Quota & Health Caching: Instantaneous response time (<2ms) on status queries with background revalidation.
• 🔀 Smart Quota-Aware Failover: Automatic multi-account rotation on stream HTTP 429 and exhausted quota (with 30s storm protection; current request is not retried, subsequent chat requests use the next available account).
• 🖥️ Plugin configuration page: Open the installed ClineBot plugin and choose configure. The page shows the credential name, models, quota, and accounts. It is not a separate sidebar section.
• 🔄 Dynamic Subscription Model Sync: Automatically pulls real models included in your ClinePass plan directly from GET /api/v1/users/me/plan with one-click DSH provider sync. Only actual plan models are registered in DSH, while the built-in catalog serves as a rich properties reference and fallback when unsynced.
• ⚠️ Quota Exhaustion Alerts: Real-time visual warning banners when 5-hour rolling limit reaches 80% (warning) and 95% (exhausted), complete with countdown to reset.
• 📈 Session Metrics Telemetry: Live dashboard tracking real in-flight DSH chat requests through the ClineBot provider, prompt and completion tokens, stream latency, and error counts since process startup.
• 📊 Live Quota Dashboard: Visual progress bars for 5-hour rolling limits and weekly windows from the official GET /users/me/plan/usage-limits API.
• 🔑 In-UI Key Storage: Paste your API key directly in the UI; it is saved securely via ctx.credentials.set() into ~/.dsh/.credentials.yaml.
• 🎯 Model Picker Management: Granular checkboxes to choose which models appear in the chat picker.
• 💬 Slash-Command `/cline`: Check quota, limits, warnings, session metrics, latency, and active model directly from the DSH chat console.

🏛️ Architecture

graph LR
    subgraph UI [DSH Web Interface]
        Settings["Settings -> ClineBot"]
        Dashboard["Quota / Analytics panel"]
        Composer["Composer cost read-out"]
        Picker["Model picker"]
    end

    subgraph PluginHost [dsh-clinebot Runtime]
        Routes["HTTP: /dsh-clinebot/*"]
        Adapter["lib/adapter.js (ctx.llm LlmAdapter)"]
        Transport["lib/transport/cline-transport.js"]
        Pool["account-pool + session-router"]
        Stats["stats-storage v2 + model-prices"]
        TUI["dsh-TUI settings section"]
    end

    subgraph DSHCore [DeepSeek Harness 0.2.1-rc.2+]
        Llm["ctx.llm"]
        Credentials["ctx.credentials"]
        Web["ctx.web / settings / commands"]
    end

    subgraph Upstream [ClinePass]
        Chat["api.cline.bot/api/v1/chat/completions"]
        Quota["users/me/plan/usage-limits"]
        Plan["users/me/plan"]
    end

    Settings --> Routes
    Dashboard --> Routes
    Composer --> Routes
    Picker --> Llm
    Llm --> Adapter
    Adapter --> Pool
    Adapter --> Transport
    Transport --> Chat
    Adapter --> Stats
    Routes --> Stats
    Routes --> Credentials
    TUI --> Routes
    Adapter --> Quota
    Adapter --> Plan

✨ Features & Module Breakdown

• `lib/adapter.js`:

Registers the ClineBotAdapter directly on ctx.llm: streaming, model catalogue, reasoning effort, pre-first-token account failover, retry policy, usage accounting and provider metadata.

• `lib/transport/cline-transport.js`:

OpenAI-compatible SSE transport with connect/idle timeouts, abort handling and upstream error classification.

• `lib/models.js`:

Dynamic subscription catalogue, curated fallback properties, reasoning efforts, custom models and plan parsing (parsePlanIncludedModels, getAllModels, getDynamicModels).

• `lib/model-prices.js`:

Explicit local cost estimates with per-model overrides. Unknown models stay unpriced instead of being reported as $0. When a newly discovered model has no price, the optional priceAutoSync setting fetches the public models.dev catalog (at most once per missing set every 6 hours); turn it off in the price card or set priceAutoSync: false while keeping the manual Sync button.

• `lib/multimodal-budget.js`:

Offloads images from earlier turns into stable text placeholders and enforces maxPayloadMb, reducing prompt-cache churn and oversized ClinePass requests. offloadedImages is included in session telemetry.

• Model tools in Settings → ClineBot → Models:

The per-model Ping button calls POST /models/probe and shows TTFT; Apply visibility calls POST /models/visible after choosing the visible models and plan-only filter.

• `lib/stats-storage.js`:

Persistent JSON telemetry v2: cache buckets, estimated cost, TTFT/latency, sessions and day/month/model/account aggregates. v1 files upgrade on read.

• `lib/account-pool.js` / `lib/session-router.js`:

Credential discovery, usage-aware least-used and round-robin rotation, sticky sessions and cooldown recovery.

• `lib/cline-client.js`:

fetchUsageLimits, credential save, smoke test and the model catalogue cache.

• `lib/index.js`:

Cordis lifecycle: adapter registration, optional HTTP routes, quota warnings, /cline command, one-time cleanup of the old provider entry and TUI section registration.

• `lib/tui-settings.js`:

dsh-TUI section for key, base URL, model filters, active account, context window and output cap.

• `lib/client.js`:

Native settings.section plus provider card, sidebar meter, center-column quota/analytics panel (modal fallback) and composer cost read-out. No emojis, no full-page panel swap.

📦 Installation

dsh plugin --profile web add @goodandready/dsh-clinebot

Requires DSH `0.2.1-rc.2` or newer in the `0.2.1` line and Node 22+. ClineBot registers directly with ctx.llm; there is no transport switch or loopback proxy.

Restart your DeepSeek Harness instance and refresh the browser.

0.6.0 endpoints

Endpoint · Purpose GET /dsh-clinebot/analytics?groupBy=model\ · day\ · session&from=&to= · Aggregated requests, tokens, estimated cost, success rate and TTFT GET /dsh-clinebot/prices · Local price table used by the composer read-out GET /dsh-clinebot/accounts/usage · Per-account quota snapshot GET /dsh-clinebot/stats/export?detailed=1 · CSV with cache, cost, TTFT and latency columns

💬 Slash-Command /cline

From any DSH chat session, type /cline to inspect quota, warning alerts, and session telemetry:

### 🤖 ClinePass Status (ClinePass)
* Latency: ✅ 210 ms
* Active Key: CLINEBOT_API_KEY (credentials)
* Default Model: `cline-pass/deepseek-v4.1-flash`

⏱ 5-Hour Window: [████░░░░░░] 42% (resets: 18:00)
📅 Weekly Window: [██████░░░░] 60% (resets: Sep 8)
* Account: `developer@example.com`

📈 Session Metrics:
* Requests: 14 calls
* Tokens: ~8,450 (Prompt: 6,100 | Completion: 2,350)
* Last Latency: 210 ms

⚙️ Configuration Reference (DSH Settings & Web UI)

In modern DeepSeek Harness (0.1.7+), settings are managed natively via the DSH Web UI Settings card or PUT /dsh-clinebot/config, with API keys persisted securely in DSH Credentials storage (~/.dsh/.credentials.yaml).

dsh-clinebot:
  enabled: true
  baseUrl: https://api.cline.bot/api/v1
  apiKeyEnv: CLINEBOT_API_KEY
  defaultModel: your-default-model
  disabledModels: []
  customModels: []
  modelReasoningDefaults:
    your-reasoning-model: high
  modelContextOverrides: []
  statsPath: ~/.dsh/clinebot-stats.json
  priceCatalogUrl: https://models.dev/api.json
  priceCatalogPath: ~/.dsh/clinebot-prices.json
  priceAutoSync: true
  eventLogPath: ~/.dsh/clinebot-events.json
  statsRetentionDays: 95
  dailyBudgetUsd: 0
  monthlyBudgetUsd: 0
  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 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.1-flash" · 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 statsPath · string · "~/.dsh/clinebot-stats.json" · Persistent on-disk path for token usage analytics priceCatalogUrl · string · "https://models.dev/api.json" · Public price catalog used by the optional sync priceCatalogPath · string · "~/.dsh/clinebot-prices.json" · Local cache for the public price catalog priceAutoSync · boolean · true · Fetch models.dev for newly discovered models without a price; the manual Sync button remains available when off eventLogPath · string · "~/.dsh/clinebot-events.json" · Ring buffer for account cooldown/recovery/routing history statsRetentionDays · number · 95 · Retention for day/hour/session telemetry; 0 keeps everything dailyBudgetUsd · number · 0 · Optional estimated daily spend guard; 0 disables it monthlyBudgetUsd · number · 0 · Optional estimated monthly spend guard; 0 disables it 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 · 15000 · HTTP probe timeout in milliseconds smokeTimeoutMs · number · 25000 · Timeout for smoke test chat completions in milliseconds streamIdleTimeoutMs · number · 30000 · 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

🌐 HTTP API Endpoints

All endpoints are registered under /dsh-clinebot/* and protected against untrusted cross-site origins (same-origin and loopback allowed). Control endpoints enforce a 256 KiB request payload limit:

Management & Control Endpoints (Max 256 KiB)

• GET /dsh-clinebot/status — Live status report including provider health, active credential, quota, and session metrics.
• GET /dsh-clinebot/config — Diagnostic endpoint returning public configuration without secret keys.
• PUT /dsh-clinebot/config — Update configuration fields. Accepts only known schema properties (unknown fields or deprecated enabledModels return 400 Bad Request).
• POST /dsh-clinebot/key/verify — Validates a candidate API key against api.cline.bot and returns account email and plan name.
• POST /dsh-clinebot/save-key — Saves a key into DSH credentials service under a valid CLINEBOT_API_KEY* name.
• POST /dsh-clinebot/models/sync — Synchronizes models with your active subscription plan.
• POST /dsh-clinebot/models/toggle — Toggles models via disabledModels (atomic Volatile preservation).
• POST /dsh-clinebot/models/custom / DELETE /dsh-clinebot/models/custom — Manage custom user-defined models.
• POST /dsh-clinebot/models/context / DELETE /dsh-clinebot/models/context — Manage model context length overrides.
• POST /dsh-clinebot/accounts — Add account to the multi-account pool.
• POST /dsh-clinebot/accounts/delete — Delete account from the pool with atomic credential preservation.
• POST /dsh-clinebot/accounts/active — Switch or pin active account (or empty for auto least-used routing).
• POST /dsh-clinebot/stats/reset — Reset session request and token statistics.
• POST /dsh-clinebot/smoke — Runs a live latency test ping.
• GET /dsh-clinebot/update/status — Query available GitHub releases and plugin updates.
• POST /dsh-clinebot/update/apply — Apply version upgrade with process-group cleanup and lockfile sync.

Visual verification

Settings card in DeepSeek Harness, Dark and Light themes side by side:

🧪 Testing

Run the automated test suite:

npm test

📄 License

MIT © GooDAnDReaDY