GooDAnDReaDY/dsh-subscriptions

📦 @goodandready/dsh-subscriptions

Personal AI Subscription Bridge, Multi-Account Pool Rotation & Zero-Leak OAuth for DeepSeek Harness

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

⚡ Overview

`dsh-subscriptions` bridges your paid personal AI subscriptions directly into DeepSeek Harness as first-class LLM providers.

Instead of burning expensive pay-as-you-go API credits for everyday agent tasks, dsh-subscriptions allows you to authenticate your existing web subscriptions via standard OAuth PKCE. It features multi-account rotation pools (automatically switching accounts when a rate limit or cooldown is reached), preemptive quota switching, and an in-process Cordis service (`ctx.subscriptions`) that safely powers sibling plugins like dsh-image-gen and dsh-grok-xsearch with zero token leakage.

graph LR
    subgraph DSHCore [DeepSeek Harness Session]
        Agent[🤖 DSH Agent Execution] --> Router{Provider Router}
    end

    subgraph SubscriptionsCore [dsh-subscriptions Engine]
        Router --> Pool{Multi-Account Vendor Pool}
        Pool -->|Account #1| Acc1[👤 Primary Account: Active]
        Pool -->|Account #2| Acc2[👤 Secondary Account: Standby]
        Pool -->|Account #3| Acc3[👤 Fallback Account: Cooldown]
        Acc1 -->|HTTP 429 / Quota Limit| Rotate[Smart Quota & Cooldown Rotator]
        Rotate -->|Switches Traffic| Acc2
    end

    subgraph VendorBridges [4 Upstream Vendor Bridges]
        Acc1 --> B1[ChatGPT / Codex Backend]
        Acc1 --> B2[Claude Pro / Max Protocol]
        Acc1 --> B3[xAI / Grok Subscriptions]
        Acc1 --> B4[Google Cloud Code Assist / Antigravity]
    end

    subgraph EcosystemBridge [In-Process Cordis Service: ctx.subscriptions]
        Pool --> ImgGen[dsh-image-gen: Zero-Cost Image Drawing]
        Pool --> XSearch[dsh-grok-xsearch: Live Twitter Search]
    end

    style DSHCore fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
    style SubscriptionsCore fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
    style VendorBridges fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
    style EcosystemBridge fill:#181825,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4

✨ Key Features & Capabilities

1. 🌐 16 Supported Built-in Subscription Vendors

Vendor Key · Subscription Tier · Protocol & Features codex · ChatGPT Plus / Pro · Codex streaming responses, tool calling & image drawing (/backend-api/codex/...) claude · Claude Pro / Max · Native Claude Messages protocol, usage tracking (/v1/messages, /api/oauth/...) grok · xAI / X Premium · Real-time reasoning responses, billing checks & social search antigravity · Google Cloud Code Assist · Antigravity engine (/v1/loadCodeAssist, /v1/streamGenerateContent) kimi · Moonshot Kimi · OAuth Device Flow login (auth.kimi.com), OpenAI-compatible chat glm · Z.ai GLM Coding Plan · GLM coding endpoint (api.z.ai), live quota monitor (/api/monitor/usage/quota/limit) cursor · Cursor · Cursor backend (api2.cursor.sh), billing-period usage dashboard parsing kiro · AWS Kiro · Kiro desktop OAuth (app.kiro.dev), streaming code assistance copilot · GitHub Copilot · GitHub Device Flow login (github.com/login/device), Copilot chat completions qwen · Alibaba Qwen (DashScope) · OpenAI-compatible endpoint (dashscope.aliyuncs.com/compatible-mode/v1), API key auth ernie · Baidu ERNIE (Qianfan) · OAuth2 token refresh via API Key + Secret Key, Wenxinworkshop chat spark · iFlytek Spark · OpenAI-compatible Spark HTTP API (spark-api-open.xf-yun.com/v1) jetbrains · JetBrains AI Assistant · JetBrains AI relay (api.jetbrains.ai) perplexity · Perplexity Pro · Sonar model catalog (api.perplexity.ai) replit · Replit Core · Replit AI API (replit.com/api/v1/ai), connect-token auth cody · Sourcegraph Cody Pro · Sourcegraph API (sourcegraph.com/.api), access-token auth

*Custom vendors can also be dynamically registered via the createVendorFromProfile factory.*

2. 🔄 Multi-Account Rotation & Rate-Limit Mitigation (rotate.js, ratelimit.js)

• Multi-Account Pooling: Attach multiple accounts per vendor (e.g. CODEX_OAUTH_1, CODEX_OAUTH_2, CODEX_OAUTH_3).
• Automatic 429 Failover: When an account encounters a rate limit (HTTP 429, RATE_LIMIT, QUOTA_EXCEEDED), traffic instantly fails over to the next healthy account in the pool.
• Preemptive Quota Switching (`switchAtRemaining`): Automatically rotates to the next account before hitting zero if the rate-limit window reset is imminent.
• Dynamic Cooldown Calculation: Parses upstream headers (Retry-After, x-ratelimit-reset, ISO dates, epoch timestamps) and auto-restores cooled-down accounts when their window resets.
• Synchronous Decision Tracing & Routing Explanation (#517): Real-time decision traces capture every account selection, rotation step, failure reason, and cascade fallback without post-hoc reconstruction, exposed in WebUI telemetry and diagnostics.
• Dynamic Model Catalog & Live Quota Visualizer (#507): Dynamic model catalog with pool-level health calculation (individual quarantine degrades rather than disables the pool), context window badges, capability tags (vision, tools, reasoning, coding, fast), and live reset countdowns.
• Cache-Aware Session Pinning (#520): Retains session affinity for prompt-caching providers (Claude, Codex, Antigravity, Grok) to maximize token cache reuse while strictly releasing pins when an account enters cooldown, quarantine, or quota exhaustion.
• Guided Diagnostic Wizard (#519): Interactive step-by-step checklist verifying credentials, network/proxy connectivity, token freshness, and model catalog reachability without paid inference and with full secret redaction.
• Desktop Electron Compatibility (#524): Non-HTTP app schemes (dsh-app://) bypass web-only host equality checks while strictly preserving loopback socket verification and fail-closed cross-site protection.

3. 🔒 Zero-Leak Credential Security & Headless OAuth

• Zero Token Leakage: OAuth tokens are never returned over HTTP API endpoints or rendered in the Web UI. The UI only receives masked account labels, connection health, and quota bars.
• Secure Host Storage: Tokens reside in encrypted $DSH_HOME/.credentials.yaml managed by the host credentials service.
• Headless / Remote Login Fallback: If running DSH on a headless server over SSH where browser popups cannot redirect to localhost, simply paste the redirected callback URL or authorization code directly into the account card.
• Proactive Background Token Refresh: Access tokens are refreshed automatically before expiration.

4. 🧩 In-Process Cordis Service (ctx.subscriptions)

Sibling plugins can tap into subscription capabilities directly in memory via Cordis:

// Example in dsh-image-gen or custom plugins:
const res = await ctx.subscriptions.request('codex', '/backend-api/codex/images/generations', {
  method: 'POST',
  body: JSON.stringify({ prompt: 'Cyberpunk landscape', size: '1024x1024' }),
})

• Zero Overhead: Eliminates intermediate HTTP loops and keeps auth tokens strictly in-memory.
• Strict Path Allowlist (`ALLOWLIST`): Restricts calls to verified vendor endpoints, preventing SSRF vulnerabilities.

5. 🔐 Login Without a Browser: Loopback & Device Code (v0.4.9)

• Automatic Loopback Callback (`autoLoopback`, on by default): For vendors whose OAuth redirect URI is a loopback address (Codex :1455, Grok :56121), the plugin spins up a temporary local HTTP server and catches the callback by itself — no URL pasting needed. The paste fallback always stays available.
• Device Code Login (Codex): On fully headless machines (no browser on any reachable host), use the Device login button in the Codex account card. The plugin requests a short user code from auth.openai.com, you open https://auth.openai.com/codex/device on any device, enter the code, and the plugin completes the standard PKCE exchange automatically.
• Classic Fallbacks Intact: Web-origin redirect (useWebCallback) and manual paste of the redirected URL / authorization code remain available for custom OAuth clients.

6. 🌍 Per-Account HTTP/SOCKS Proxy (v0.4.9)

• Individual Proxy per Account (`proxyUrl`): Every account slot accepts its own proxy URL (http://, https://, socks5://[user:pass@]host:port). All requests for that account — OAuth token refresh, vendor checks, model requests — are routed through it. Empty = direct connection.
• One-Click Proxy Check: The account card has a Check proxy button: it performs a real request to the vendor base URL through the configured proxy and shows the round-trip latency or the failure reason.
• Request History Timings: Every recorded request now carries its duration (ms) in the history store, so you can compare direct vs proxied latency over time.

7. 🕶️ Privacy Masking & Diagnostics Report (v0.4.9)

• Privacy Masking (`privacyMask`): One toggle in the settings card masks personal data across the whole UI: emails render as j***n@example.com everywhere (account lists, status labels, check results). Designed for screen sharing and streaming. Server-side masking means labels never leak through API responses either; the underlying account data is never overwritten.
• Anonymized Diagnostics Report: The settings card has a Generate diagnostics report block: one click fetches an anonymized report (plugin/runtime versions, OS, per-vendor health counters, aggregate HTTP status counts, last ≥400 errors with timings, non-secret settings) and copies it to the clipboard. Tokens, emails, credential refs and proxy URLs are strictly excluded (verified by tests).
• Issue-Ready: The same block links to the project issue tracker, so a bug report is: generate → paste → submit.

8. 🔌 HTTP API (added in v0.4.9)

Route · Method · Purpose /dsh-subscriptions/diagnostics · GET · Anonymized diagnostics report (no secrets, no tokens, no proxy URLs) /dsh-subscriptions/proxy-check · POST · Latency check of a slot's proxy against its vendor base URL /dsh-subscriptions/oauth/device/start · POST · Begin Codex device-code login (returns user code + verification URL) /dsh-subscriptions/oauth/device/poll · POST · Poll device-code authorization status /dsh-subscriptions/quarantine/park · POST · Park an account into quarantine for custom duration (durationMs, reason) /dsh-subscriptions/quarantine/probe · POST · Run immediate live warmup health probe or force-release account /dsh-subscriptions/alerts · GET · List recent in-app alerts and notifications

9. 🦛 Local Ollama Gateway & Seamless Fallback (v0.4.17)

• Native Provider (`ollama`): When a local Ollama is reachable at ollamaBaseUrl (default http://127.0.0.1:11434), it appears in the native DSH model picker with the models discovered from /api/tags. No API key needed.
• Seamless Quota Fallback (`ollamaFallback`, on by default): When every account of a provider is exhausted (or unreachable) and nothing has been streamed yet, the chat continues on a local model (ollamaFallbackModel, or the first model from /api/tags). The fallback is logged and recorded in request history as kind: fallback.
• Free ($0) Emergency Path: Works with no internet and no quota — ideal for offline demos.

10. ⚡ Reasoning Effort, Verbosity & Fast Mode (v0.4.17)

• Reasoning Effort: Codex models advertise their supported effort levels from the live catalog; the native picker validates and the chosen effort is transmitted as reasoning.effort in the Codex /responses protocol. Grok forwards effort with its own catalog-aware filtering.
• Verbosity (`codexVerbosity`): low / medium / high is sent as text.verbosity for Codex reasoning models. Empty = protocol default.
• Fast Mode (`codexFastMode`): Sends service_tier: priority (1.5x speed billing tier) with every Codex request. The active-subscription chip shows a ⚡ prefix while enabled.

11. 🚦 Family-Scoped Cooldowns & Model Filtering (v0.4.17)

• Reasoning vs Standard: A 429 on a reasoning model (claude *thinking*, grok *reasoning*, all codex models) cools down only the reasoning family of that account — standard models on the same account keep working immediately. Legacy cooldowns (from older versions) still block the whole account until expiry.
• Hide Deprecated Models (`hideDeprecatedModels`): Filters test/preview/dev/alpha/beta/legacy model ids out of the native picker (applies to live catalogs and the static fallback).

12. 🧯 Safe Reset Credits (v0.4.18)

• Reset Card Visibility: The Codex account card shows how many ChatGPT quota reset cards are available and when the earliest one expires.
• Deliberate Confirmation Flow: Consuming a card requires an explicit checkbox ("I understand one attempt will be consumed") plus a mandatory 5-second cooldown before the Reset button activates.
• Double-Click Proof: A host-side single-flight gate (synchronous pending lock before the first network await) makes it impossible for a double click or a concurrent call to consume two cards. Uncertain network results return the challenge to "prepared" for a safe retry of the same request.
• Honest Results: Server verdicts are shown verbatim: reset / nothing to reset (nothing consumed) / no usable credit / already redeemed.

13. 📊 Composer Quota Indicator & Runway Forecast (v0.4.18)

• Placement: Renders in the input area next to the model switcher (conversation.input.right slot).
• Four display modes (`composerQuota` setting): off / percent (85%) / bar (40px mini bar, green>30 / amber 10-30 / red <10) / forecast.
• Runway Forecast: A sliding 24h window of remaining-percent samples (up to 192 points) feeds a recency-weighted least-squares burn rate; below 30 min of observation or <1% consumed it stays calibrating…, with no consumption it says no usage. Ready state shows ~4.5h / ~12m.
• Auto-Hide: No indicator for local Ollama or when nothing is active.

14. 🧑‍💻 SUBS Pill & Session Console (v0.4.18)

• Pill in the Session Header: SUBS (N) in the session header actions area with a pool-health LED: green <50% max usage, amber 50-90%, red ≥90%, gray when nothing is connected.
• Modal Console: Clicking the pill opens an in-session modal listing every account (provider #index, connected/not, cooldown, quota %) and a shortcut to the settings card. Closes on outside click, ✕ or Escape.

15. 🫧 Draggable HUD Widget (v0.4.18)

• Floating Bubble on shell.overlay: a 64px circle with an SVG ring gauge of the active subscription balance, mounted via createPortal.
• Drag & Dock: Drag anywhere; it snaps to any screen edge within 24px (peek-style half-hidden until hovered) and remembers its position in localStorage.
• Frosted Panel: Hovering reveals a backdrop-filter: blur(28px) panel listing every account with usage bars. Clicking the bubble refreshes quota data; data also refreshes every 60 s.
• Settings Card Polish (`v0.4.18`): Chevron switched to the core IconChevronDownOutline14 primitive; explicit settings snapshot states (loading / unavailable + Retry) guard against phantom input.

16. ⚡ ClineBot-Inspired UI & Hardened Telemetry (v0.6.6)

• Live Status Badge Bar: Instant latency check to the host (Host online (XX ms)), real-time connected account indicators, and pool size at a glance.
• One-Click Smoke Test (Ping): Test live connectivity to the active upstream subscription provider and measure real round-trip latency.
• Session Telemetry Dashboard: Visual stat cards displaying successful/total requests, average latency, session success rate, and last request activity.
• Curated Models Catalog: Quick preview of supported model families with context windows and capability tags (Vision, Reasoning, Hybrid).
• Non-Blocking Storage: HistoryStore debounces disk persistence asynchronously to prevent blocking the Node.js event loop during high-throughput streaming.

17. 🛡️ Quarantine Management, Live Quota Countdown & In-App Toast Alerts (v0.6.59)

• Manual Quarantine Control (Park & Probe): Directly park active accounts in quarantine (POST /dsh-subscriptions/quarantine/park) for maintenance or pause, or trigger an immediate live warmup probe and instant release (POST /dsh-subscriptions/quarantine/probe) right from the account slot card.
• Dynamic Quota Window Countdown: Live second-by-second countdown timer displayed in the SubsPill session widget and account settings cards, showing exact time remaining until rolling rate-limit windows (five_hour, seven_day, primary_window) reset.
• In-App Toast Alerts (`enableToasts`): Lightweight floating toast alerts in the DSH chat interface notifying you when accounts enter quarantine, recover from cooldowns, or exceed quota safety thresholds.
• Automated Webhook Integration: Instant event notifications dispatched via notifyQuarantineEntered and notifyQuarantineReleased.

25. 🩺 Vendor Auth Doctor, Latency RTT Indicator, Dynamic Model Sync & Client Bundle Relief (v0.6.72)

• Vendor Auth Doctor (#543): Intelligent classification and explanation of provider authentication and connection errors (Cloudflare 403 / Geoblock, expired tokens, revoked sessions, missing model scopes, exhausted quotas). Displays diagnostic verdict with actionable recommendations in the account card.
• Latency RTT Indicator & Fast Ping Probe (#542): Live round-trip time measurement to vendor APIs with color-coded badges (🟢 750ms). Dedicated ping endpoint (POST /dsh-subscriptions/ping) and latency metrics in connection tests.
• Dynamic Model Catalog Discovery & Sync (#541): One-click "Sync Models" button on account cards querying live vendor /v1/models endpoints to discover newly released and subscription-specific models dynamically without waiting for plugin updates.
• Client Bundle Modularization & Store Limit Relief (#540): Reduced lib/client.js bundle size from 217.3 KiB to 57 KiB buffer below the 256 KiB DSH Store ceiling) via createElement aliasing, CSS minification, and dynamic instruction loading.

24. 🛡️ Resilience, Diagnostics & Fallback Enhancements (v0.6.71)

• Cross-Vendor Cascading Fallback & Provider Priority Ordering (#536): Configure fallback ordering across subscription providers with interactive reordering in WebUI.
• 1-Click Connection Smoke Test & Latency Ping (#536): Test individual account connections on the spot with real-time latency badges.
• Live Cooldown Countdown & Availability Toasts (#536): Exact countdown timer for cooled-down accounts and automated toast alerts upon recovery.
• Proactive OAuth Token Heartbeat (#536): Pre-emptive background token refresh before expiry to prevent first-query latency spikes.
• Recent Errors Ring Buffer Inspector (#536): In-memory sanitized log of the last 20 runtime failures in WebUI Diagnostics.

23. 🧠 Antigravity Tiered Models, Tool Sentinel & Stream Resilience (v0.6.69)

• Gemini 3 Tool Replay Sentinel (#534): Injects thoughtSignature: 'skip_thought_signature_validator' on reconstructed tool calls, enabling reliable multi-turn tool calling without Gemini 3 validation failures.
• Tiered Flash Models & Thinking Levels (#534): Exposes Gemini 3.8 and 3.7 Flash High, Medium, and Low thinking levels with upstream *-flash-tiered mapping.
• Stream Resilience & Empty Stream Retry (#534): Idle SSE timeout (30s), empty response detection, and transient stream retry with automatic account rotation.

22. ⚡ xAI Grok RFC 8628 Device Authorization Flow (v0.6.68)

• RFC 8628 Device Code Authorization (GH #17, #532): Native device authorization grant support for xAI Grok. Solves the issue where xAI presents a Grok Build user-code verification page for CLI client IDs without redirecting back to loopback callbacks. Provides direct user code display and automatic token polling.

21. 🛡️ Per-Account Claude Billing Attribution Isolation (v0.6.67)

• Per-Account `cc_turn_index` & `cch` Isolation (#530): Isolates Claude Code billing attribution state (cch session hash and cc_turn_index counter) per subscription account (accountId) in a bounded module Map instead of globalThis, preventing cross-account telemetry mixing in multi-account pools.
• Dynamic `cc_prompt_index` & Kill-Switch: Automatically derives 0-based cc_prompt_index from multi-turn messages history and supports suppression via CLAUDE_CODE_ATTRIBUTION_HEADER=0 or disableBillingHeader: true.

20. 🤖 Native Copilot CLI SDK Mode & Local Tool Calling (v0.6.66)

• Direct Copilot CLI Integration (#508): Native driver copilot-cli.js supporting execution via local copilot / github-copilot-cli binaries with zero network token emulation risk.
• Smart Mode Switching (`copilotMode`): Choose between auto (prefers local CLI with graceful web API fallback), cli (strict CLI SDK execution), and web (direct OAuth/API).
• Multi-Source Credential Detection: Automatically discovers tokens from GitHub CLI (gh hosts.yml), Copilot config files (hosts.json, apps.json), and environment variables (GITHUB_COPILOT_TOKEN, GH_TOKEN).
• Full Tool-Calling & Streaming: Seamless translation of CLI process output into real-time streaming chunks and multi-turn tool-call deltas.

19. 🧠 Session Reasoning Effort Management & Contract Matrix (v0.6.65)

• Session-Scoped Reasoning Effort Control (#505): Dynamically adjust reasoning effort (low, medium, high, max) or disable reasoning (off) per conversation session via REST endpoints (GET, POST, DELETE /dsh-subscriptions/session-reasoning).
• Model-Switch Invariant & Safety Guard: Automatic suppression of reasoning parameters when switching from a reasoning model (e.g. o1) to a standard model (e.g. gpt-4o), avoiding upstream HTTP 400 parameter errors.
• Extended Multi-Vendor Capability: Native reasoning support across Codex (o1, o3), Claude (claude-3-7-sonnet*, claude-4.6+ thinking tokens & budgets), Antigravity/Gemini (thinkingConfig), Grok (grok-3-mini), and Kimi (k1.5).
• Comprehensive Adapter Contract Matrix (#521): Automated offline wire contract verification (test/contract-matrix.test.mjs) testing 8 provider