📦 @goodandready/dsh-clinebot

⚡ 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-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]
        Page["Dedicated Page (Settings -> ClineBot)"]
        QuotaBar["5-Hour & Weekly Progress Bars & Warning Banner"]
        KeyInput["Direct Key Paste & Save"]
        ModelPick["Dynamic Model Sync & Picker Controls"]
        StatsCard["Session Metrics Telemetry"]
    end

    subgraph PluginHost [dsh-clinebot Host Runtime]
        HttpEndpoints["API: /dsh-clinebot/*"]
        ClientCore["lib/cline-client.js"]
        ModelCatalog["lib/models.js (Curated + Dynamic Plan)"]
        SlashCmd["Command: /cline"]
    end

    subgraph DSHCore [DeepSeek Harness Services]
        Credentials["Credentials Service (~/.dsh/.credentials.yaml)"]
        PiAi["Settings: llm-pi-ai.providers.clinebot"]
    end

    subgraph Upstream [Cline Cloud]
        ClinePass["api.cline.bot/api/v1/chat/completions"]
        ClineQuota["api.cline.bot/api/v1/users/me/plan/usage-limits"]
        ClinePlan["api.cline.bot/api/v1/users/me/plan"]
    end

    Page -->|GET /status & /usage| HttpEndpoints
    KeyInput -->|POST /save-key| HttpEndpoints
    ModelPick -->|POST /models/sync| HttpEndpoints
    HttpEndpoints --> Credentials
    HttpEndpoints --> ClientCore
    ClientCore --> ModelCatalog
    HttpEndpoints -->|Atomic Mutate| PiAi
    ClientCore -->|Chat| ClinePass
    ClientCore -->|Usage Limits| ClineQuota
    ClientCore -->|Plan Features| ClinePlan

✨ Features & Module Breakdown

• lib/models.js: 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.
  • saveCredentialKey: writes credentials directly into ~/.dsh/.credentials.yaml.
  • smokeChat: tests latency via non-streaming ping and updates session metrics.
  • buildPiAiProvider: builds the DSH llm-pi-ai structure (api: 'openai-completions') with full reasoning effort protocol compliance (compat.supportsReasoningEffort: true).
• lib/index.js: Cordis service module managing routes (including POST /dsh-clinebot/models/sync), quota warnings threshold evaluation, credentials, and registering the /cline slash command.
• lib/client.js: Configuration page on the plugin row (plugins.row.config) with live quota bars, an exhaustion warning, session metrics, one-click plan sync, and a fallback plugins card (settings.plugin.item). There is no settings.section sidebar entry.

📦 Installation

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

Restart your DeepSeek Harness instance and refresh the browser.

💬 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-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
  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

🌐 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; the loopback proxy endpoint supports up to 64 MiB payloads (MAX_PROXY_BODY_BYTES):

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.

OpenAI-Compatible Loopback Proxy (Max 64 MiB)

• POST /dsh-clinebot/v1/chat/completions — Transparent local proxy supporting streaming SSE and non-streaming responses, Bearer token authentication, sticky session affinity with least-used quota allocation, body read watchdog (streamIdleTimeoutMs), and automatic 429 failover.
• GET /dsh-clinebot/v1/models — OpenAI-compatible catalog listing all active plan and custom models.

DSH Desktop 2.x & Headless Environments: The loopback proxy binds an isolated loopback HTTP server on 127.0.0.1 (ephemeral port), completely bypassing DesktopWebServer renderer fences (x-dsh-desktop-renderer). Automated fence detection (detectHostWebServerFence) falls back to direct upstream connection if the loopback server is restricted, and proxy mode can be directly toggled via the Diagnostics settings card.

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