dsh-key-limits

📦 @goodandready/dsh-key-limits

---

⚡ Overview & The Problem

AI developers and engineers frequently work across multiple LLM providers, corporate subscriptions, and token plan tiers simultaneously (such as OpenCode GO, Ollama Cloud, Qwen Cloud, Kimi, GLM, MiniMax, Cline, DeepSeek, OpenRouter, and Command Code).

Without ambient, real-time quota tracking inside DeepSeek Harness (DSH):

• Conversations crash unexpectedly when rolling 5-hour limits or monthly quotas deplete mid-generation.
• Users have no instant visibility into which subscription key is currently bound to the active chat session.
• Switching tabs to check individual vendor dashboards disrupts developer workflow.

dsh-key-limits solves this by delivering ambient, distraction-free quota monitoring directly within the DSH Web UI. It focuses strictly on quota limits and subscription balances without heavy accounting ledgers, historical spending databases, or complex analytics.

---

🏗️ Architecture & Data Flow

graph LR
  subgraph Client ["DSH Web Client"]
    FC["FloatChip (Draggable Badge)"]
    CB["ActiveKeyButton (Composer Bar)"]
    SC["Settings Card (Plugin Slot)"]
    M["Modals (All Limits & One Limit)"]
  end

  subgraph Backend ["Cordis Plugin Backend"]
    Router["HTTP API Router (/dsh-key-limits)"]
    CredStore["Encrypted Credential Storage"]
    Updater["Loopback Plugin Updater"]
  end

  subgraph Providers ["AI Providers & Services"]
    P1["OpenCode GO / Ollama / Qwen"]
    P2["Command Code / Cline / GLM"]
    P3["DeepSeek / OpenRouter / MiniMax"]
    NPM["npmjs.org Registry"]
  end

  FC -->|Click| M
  CB -->|Click| M
  M -->|Poll Quotas (60s)| Router
  SC -->|Save Credentials| Router
  SC -->|Trigger Update| Updater
  Router --> CredStore
  Router -->|Parallel 12s Abort| P1
  Router -->|Parallel 12s Abort| P2
  Router -->|Parallel 12s Abort| P3
  Updater -->|Loopback Check / Install| NPM

---

✨ Full Feature Breakdown

1. Floating Quota Chip (FloatChip)

• Persistent Viewport Overlay: Displays the lowest remaining quota percentage across all active keys (or total account count).
• Draggable with Boundary Clamping: Smooth mouse and touch dragging that prevents the chip from leaving the visible screen. Coordinates persist automatically in localStorage.
• One-Click Overview: Clicking the chip opens the All Limits Modal showing every configured account, plan, rolling windows, and expiration dates.

2. Composer Bar Key Status (ActiveKeyButton)

• Injected directly into the message input area (conversation.composer.bar, priority 10).
• Automatically inspects the active conversation session to detect the bound provider model.
• Shows the remaining quota percentage or monetary balance for that exact model.
• Clicking the button opens the One Limit Modal dedicated to the active account.

3. Account Reordering & Active on Top

• Custom Account Order (order): In settings, arrange the display sequence of accounts using intuitive Up/Down controls (▲ / ▼).
• Active Always on Top (activeOnTop): Automatically moves the account currently in use by the active conversation to the top of the list. Enabled by default.

4. Humanized Reset Countdown (fmtReset)

• Durations exceeding 24 hours display days, hours, and minutes (e.g., 5d 5h 19m).
• Durations under 24 hours omit days for concise reading (e.g., 4h 59m).
• Expired windows immediately indicate refresh status.

5. Calm, Professional UI Design

• Consistent 12px vertical spacing between cards eliminates cramped layouts and overlapping borders.
• Calm neutral tones for healthy (>30%) quota states, reserving amber and red strictly for warning (<30%) and critical (<15%) levels.
• Sleek 5px progress bars that blend into the native DSH theme.

6. Pool Health & Predictive Analytics

• Pool Health Indicator: Ambient breakdown of provider account pools (healthy / warning / exhausted), immediately surfacing accounts experiencing quota exhaustion or upstream timeouts.
• Burn Rate & Velocity: Real-time hourly consumption speed tracking (%/h) and automatic time-to-depletion projection (~X.X h left) derived from 24-hour rolling browser usage snapshots.
• Ambient Reset Countdown: Floating chip tooltip and account tags display humanized countdown timers to the nearest quota reset window (e.g., Resets in 2h 15m).

7. Docked Mode, Hotkey & Low-Quota Alerts

• Docked Mode: One-click pin button in the floating chip docks it neatly into the bottom-right corner, locking movement and saving window space.
• Global Hotkey Alt+K: Instant access to the Limits Hub from any view or workflow without reaching for the mouse.
• Danger Toast Warning: Ambient alert appears when the active key dips below 15% quota, preventing surprise generation cutoffs.

8. Encrypted Backup & Batch Refresh

• Encrypted Export & Import: Export all configured keys and subscriptions into a password-protected AES-256-GCM encrypted backup file for easy migration between devices or profiles.
• Refresh All: One-click forced quota refresh in the Limits Hub with spinning progress animation and concurrency-limited batch querying.

9. Built-in One-Click Updater

• Check for updates directly within the settings card.
• Installs the exact published package from npm without manual terminal intervention.
• Protected against non-loopback or cross-origin requests.

10. Security & Storage Architecture

• Isolated Secret Persistence: Plaintext API keys and sensitive session cookies (e.g. Ollama Cloud) are stored exclusively in the host DSH credentials service. The local subs.json file only contains non-sensitive metadata and references.
• Strict File Permissions: The subs.json database and temporary swap files are enforced with strict POSIX 0600 file modes, preventing multi-user local inspection.
• Fail-Closed Memory Hygiene: The in-memory cache purges sensitive secrets before resolving, ensuring revoked or deleted credentials do not persist in background polling or leak into backup exports.
• Redirect Protection: Provider API fetchers enforce redirect: 'error', preventing sensitive authorization headers (x-api-key, Bearer tokens) from leaking cross-origin across HTTP 301/302/307 redirects.
• Transactional Persistence: Disk write failures automatically roll back in-memory state and return standard HTTP 500 responses rather than reporting false success.

---

🔌 Supported Providers

---

📦 Quick Installation

Install the official package into your active DSH profile:

dsh plugin --profile web add @goodandready/dsh-key-limits

Restart DSH Web:

dsh web --profile web

---

⚙️ Configuration Reference

# Primary configuration: Settings -> Plugins -> Key Limits, or profile plugin config.
# Legacy import: ~/.dsh/profiles/web/settings.yaml
plugins:
  '@goodandready/dsh-key-limits':
    storageDir: ~/.dsh/storages/dsh-key-limits
    refreshHours: 24
    ui:
      floatChip: true
      composerBar: true
      activeOnTop: true
      order: []

Parameter Details

---

🌐 REST API Endpoints

---

🛠️ Development & Testing

Note: The published npm package and release tarball carry only runtime production files (lib/, cordis.patch.yml, docs, and license). Development sources (src/client/, test/, and build scripts) are maintained in the source repository. To run automated tests or rebuild the client bundle, clone the development repository.

# Build unified client bundle from src/client/ into lib/client.js
npm run build:client

# Run automated offline test suite
npm test

Directory Structure

.
├── lib/
│   ├── index.js                  # Cordis plugin entrypoint & HTTP routes
│   ├── client.js                 # Built client bundle
│   ├── cards.js                  # Card generation and formatting
│   ├── subs.js                   # Provider quota manager & normalization
│   ├── provider-fetchers.js       # Core quota fetchers & HTML parsers
│   ├── provider-extra-fetchers.js # Extended quota fetchers (SiliconFlow, Anthropic, Groq, Gemini)
│   ├── crypto-backup.js          # AES-256-GCM passphrase export & import
│   ├── paths.js                  # Path resolution helpers
│   └── plugin-updater.js         # Secure loopback updater
├── src/client/                   # Source modules for browser client
│   ├── 01-prelude.js             # Scoped CSS & React setup
│   ├── 02-locale.js              # Multi-language dictionaries (en, zh; ru via dsh-russian-lang)
│   ├── 03-format.js              # Humanized countdowns & color classes
│   ├── 04-modals.js              # AllLimitsModal & OneLimitModal
│   ├── 05-bar.js                 # Composer bar ActiveKeyButton
│   ├── 06-float.js               # Draggable FloatChip
│   ├── 07-settings.js            # Settings card, reorder list & updater
│   └── 08-apply.js               # DSH plugin bootstrap & slot registrations
├── cordis.patch.yml              # Cordis plugin declaration
└── test/                         # Test suite

---

📄 License

MIT © GooDAnDReaDY