@goodandready/dsh-clinebot 0.3.8 → 0.3.10

package/docs/design/DESIGN.md

@@ -1,82 +0,0 @@
-# Design Contract: `@goodandready/dsh-clinebot`
-
-## 1. Executive Summary
-`@goodandready/dsh-clinebot` is a companion plugin for DeepSeek Harness (DSH) enabling native integration of the **ClineBot / ClinePass** subscription provider. Because ClinePass is an OpenAI-compatible endpoint whose `GET /v1/models` returns `404 Not Found`, dynamic discovery is impossible. This plugin acts as the bridge: delivering a curated catalog of open-weights models, securely resolving credentials, exposing health and smoke tests, and mutating the DSH `llm-pi-ai` provider registry.
-
-## 2. Architecture & Cordis Lifecycles
-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**: 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 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"`.
-
-```mermaid
-graph LR
-    subgraph Client [DSH Web Interface]
-        UI[Settings Card: ClineBot]
-        SmokeBtn[Smoke Test Button]
-        RegBtn[Register in DSH Models]
-    end
-
-    subgraph Host [DSH Node.js Runtime]
-        API["HTTP API: /api/plugins/dsh-clinebot/*"]
-        ClientHelper["lib/cline-client.js"]
-        Catalog["lib/models.js (Static 11 Models)"]
-        CredService[DSH Credentials Service]
-        PiAiSettings["DSH Settings: llm-pi-ai"]
-    end
-
-    subgraph Remote [Cline Service]
-        ClineAPI["api.cline.bot/api/v1"]
-    end
-
-    UI -->|GET /status| API
-    SmokeBtn -->|POST /smoke| API
-    RegBtn -->|POST /register| API
-    API --> CredService
-    API --> ClientHelper
-    ClientHelper --> Catalog
-    API -->|Mutate| PiAiSettings
-    ClientHelper -->|POST /chat/completions| ClineAPI
-```
-
-## 3. UI/UX Contract
-* **Badges**:
-  * Host connectivity: `Host online (<ms>)` (green) / `Host unreachable` (red).
-  * Credential presence: `Key ✓ (credentials|env)` (green) / `Key missing` (amber).
-  * Registration status: `DSH Registered` (green) / `Not Registered` (amber).
-* **Model Picker**: Interactive checklist of all 11 official models with multi-select and vision capability indicators.
-* **Non-destructive actions**: Unregister cleanly removes the provider entry from DSH without touching other providers or configurations.
-
-## 4. Security & Isolation
-* CSRF / Cross-site protection: All mutating routes (`/register`, `/unregister`, `/smoke`, `/models`, `/accounts/active`, `/auth/begin`) validate `isTrustedSettingsRequest(req)` (`Sec-Fetch-Site !== 'cross-site'`).
-* Body size limits: Request payloads are strictly capped at 256 KB.
-* Sensitive credential data is never returned across the HTTP API (only `{ present: boolean, source: string, envName: string }`).
-
-## 5. Multi-Account Pool & Resilient Execution (v0.3.3)
-* **Account Pool**: The plugin supports multiple accounts (`accounts: [{ label, apiKeyEnv }]`, `activeAccount`). `resolveActiveAccountKey()` automatically selects the configured active account or falls back to primary `apiKeyEnv`. Account switching (`POST /dsh-clinebot/accounts/active` and `/cline switch <label>`) triggers instant re-registration in `llm-pi-ai` without service restart.
-* **Resilient Retry Policy**: HTTP calls to ClinePass utilize `retryWithBackoff()` with exponential delays and jitter to automatically absorb transient 429 rate-limiting events and upstream 5xx errors.
-* **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.