📦 @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. 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.

---

🔌 Supported Providers

Provider ID	Name	Quota Windows	Authentication
commandcode	Command Code	Rolling 5h / Weekly / Monthly (GOAT, Pro, Max plans)	API key (user_... or token)
opencode-go	OpenCode GO	Rolling 5h / Weekly / Monthly	Session cookie (auth) & Workspace ID
ollama	Ollama Cloud	Session / Weekly / Monthly	API key & Session cookie
qwen	Qwen Cloud	5h / 1-Week Token Plans	Session cookie & optional sec_token
kimi	Kimi for Coding	Weekly Quota Limit	API key (sk-kimi-...)
glm	GLM (Z.ai)	Daily / Monthly Quota	API key
minimax	MiniMax Coding Plan	Coding Plan Quota	API key (sk-cp-...)
cline	Cline	5h / Weekly / Monthly	Bearer API token
deepseek	DeepSeek	Balance ($ / ¥)	API key (sk-...)
openrouter	OpenRouter	Balance ($ credits remaining)	API key (sk-or-...)

---

📦 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 (settings.yaml)

# ~/.dsh/profiles/web/settings.yaml
plugins:
  '@goodandready/dsh-key-limits':
    storageDir: ~/.dsh/storages/dsh-key-limits
    refreshIntervalMs: 60000
    activeOnTop: true
    order: []

Parameter Details

Parameter	Type	Default	Description
storageDir	string	~/.dsh/storages/dsh-key-limits	Directory where subscription metadata and cached cards are stored.
refreshIntervalMs	number	60000 (1 min)	Polling frequency for refreshing quota windows from providers.
activeOnTop	boolean	true	Automatically pins the account matching the active chat session to the top of lists.
order	string[]	[]	User-defined sequence of subscription IDs for custom card ordering.

---

🛠️ Development & Testing

# Build unified client bundle from src/client/
npm run build:client

# Run automated tests
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 fetchers & normalization
│   ├── 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)
│   ├── 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