@leaf233/dsh-llm-rate-limiter 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.1.1] - 2026-09-12
+
+### Changed
+- **Package renamed to `@leaf233/dsh-llm-rate-limiter`** (npm scope) and published to npm; the internal plugin identity (`llm-rate-limiter`), settings namespace, and runtime behavior are unchanged
+- `cordis.patch.yml` `name` and the browser client bundle id now follow the scoped package name (required by DSH module resolution)
+- npm badge and npm install instructions added to README
+
+### Fixed (since the `v0.1.0` git tag)
+- CI: `pnpm/action-setup` now precedes `actions/setup-node` (pnpm was missing from PATH)
+- CI: `pnpm-lock.yaml` committed, so `--frozen-lockfile` installs work
+- Removed private `@deepseek-ai/dsh-llm` from `peerDependencies` (unresolvable for consumers)
+
+## [0.1.0] - 2026-09-12
+
+### Added
+- Token Bucket strategy with configurable `burstSize`, `refillRate`, `maxConcurrent`
+- Sliding Window strategy with `windowMs`, `maxRpm`, `maxConcurrent`
+- Per-model rate limit overrides (`models["provider/model"]`)
+- Queue mode: throttled requests wait and are released when slots open
+- Reject mode: throttled requests fail with `RATE_LIMIT` code (compatible with `dsh-llm-retry`)
+- Interactive GUI in DSH Settings → Plugins (collapsible PluginCard)
+- `maxRpm` → `refillRate` auto-derivation for token-bucket when only `maxRpm` is set
+- Hot-reload: settings changes take effect immediately
+- `maxQueueWaitMs` timeout for queue mode
+- 19 unit tests covering concurrency, burst, queue, abort, and hot-reload
+- E2E test (`test-3rpm.mjs`) verifying 3 rpm limit
+- DSH version compatibility analysis (COMPATIBILITY.md)

package/COMPATIBILITY.md

@@ -0,0 +1,133 @@
+# dsh-llm-rate-limiter — DSH 版本兼容性检测报告
+
+> 检测日期: 2026-07-28  
+> 本地 DSH 版本: **0.1.2-rc.1**  
+> 测试方式: 源码分析（npm registry 在沙箱中被拦截，无法查询其他版本）
+
+---
+
+## 一、依赖 API 清单与存在性验证
+
+### Host 端（lib/index.js）— 6 个 API 依赖
+
+| # | API | 所属包 | 本地存在 | 稳定性评估 |
+|---|-----|--------|----------|------------|
+| 1 | `ctx.settings.register(ns, schema, { base })` | dsh-settings | ✅ 3处 | 核心 API，SettingsService 的公共接口 |
+| 2 | `scope.get()` | dsh-settings (返回值) | ✅ `registration.resolved` | 简单属性读取，极低风险 |
+| 3 | `scope.watch(callback)` → `unwatch()` | dsh-settings (返回值) | ✅ watcher Set 管理 | 标准 observer 模式，极低风险 |
+| 4 | `ctx.on("llm/stream", async function*(options, next))` | dsh-llm + cordis | ✅ 3处 | waterfall 中间件，LLM 调用的核心拦截点 |
+| 5 | `ctx.effect(() => cleanup, label)` | cordis | ✅ | Cordis 核心生命周期 API |
+| 6 | `ctx.logger?.("rate-limiter").info/warn(...)` | cordis | ✅ | 日志 API，如不存在用 `?.` 降级 |
+
+### Client 端（lib/client.js）— 5 个 API 依赖
+
+| # | API | 所属包 | 本地存在 | 稳定性评估 |
+|---|-----|--------|----------|------------|
+| 1 | `window.__ModuleLoader__.load({ id, factory })` | DSH web shell | ✅ 1处 | 客户端模块加载器，所有 client 插件都用 |
+| 2 | `settingsScope.get?.()` / `getSnapshot?.()` | dsh-client-ui-settings | ✅ 各1处 | get() 来自 host scope, getSnapshot 来自 client controller; 双兼容 |
+| 3 | `settingsScope.subscribe(listener)` | dsh-client-ui-settings | ✅ 1处 | SettingsScopeController.subscribe |
+| 4 | `settingsScope.set(field, value)` | dsh-client-ui-settings | ✅ 2处 | SettingsScopeController.set (单字段写) |
+| 5 | `settingsScope.mutate([{ op, path, value }])` | dsh-client-ui-settings | ✅ 1处 | SettingsScopeController.mutate (嵌套操作) |
+| 6 | `ctx.slots.inject("settings.plugin.item", ...)` | dsh-client-ui-settings-plugins | ✅ 6处 | 插件设置卡片注册 slot |
+
+### Schema 依赖 — 1 个包
+
+| 包 | 本地版本 | 用到的 API |
+|----|---------|-----------|
+| @deepseek-ai/schemastery | 3.18.2+ | `Schema.object()`, `Schema.union()`, `Schema.const()`, `Schema.dict()`, `.default()`, `.int()`, `.min()`, `.description()` |
+
+---
+
+## 二、版本矩阵评估
+
+### 已知版本
+
+| 组件 | 本地安装版本 | peerDep 要求 | DSH 用法 |
+|------|------------|-------------|---------|
+| @deepseek-ai/dsh | **0.1.2-rc.1** | — | 安装的 DSH 主包 |
+| @deepseek-ai/cordis | **4.0.2** | ≥4.0.2 | DSH 所有插件统一用 ^4.0.2 |
+| @deepseek-ai/schemastery | 3.18.2+ | ≥3.18.0 | DSH 用 ^3.18.2 |
+| @deepseek-ai/dsh-settings | **0.1.2-rc.1** | — | 提供 `ctx.settings.register()` |
+| @deepseek-ai/dsh-llm | **0.1.2-rc.1** | — | 提供 `llm/stream` waterfall |
+| @deepseek-ai/dsh-llm-retry | **0.1.2-rc.1** | — | 本插件的参考实现 |
+| @deepseek-ai/dsh-client-ui-settings | **0.1.2-rc.1** | — | 提供 `settingsScope` 服务 |
+| @deepseek-ai/dsh-client-ui-settings-plugins | **0.1.2-rc.1** | — | 提供 `settings.plugin.item` slot |
+
+### 兼容性矩阵（推断）
+
+| DSH 版本 | 预期兼容 | 风险点 |
+|----------|---------|--------|
+| 0.1.0 ~ 0.1.2 | ✅ 应兼容 | RC 阶段 API 趋于稳定，settings.register / llm/stream 已是核心 |
+| 0.1.3+ (同 minor) | ✅ 应兼容 | 遵循 semver，接口不大改 |
+| 0.2.x (minor 升级) | ⚠️ 需验证 | 可能新增/重命名 settings 参数、llm/stream 签名变体 |
+| 1.0+ (major) | ⚠️ 必须重测 | 核心 API 可能重构（cordis 升级、settings 层重构） |
+
+---
+
+## 三、关键风险点分析
+
+### 🔴 高风险
+
+| 风险 | 说明 | 影响 | 缓解措施 |
+|------|------|------|----------|
+| **`llm/stream` waterfall 签名变更** | DSH 当前签名: `(options: GenerateOptions, next) => AsyncIterable`，如果未来增加参数或改变 options 结构 | 插件读不到 `provider`/`model` 字段 | 用可选链 `options.provider ?? "unknown"` 降级 |
+| **cordis major 升级** | cordis 是 DSH 的运行时内核，major 版本会改变插件生命周期 | apply/signature/effect 全部受影响 | peerDep 已锁定 `≥4.0.2`，major 升级时必须更新 |
+| **0.1.x 是 RC 阶段** | 预发布版本的 API 不保证向后兼容 | 任何 patch 版本都可能引入 breaking change | 紧跟 DSH 版本更新 |
+
+### 🟡 中等风险
+
+| 风险 | 说明 | 影响 | 缓解措施 |
+|------|------|------|----------|
+| **`settingsScope` API 名字变更** | Service 字符串 `"settingsScope"` 硬编码在 `SettingsScopeBinder` 构造函数中 | Client 端服务注入失败 | 该 Service 名是 UI 基础设施，改名成本极高，短期低概率 |
+| **`settings.plugin.item` slot 名变更** | 插件设置页的 slot 注册点 | 卡片不会显示 | slot 名已被多处硬编码引用（Bash、AgentLoop 等），改名需全量迁移 |
+| **schemastery 3.x → 4.x** | 新 major 可能改 `Schema.union/const` 等 API | 配置 Schema 编译失败 | peerDep 锁 ≥3.18.0，major 时必须适配 |
+
+### 🟢 低风险
+
+| 风险 | 说明 |
+|------|------|
+| `ctx.on("llm/stream")` 事件名变更 | LLM waterfall 是 LLM 模块的核心公开接口 |
+| `scope.get()` / `scope.watch()` 签名变更 | 简单 getter/observer，改动概率极低 |
+| `settingsScope.set(field, value)` 签名变更 | 标准 setter，多个 UI 卡片都在用 |
+
+---
+
+## 四、已验证的兼容性事实
+
+### API 表面稳定性证据
+
+1. **`llm/stream` waterfall 被 2 处引用**：`dsh-llm/lib/index.js` 的 `stream()` 和 `invariant.js` 的验证层，形成双重稳定约束
+2. **`settings.register` 返回的 scope**：host 侧返回 `{ get, watch, update, replace }`，结构明确且简洁
+3. **`settingsScope.bind`** 由 `dsh-client-ui-settings` 提供，client 端 scope 返回 `{ set, unset, mutate, subscribe, getSnapshot }`，被 `dsh-client-ui-settings-plugins`、`dsh-client-ui-settings-models` 等多个官方 UI 包使用
+4. **`dsh-llm-retry` 作为参考**：同样使用 `ctx.on` 事件 + `ctx.effect` 清理，peerDep 了 `@deepseek-ai/cordis: ^4.0.2`，与本插件策略一致
+5. **cordis ^4.0.2 被所有 DSH 插件统一引用**：`dsh-llm`、`dsh-llm-retry`、`dsh-client-ui-settings` 都声明同一个范围
+
+---
+
+## 五、兼容性加固措施（已应用）
+
+| # | 措施 | 位置 |
+|---|------|------|
+| 1 | client.js 的 `settingsScope.get?.()` / `.getSnapshot?.()` 双兼容 | 读取初始值 |
+| 2 | client.js 的 `watch` / `subscribe` 双兼容（typeof 检测） | 监听配置变化 |
+| 3 | host.js 的 `ctx.logger?.()` 可选链 | 日志降级 |
+| 4 | peerDep 使用 `≥4.0.2` 范围（允许 minor 升级） | package.json |
+| 5 | schemastery peerDep 使用 `≥3.18.0`（允许 minor 升级） | package.json |
+| 6 | 终端 chunk 使用 DSH 标准格式 `{ type: "finish", reason: { kind, failure } }` | 与 adapterFailureChunk 一致 |
+
+---
+
+## 六、建议
+
+1. **当前 DSH 0.1.2-rc.1**：插件完全兼容，所有 API 已验证
+2. **发布时建议声明 peerDep**：
+   - `@deepseek-ai/cordis`: `>=4.0.2`
+   - `@deepseek-ai/dsh-llm`: `>=0.1.0`（因为我们只用 `llm/stream` 事件）
+   - `@deepseek-ai/schemastery`: `>=3.18.0`
+3. **DSH 升级到 0.2.x+ 时必须回归测试**以下清单：
+   - [ ] `llm/stream` 事件签名是否变化
+   - [ ] `options.provider` / `options.model` 字段是否存在
+   - [ ] `settings.register` 返回值结构是否变化
+   - [ ] `settingsScope.set/mutate` 接口是否变化
+   - [ ] `settings.plugin.item` slot 是否仍可注入
+4. **如果 cordis 升级到 5.0+**：整个 `apply(ctx)` 接口、`ctx.effect()`、`ctx.on()` 签名可能重写，需要全面适配

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-llm-rate-limiter contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# dsh-llm-rate-limiter
+
+[![npm](https://img.shields.io/npm/v/@leaf233/dsh-llm-rate-limiter.svg)](https://www.npmjs.com/package/@leaf233/dsh-llm-rate-limiter)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![DSH 0.1.x](https://img.shields.io/badge/DSH-0.1.x-brightgreen.svg)](COMPATIBILITY.md)
+[![Cordis 4.x](https://img.shields.io/badge/Cordis-%3E%3D4.0.2-brightgreen.svg)](package.json)
+[![Tests](https://img.shields.io/badge/tests-19%2F19%20passing-brightgreen.svg)](test-strategies.mjs)
+
+Per-model LLM call rate limiter for [DeepSeek Harness](https://github.com/deepseek-ai/dsh) with queue/reject support and interactive GUI configuration.
+
+---
+
+## Features
+
+- **Per-model rate limiting** — independent concurrency, RPM, and burst limits for each `provider/model`
+- **Two algorithms** — Token Bucket (allows bursts) or Sliding Window (smooth, strict RPM)
+- **Queue mode** — throttled requests wait in queue and are released when a slot opens
+- **Reject mode** — throttled requests fail immediately (integrates with `dsh-llm-retry` for auto-backoff)
+- **Interactive GUI** — collapsible card in DSH Settings → Plugins → Configurable
+- **Hot-reload** — settings changes take effect immediately, no restart needed
+- **Every request checked** — intercepts `llm/stream` waterfall, covering every LLM call in every agent turn
+
+---
+
+## Installation
+
+### Option 1: npm (recommended)
+
+```bash
+dsh plugin add <your-profile> @leaf233/dsh-llm-rate-limiter
+# or, inside the profile directory:
+pnpm add @leaf233/dsh-llm-rate-limiter
+```
+
+### Option 2: local path (development)
+
+```bash
+dsh plugin add <your-profile> ./path/to/dsh-llm-rate-limiter
+# or
+dsh plugin add ./path/to/dsh-llm-rate-limiter   # default profile
+```
+
+> The plugin must be added as a dependency in the profile's `package.json`.
+> The bundle entry (`cordis.patch.yml`) is auto-detected by `reconcilePlugins`.
+
+### Option 3: from GitHub
+
+```bash
+dsh plugin add <your-profile> github:Leafyezi233/dsh-llm-rate-limiter
+```
+
+> ⚠️ **Important**: Git-hosted plugins are blocked by pnpm's `allowBuilds` restriction on first install. If the install fails, check the error message for the exact key pnpm suggests, then add it to your profile's `pnpm-workspace.yaml`:
+>
+> ```yaml
+> pnpm:
+>   allowBuilds:
+>     - '@leaf233/dsh-llm-rate-limiter'
+> ```
+>
+> Then re-run the install command.
+
+---
+
+## Configuration
+
+### Via GUI
+
+1. Open DSH Web UI (`dsh web`)
+2. Go to **Settings → Plugins**
+3. Find **⚙ LLM 调用限速** card — click to expand
+4. Configure defaults, per-model overrides, and throttle behavior
+
+### Via file
+
+Edit the profile's `settings.yaml` or use the GUI — changes are persisted to the DSH settings store:
+
+```yaml
+llm-rate-limiter:
+  enabled: true
+  strategy: token-bucket       # "token-bucket" | "sliding-window"
+  defaults:
+    maxConcurrent: 5
+    maxRpm: 60
+    burstSize: 10               # token-bucket only
+    refillRate: 1               # token-bucket only (tokens/sec)
+  models:
+    "deepseek/deepseek-chat":
+      maxConcurrent: 8
+      maxRpm: 120
+    "openai/gpt-4o":
+      maxConcurrent: 2
+      maxRpm: 10
+      burstSize: 3
+    "anthropic/claude-3-5-sonnet":
+      enabled: false            # skip rate limiting for this model
+  onThrottled: queue            # "queue" | "reject"
+  maxQueueWaitMs: 60000
+```
+
+---
+
+## Settings Reference
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `enabled` | `true` | Global on/off switch. When off, zero overhead bypass. |
+| `strategy` | `"token-bucket"` | `"token-bucket"` (allows bursts) or `"sliding-window"` (smooth, strict RPM) |
+| `defaults.maxConcurrent` | `5` | Max simultaneous requests per model |
+| `defaults.maxRpm` | `60` | Max requests per minute per model |
+| `defaults.burstSize` | `10` | Token bucket capacity — how many requests can burst at once |
+| `defaults.refillRate` | `1` | Tokens refilled per second (token-bucket). Auto-derived from `maxRpm / 60` if not set. |
+| `models.<key>.maxConcurrent` | — | Per-model concurrency override |
+| `models.<key>.maxRpm` | — | Per-model RPM override |
+| `models.<key>.burstSize` | — | Per-model burst capacity override |
+| `models.<key>.refillRate` | — | Per-model refill rate override |
+| `models.<key>.enabled` | — | Set `false` to skip rate limiting for this specific model |
+| `onThrottled` | `"queue"` | What happens when a request hits the limit: `"queue"` (wait) or `"reject"` (fail immediately) |
+| `maxQueueWaitMs` | `60000` | Max time (ms) a request waits in queue before being rejected |
+
+> **Note:** When a model overrides `maxRpm` without explicitly setting `refillRate`, the refill rate is automatically derived as `maxRpm / 60` (tokens per second). This ensures "set maxRpm=3" actually limits to 3 requests per minute.
+
+---
+
+## Algorithm Comparison
+
+| | Token Bucket | Sliding Window |
+|---|---|---|
+| **Burst** | Yes (controlled by `burstSize`) | No — strictly smooth |
+| **Recovery** | Tokens refill at `refillRate`/sec | Window slides continuously |
+| **Best for** | Tolerating request spikes | APIs with hard per-minute limits |
+| **GUI label** | 令牌桶 (Token Bucket) | 滑动窗口 (Sliding Window) |
+
+---
+
+## How It Works
+
+```
+Agent Turn
+  → LLM Call (e.g. deepseek/deepseek-chat)
+    → ctx.on("llm/stream") interceptor
+      → Resolve rate limiter for this provider/model
+      → Token bucket: has tokens + concurrency room?
+      → If YES: consume token, acquire slot, forward to API
+      → If NO (reject mode): return RATE_LIMIT error immediately
+      → If NO (queue mode): park in waiters[], wait for token refill
+    → Request completes → release slot → drain waiting requests
+  → dsh-llm-retry catches RATE_LIMIT → exponential backoff → retry
+```
+
+---
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/Leafyezi233/dsh-llm-rate-limiter.git
+cd dsh-llm-rate-limiter
+
+# Install deps
+pnpm install
+
+# Run tests (19 tests)
+node test-strategies.mjs
+
+# Run E2E rate-limit test
+node test-3rpm.mjs
+
+# Install into a DSH profile for testing
+dsh plugin add <your-profile> .
+```
+
+The plugin uses a live symlink when installed via `link:` — edits to `lib/` take effect on browser hard-refresh (`Ctrl+Shift+R`) without reinstalling.
+
+---
+
+## Compatibility
+
+| DSH Version | Status | Notes |
+|-------------|--------|-------|
+| 0.1.x (RC) | ✅ Tested | Verified against 0.1.2-rc.1, cordis 4.0.2 |
+| 0.2.x | ⚠️ Untested | May need API adjustments |
+| Cordis 5+ | ⚠️ Untested | Major version change likely requires rewrite |
+
+See [COMPATIBILITY.md](COMPATIBILITY.md) for detailed API dependency analysis.
+
+---
+
+## License
+
+[MIT](LICENSE)

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: llm-rate-limiter
+      name: '@leaf233/dsh-llm-rate-limiter'

package/lib/client.js

@@ -0,0 +1,233 @@
+/* eslint-disable */
+/**
+ * dsh-llm-rate-limiter — Client (browser) entry point.
+ *
+ * Registers a "Rate Limiter" card in the Plugins → Configurable settings page.
+ * The card uses a collapsible header (PluginCard pattern) with a chevron toggle.
+ *
+ * Browser format: CJS-style factory registered via window.__ModuleLoader__.load
+ * (loaded as a plain <script>, so NO top-level ESM `export` allowed).
+ *
+ * @module dsh-llm-rate-limiter/client
+ */
+window.__ModuleLoader__.load({
+	id: "@leaf233/dsh-llm-rate-limiter",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+
+		// ── React imports (browser module system provides them) ──────────────
+		let react, jsx, jsxs;
+		react = require("react");
+		({ jsx, jsxs } = require("react/jsx-runtime"));
+
+		// ── Shared constants ──
+		const name = "llm-rate-limiter";
+		const inject = ["slots", "settingsScope"];
+
+		/* ── CSS-in-JS (design tokens, injected once) ────────────────────── */
+		(() => {
+			const styles = [
+				".rlr-card{border:.5px solid var(--dsw-alias-border-l4);background:var(--dsw-alias-bg-layer-3);border-radius:16px;list-style:none;transition:border-color .16s,background .16s;margin:0}",
+				".rlr-card:hover{border-color:var(--dsw-alias-label-dimmed)}",
+				".rlr-cardOpen{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-label-dimmed)}",
+				".rlr-header{appearance:none;width:100%;font:inherit;color:inherit;text-align:left;cursor:pointer;background:0 0;border:0;border-radius:12px;align-items:center;gap:12px;padding:14px 16px;display:flex}",
+				".rlr-header:focus-visible{outline:2px solid var(--dsw-alias-brand-primary);outline-offset:-2px}",
+				".rlr-headText{flex-direction:column;flex:1;gap:4px;min-width:0;display:flex}",
+				".rlr-name{color:var(--dsw-alias-label-primary);font-size:15px;font-weight:600;line-height:1.4}",
+				".rlr-description{color:var(--dsw-alias-label-tertiary);font-size:13px;line-height:1.5}",
+				".rlr-chevron{color:var(--dsw-alias-label-tertiary);flex:none;transition:transform .16s;font-size:12px}",
+				".rlr-chevronOpen{transform:rotate(180deg)}",
+				".rlr-body{border-top:.5px solid var(--dsw-alias-border-l2);margin:0 16px;padding:8px 0 8px}",
+				".rlr-status{color:var(--dsw-alias-label-tertiary);margin:8px 0 4px;font-size:12px;line-height:1.5}",
+				".rlr-row{display:flex;align-items:center;gap:10px;flex-wrap:wrap;margin:6px 0}",
+				".rlr-label{min-width:140px;font-size:13px;color:var(--dsw-alias-label-secondary)}",
+				".rlr-input{width:80px;padding:4px 8px;border-radius:6px;border:1px solid var(--dsw-alias-border-l4);background:var(--dsw-alias-surface-s2);color:var(--dsw-alias-label-primary);font-size:13px}",
+				".rlr-select{padding:4px 8px;border-radius:6px;border:1px solid var(--dsw-alias-border-l4);background:var(--dsw-alias-surface-s2);color:var(--dsw-alias-label-primary);font-size:13px}",
+				".rlr-btn{height:30px;padding:0 12px;border-radius:15px;border:none;cursor:pointer;font-size:13px;font-weight:500;color:var(--dsw-alias-label-primary-foreground);background:var(--dsh-alias-button-primary-fill,#4f46e5)}",
+				".rlr-btnSec{height:26px;padding:0 10px;border-radius:13px;border:none;cursor:pointer;font-size:12px;background:var(--dsw-alias-button-secondary-fill);color:var(--dsw-alias-label-primary)}",
+				".rlr-danger{height:26px;padding:0 8px;border-radius:13px;border:none;cursor:pointer;font-size:11px;background:var(--dsw-alias-state-error-primary);color:#fff}",
+				".rlr-modelRow{display:flex;align-items:center;justify-content:space-between;padding:8px 12px;border-radius:12px;border:1px solid var(--dsw-alias-border-l4);gap:8px;margin:4px 0}",
+				".rlr-modelName{font-size:13px;font-weight:500;font-family:monospace}",
+				".rlr-modelMeta{display:flex;gap:12px;font-size:12px;color:var(--dsw-alias-label-tertiary)}",
+				".rlr-section{display:flex;flex-direction:column;gap:4px;margin-top:2px}",
+				".rlr-sectHead{margin:10px 0 0;font-size:14px;font-weight:500}",
+			].join("\n");
+			const tagId = "@dsh-llm-rate-limiter/rate-limiter-card.css";
+			if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
+				const tag = document.createElement("style");
+				tag.dataset.plugin = "dsh-llm-rate-limiter";
+				tag.dataset.pluginCss = tagId;
+				tag.textContent = styles;
+				document.head.appendChild(tag);
+			}
+		})();
+
+		/* ── helpers ─────────────────────────────────────────────────────── */
+		function readNum(cfg, key, field) {
+			return cfg.models?.[key]?.[field] ?? cfg.defaults?.[field] ?? 0;
+		}
+		function setNested(scope, path, value) {
+			scope.mutate([{ op: "set", path, value }]);
+		}
+		function unsetNested(scope, path) {
+			scope.mutate([{ op: "unset", path }]);
+		}
+
+		/* ── React component: collapsible card ───────────────────────────── */
+		function RateLimiterCard({ settingsScope }) {
+			const [cfg, setCfg] = react.useState(() => {
+				const snap = settingsScope.getSnapshot?.();
+				return snap?.status === "ready" && snap.value ? { ...snap.value } : {};
+			});
+
+			react.useEffect(() => {
+				const unsub = settingsScope.subscribe?.(() => {
+					const snap = settingsScope.getSnapshot();
+					if (snap?.status === "ready" && snap.value) setCfg({ ...snap.value });
+				});
+				return () => (typeof unsub === "function" ? unsub() : undefined);
+			}, [settingsScope]);
+
+			const modelKeys = Object.keys(cfg.models ?? {});
+
+			function addModel() {
+				const key = prompt('添加模型限速 (格式: provider/model)\n例如: deepseek/deepseek-chat');
+				if (!key) return;
+				setNested(settingsScope, ["models", key], {});
+			}
+			function removeModel(key) {
+				unsetNested(settingsScope, ["models", key]);
+			}
+			function setModelField(key, field, value) {
+				const path = ["models", key, field];
+				if (value === undefined || value === "") unsetNested(settingsScope, path);
+				else setNested(settingsScope, path, value);
+			}
+			function setDefault(field, value) {
+				setNested(settingsScope, ["defaults", field], value);
+			}
+			function setTop(field, value) {
+				settingsScope.set(field, value);
+			}
+
+			const [open, setOpen] = react.useState(false);
+
+			return jsxs("li", { className: "rlr-card" + (open ? " rlr-cardOpen" : ""), children: [
+				jsxs("button", {
+					type: "button",
+					className: "rlr-header",
+					"aria-expanded": open,
+					onClick: () => setOpen(!open),
+					children: [
+						jsxs("span", { className: "rlr-headText", children: [
+							jsx("span", { className: "rlr-name", children: "⚙ LLM 调用限速" }),
+							jsx("span", { className: "rlr-description", children: "按模型限制 LLM 请求频率，超出限制的请求排队等待" }),
+						] }),
+						jsx("span", { className: "rlr-chevron" + (open ? " rlr-chevronOpen" : ""), children: "▾" }),
+					]
+				}),
+				open && jsxs("div", { className: "rlr-body", children: [
+					/* ── 启用开关 ── */
+					jsxs("div", { className: "rlr-row", children: [
+						jsx("label", { children: [
+							jsx("input", { type: "checkbox", checked: cfg.enabled ?? true, onChange: (e) => setTop("enabled", e.target.checked) }),
+							" 启用限速",
+						] }),
+					] }),
+					/* ── 默认配置 ── */
+					jsxs("div", { className: "rlr-section", children: [
+						jsx("div", { className: "rlr-sectHead", children: "默认配置" }),
+						jsxs("div", { className: "rlr-row", children: [
+							jsx("span", { className: "rlr-label", children: "策略" }),
+							jsxs("select", { className: "rlr-select", value: cfg.strategy ?? "token-bucket", onChange: (e) => setTop("strategy", e.target.value), children: [
+								jsx("option", { value: "token-bucket", children: "令牌桶 (Token Bucket)" }),
+								jsx("option", { value: "sliding-window", children: "滑动窗口 (Sliding Window)" }),
+							] }),
+						] }),
+						jsxs("div", { className: "rlr-row", children: [
+							jsx("span", { className: "rlr-label", children: "最大并发数" }),
+							jsx("input", { type: "number", min: 1, className: "rlr-input", value: cfg.defaults?.maxConcurrent ?? 5, onChange: (e) => setDefault("maxConcurrent", Number(e.target.value) || 1) }),
+						] }),
+						jsxs("div", { className: "rlr-row", children: [
+							jsx("span", { className: "rlr-label", children: "每分钟最大请求数" }),
+							jsx("input", { type: "number", min: 1, className: "rlr-input", value: cfg.defaults?.maxRpm ?? 60, onChange: (e) => setDefault("maxRpm", Number(e.target.value) || 1) }),
+						] }),
+						cfg.strategy !== "sliding-window" && jsxs(react.Fragment, { children: [
+							jsxs("div", { className: "rlr-row", children: [
+								jsx("span", { className: "rlr-label", children: "突发容量" }),
+								jsx("input", { type: "number", min: 1, className: "rlr-input", value: cfg.defaults?.burstSize ?? 10, onChange: (e) => setDefault("burstSize", Number(e.target.value) || 1) }),
+							] }),
+							jsxs("div", { className: "rlr-row", children: [
+								jsx("span", { className: "rlr-label", children: "补充速率 (个/秒)" }),
+								jsx("input", { type: "number", min: 0.1, step: 0.1, className: "rlr-input", value: cfg.defaults?.refillRate ?? 1, onChange: (e) => setDefault("refillRate", Number(e.target.value) || 0.1) }),
+							] }),
+						] }),
+					] }),
+					/* ── 模型专属配置 ── */
+					jsxs("div", { className: "rlr-section", children: [
+						jsxs("div", { style: { display: "flex", justifyContent: "space-between", alignItems: "center" }, children: [
+							jsx("div", { className: "rlr-sectHead", children: "模型专属配置" }),
+							jsx("button", { className: "rlr-btn", onClick: addModel, children: "+ 添加模型" }),
+						] }),
+						modelKeys.length === 0 && jsx("p", { className: "rlr-status", children: "未配置模型专属限速，所有模型使用默认值。" }),
+						modelKeys.map((key) => jsxs("div", { className: "rlr-modelRow", key, children: [
+							jsxs("div", { style: { display: "flex", flexDirection: "column", gap: 4, flex: 1 }, children: [
+								jsx("span", { className: "rlr-modelName", children: key }),
+								jsxs("div", { className: "rlr-modelMeta", children: [
+									jsx("span", { children: `并发: ${readNum(cfg, key, "maxConcurrent")}` }),
+									jsx("span", { children: `RPM: ${readNum(cfg, key, "maxRpm")}` }),
+									cfg.strategy !== "sliding-window" && jsx("span", { children: `突发: ${readNum(cfg, key, "burstSize")}` }),
+								] }),
+								jsxs("div", { style: { display: "flex", alignItems: "center", gap: 6, marginTop: 4 }, children: [
+									jsx("input", { type: "number", min: 1, className: "rlr-input", style: { width: 60 }, title: "并发", placeholder: "并发", value: cfg.models?.[key]?.maxConcurrent ?? "", onChange: (e) => setModelField(key, "maxConcurrent", e.target.value === "" ? undefined : Number(e.target.value) || 1) }),
+									jsx("input", { type: "number", min: 1, className: "rlr-input", style: { width: 60 }, title: "RPM", placeholder: "RPM", value: cfg.models?.[key]?.maxRpm ?? "", onChange: (e) => setModelField(key, "maxRpm", e.target.value === "" ? undefined : Number(e.target.value) || 1) }),
+									cfg.strategy !== "sliding-window" && jsx("input", { type: "number", min: 1, className: "rlr-input", style: { width: 60 }, title: "突发", placeholder: "突发", value: cfg.models?.[key]?.burstSize ?? "", onChange: (e) => setModelField(key, "burstSize", e.target.value === "" ? undefined : Number(e.target.value) || 1) }),
+									jsx("button", { className: "rlr-btnSec", onClick: () => { const v = cfg.models?.[key]?.enabled; setModelField(key, "enabled", v === false ? undefined : false); }, children: cfg.models?.[key]?.enabled === false ? "已禁用" : "禁用" }),
+								] }),
+							] }),
+							jsx("button", { className: "rlr-danger", onClick: () => removeModel(key), title: "删除", children: "✕" }),
+						] })),
+					] }),
+					/* ── 被限速时的行为 ── */
+					jsxs("div", { className: "rlr-section", children: [
+						jsx("div", { className: "rlr-sectHead", children: "被限速时的行为" }),
+						jsxs("div", { className: "rlr-row", children: [
+							jsx("label", { style: { display: "flex", alignItems: "center", gap: 4, cursor: "pointer" }, children: [
+								jsx("input", { type: "radio", name: "rl-on-throttle", checked: cfg.onThrottled !== "reject", onChange: () => setTop("onThrottled", "queue") }),
+								"排队等待",
+							] }),
+							jsx("label", { style: { display: "flex", alignItems: "center", gap: 4, cursor: "pointer" }, children: [
+								jsx("input", { type: "radio", name: "rl-on-throttle", checked: cfg.onThrottled === "reject", onChange: () => setTop("onThrottled", "reject") }),
+								"拒绝请求",
+							] }),
+						] }),
+						cfg.onThrottled !== "reject" && jsxs("div", { className: "rlr-row", children: [
+							jsx("span", { className: "rlr-label", children: "最大排队等待 (ms)" }),
+							jsx("input", { type: "number", min: 1000, step: 1000, className: "rlr-input", value: cfg.maxQueueWaitMs ?? 60000, onChange: (e) => setTop("maxQueueWaitMs", Number(e.target.value) || 60000) }),
+						] }),
+					] }),
+				] }),
+			] });
+		}
+
+		/* ── Plugin registration ── */
+		function apply(ctx) {
+			const scope = ctx.settingsScope.bind({ namespace: name });
+			ctx.slots.inject("settings.plugin.item", function* () {
+				yield ctx.slots.register({
+					name: "settings.plugin.item",
+					key: name,
+					locale: name,
+					inject: () => ({ settingsScope: scope }),
+				}, RateLimiterCard);
+			});
+		}
+
+		exports.apply = apply;
+		exports.inject = inject;
+		exports.name = name;
+		return module.exports;
+	}
+});

package/lib/index.js

@@ -0,0 +1,203 @@
+/**
+ * dsh-llm-rate-limiter — Host (server-side) entry point.
+ *
+ * Intercepts the `llm/stream` waterfall and enforces per-model rate limits.
+ * Configuration lives in the "llm-rate-limiter" settings namespace, editable
+ * from the browser GUI.
+ *
+ * The `llm/stream` waterfall signature is:
+ *   (options: GenerateOptions, next: () => AsyncIterable<StreamChunk>) => AsyncIterable<StreamChunk>
+ *
+ * where `options` always has `.provider` (string) and `.model` (string).
+ *
+ * The settings service is injected dynamically (like dshmarket's
+ * installMarketSettings): `ctx.inject(['settings'], (scopedCtx) => ...)`, so a
+ * host without a settings provider simply runs without the GUI wiring — the
+ * composed entry stays as configured. Inherited from the DSH house pattern.
+ *
+ * @module dsh-llm-rate-limiter
+ */
+
+import { TokenBucketStrategy } from "./strategies/token-bucket.js";
+import { SlidingWindowStrategy } from "./strategies/sliding-window.js";
+import { RateLimiterConfig } from "./types/config.js";
+
+const name = "llm-rate-limiter";
+const SETTINGS_NS = "llm-rate-limiter";
+
+/* ── Helpers ─────────────────────────────────────────────────────────── */
+
+/**
+ * Merge defaults + per-model overrides into a flat config object that both
+ * strategy constructors understand.
+ */
+function resolveModelConfig(cfg, key) {
+  const o = cfg.models?.[key] ?? {};
+  const d = cfg.defaults ?? {};
+  const maxRpm = o.maxRpm ?? d.maxRpm ?? 60;
+  // When a model overrides maxRpm but not refillRate, derive refillRate from
+  // the model's maxRpm — this is the most common case ("set maxRpm=3").
+  // When model doesn't override maxRpm, use the defaults' refillRate as-is.
+  const refillRate = o.refillRate ?? (o.maxRpm != null ? o.maxRpm / 60 : d.refillRate ?? (maxRpm / 60));
+  return {
+    maxConcurrent: o.maxConcurrent ?? d.maxConcurrent ?? 5,
+    maxRpm,
+    burstSize:     o.burstSize     ?? d.burstSize     ?? 10,
+    refillRate,
+    windowMs:      d.windowMs      ?? 60_000,
+  };
+}
+
+/**
+ * Ensure a rate-limiting strategy instance exists (or is updated) for `key`.
+ */
+function ensureLimiter(limiters, key, cfg) {
+  const merged = resolveModelConfig(cfg, key);
+  const existing = limiters.get(key);
+  if (existing) {
+    existing.update(merged);
+    return existing;
+  }
+  const strategy = cfg.strategy === "sliding-window"
+    ? new SlidingWindowStrategy(merged)
+    : new TokenBucketStrategy(merged);
+  limiters.set(key, strategy);
+  return strategy;
+}
+
+/**
+ * Build a terminal StreamChunk for rate-limiting failures.
+ * Uses `kind: "aborted"` when the caller's AbortSignal fired, so the agent
+ * loop treats it as a cancellation rather than a retryable error.
+ * Otherwise uses `kind: "error"` with `RATE_LIMIT` code, which the
+ * `dsh-llm-retry` plugin can catch and back off.
+ */
+function terminalChunk(modelKey, signal) {
+  const aborted = signal?.aborted === true;
+  return {
+    type: "finish",
+    reason: aborted
+      ? { kind: "aborted", failure: { code: "RATE_LIMIT", message: `Rate limit: ${modelKey} (aborted)` } }
+      : { kind: "error", failure: { code: "RATE_LIMIT", message: `Rate limit exceeded for ${modelKey}` } },
+  };
+}
+
+/* ── Plugin entry ────────────────────────────────────────────────────── */
+
+/**
+ * @param {import("@deepseek-ai/cordis").Context} ctx
+ */
+function apply(ctx) {
+  const logger = ctx.logger?.("rate-limiter");
+
+  // Shared mutable config state.  Starts with built-in defaults; once the
+  // settings service is available the watcher replaces it with the live
+  // user-configured value on every change.
+  const defaultBase = {
+    enabled: true,
+    strategy: "token-bucket",
+    defaults: { maxConcurrent: 5, maxRpm: 60, burstSize: 10, refillRate: 1 },
+    models: {},
+    onThrottled: "queue",
+    maxQueueWaitMs: 60_000,
+  };
+  let cfg = { ...defaultBase };
+
+  /** @type {Map<string, TokenBucketStrategy | SlidingWindowStrategy>} */
+  const limiters = new Map();
+
+  // ── Settings wiring (dynamic inject) ───────────────────────
+  // Wrapped in ctx.inject so the plugin works on older DSH versions that
+  // don't have a settings service at all — the callback simply never runs.
+  ctx.inject(["settings"], (scopedCtx) => {
+    const scope = scopedCtx.settings.register(SETTINGS_NS, RateLimiterConfig, {
+      base: defaultBase,
+    });
+
+    logger?.info("rate limiter settings namespace registered (%s)", SETTINGS_NS);
+
+    // Replace cfg with live settings value on every change.
+    cfg = scope.get();
+    scope.watch((c) => { cfg = c; });
+
+    // Dispose limiters on settings teardown.
+    scopedCtx.effect(() => () => {
+      logger?.info("rate limiter settings scope tearing down (%s)", SETTINGS_NS);
+      for (const limiter of limiters.values()) limiter.dispose();
+      limiters.clear();
+    }, "rate-limiter: settings scope teardown");
+  });
+
+  // ── LLM stream interceptor ─────────────────────────────────
+  // ctx.on('llm/stream') doesn't need the settings service — it's a plain
+  // waterfall listener that reads the shared `cfg` variable (initialised
+  // with defaults; replaced by the settings watcher when available).
+  const disposeLlmListener = ctx.on("llm/stream", async function* rateLimitInterceptor(options, next) {
+    if (!cfg.enabled) {
+      yield* next();
+      return;
+    }
+
+    const modelKey = `${options.provider}/${options.model}`;
+
+    // Per-model opt-out: `enabled: false` skips this model entirely.
+    if (cfg.models?.[modelKey]?.enabled === false) {
+      yield* next();
+      return;
+    }
+
+    const limiter = ensureLimiter(limiters, modelKey, cfg);
+
+    // ── Phase 1: acquire ────────────────────────────────────────
+    let slotTaken = false;
+    if (cfg.onThrottled === "reject") {
+      // Non-blocking check — if at capacity, yield a terminal chunk immediately.
+      // acquireNonBlocking deducts a token AND takes a concurrent slot, so
+      // reject mode still enforces the frequency limit, not just concurrency.
+      const permit = limiter.acquireNonBlocking();
+      if (!permit.granted) {
+        logger?.warn("model %C rejected — rate limit reached", modelKey);
+        yield terminalChunk(modelKey, options.signal);
+        return;
+      }
+      // permit granted → slot already taken by acquireNonBlocking; skip acquireSlot.
+      slotTaken = true;
+    } else {
+      // Queue mode — park until a slot opens.
+      const permit = await limiter.acquire({
+        signal: options.signal,
+        timeoutMs: cfg.maxQueueWaitMs ?? 60_000,
+      });
+      if (!permit.granted) {
+        logger?.warn(
+          "model %C %s after %d ms",
+          modelKey, options.signal?.aborted ? "aborted" : "queue timeout", permit.waitMs,
+        );
+        yield terminalChunk(modelKey, options.signal);
+        return;
+      }
+      // Queue mode: acquire() does NOT take a concurrent slot.
+      // We must call acquireSlot() before the actual call.
+      slotTaken = false;
+    }
+
+    // ── Phase 2: run the real LLM call ─────────────────────────
+    if (!slotTaken) limiter.acquireSlot();
+    try {
+      yield* next();
+    } finally {
+      limiter.releaseSlot();
+    }
+  });
+
+  // ── Teardown ──
+  ctx.effect(() => () => {
+    disposeLlmListener();
+    for (const limiter of limiters.values()) limiter.dispose();
+    limiters.clear();
+  }, "rate-limiter: dispose llm/stream listener");
+
+  logger?.info("rate limiter active — llm/stream interceptor registered");
+}
+
+export { apply, name, SETTINGS_NS };

package/lib/strategies/sliding-window.js

@@ -0,0 +1,148 @@
+/**
+ * Sliding-Window rate limiter strategy.
+ *
+ * Counts requests inside a rolling window of `windowMs` milliseconds.
+ * The window slides continuously: each request's timestamp is recorded,
+ * and the count is the number of timestamps inside the window.
+ *
+ * Concurrency is controlled separately (same as TokenBucketStrategy).
+ *
+ * @module dsh-llm-rate-limiter/strategies/sliding-window
+ */
+
+export class SlidingWindowStrategy {
+  /** @type {{ windowMs: number, maxRpm: number, maxConcurrent: number }} */
+  #cfg;
+  #concurrent = 0;
+  /** @type {number[]} — timestamps (Date.now()) inside the window */
+  #timestamps = [];
+  /** @type {Array<{ resolve: (r: { granted: boolean }) => void, abort: () => void }>} */
+  #waiters = [];
+  #timer;
+
+  /**
+   * @param {object} config — `{ windowMs, maxRpm, maxConcurrent }`
+   */
+  constructor(config) {
+    this.#cfg = { ...config };
+    // Prune stale timestamps every second.
+    this.#timer = setInterval(() => this.#prune(), 1_000);
+  }
+
+  /* ── public API ─────────────────────────────────────── */
+
+  acquire({ signal, timeoutMs }) {
+    const t0 = Date.now();
+
+    if (signal?.aborted) return Promise.resolve({ granted: false });
+
+    // Fast path: concurrency AND window capacity both available.
+    if (this.#concurrent < this.#cfg.maxConcurrent && this.#count() < this.#cfg.maxRpm) {
+      this.#timestamps.push(Date.now());
+      return Promise.resolve({ granted: true });
+    }
+
+    if (this.#cfg.maxConcurrent <= 0) return Promise.resolve({ granted: false });
+
+    return new Promise((resolve) => {
+      const onDone = (result) => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        const idx = this.#waiters.indexOf(entry);
+        if (idx >= 0) this.#waiters.splice(idx, 1);
+        resolve({ ...result, waitMs: Date.now() - t0 });
+      };
+
+      const onAbort = () => onDone({ granted: false });
+      const timer = setTimeout(() => onDone({ granted: false }), timeoutMs);
+
+      const entry = {
+        resolve: () => onDone({ granted: true }),
+        abort: onAbort,
+      };
+
+      this.#waiters.push(entry);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+
+  /**
+   * Non-blocking acquisition: record the request in the window and take an
+   * implicit concurrent slot if both are available right now, without parking
+   * in the queue.
+   *
+   * Used by "reject" throttle mode, which must not wait, but must still count
+   * the request so the rate limit is enforced.
+   *
+   * @returns {{ granted: boolean }} — granted means the request was counted
+   *   and a concurrent slot taken; the caller MUST pair it with `releaseSlot()`.
+   */
+  acquireNonBlocking() {
+    if (this.#concurrent < this.#cfg.maxConcurrent && this.#count() < this.#cfg.maxRpm) {
+      this.#timestamps.push(Date.now());
+      this.#concurrent += 1;
+      return { granted: true };
+    }
+    return { granted: false };
+  }
+
+  acquireSlot() {
+    this.#concurrent += 1;
+  }
+
+  releaseSlot() {
+    this.#concurrent = Math.max(0, this.#concurrent - 1);
+    this.#drain();
+  }
+
+  getStatus() {
+    return {
+      strategy: "sliding-window",
+      windowMs: this.#cfg.windowMs,
+      countInWindow: this.#count(),
+      maxRpm: this.#cfg.maxRpm,
+      concurrent: this.#concurrent,
+      maxConcurrent: this.#cfg.maxConcurrent,
+      queued: this.#waiters.length,
+    };
+  }
+
+  update(config) {
+    Object.assign(this.#cfg, config);
+  }
+
+  dispose() {
+    clearInterval(this.#timer);
+    for (const w of this.#waiters) w.abort();
+    this.#waiters = [];
+  }
+
+  /* ── internals ─────────────────────────────────────── */
+
+  /** Number of timestamps inside the current window. */
+  #count() {
+    const cutoff = Date.now() - this.#cfg.windowMs;
+    // timestamps are pushed in order, so find the first that's still inside.
+    let i = 0;
+    while (i < this.#timestamps.length && this.#timestamps[i] <= cutoff) i += 1;
+    return this.#timestamps.length - i;
+  }
+
+  /** Remove timestamps that fell out of the window. */
+  #prune() {
+    const cutoff = Date.now() - this.#cfg.windowMs;
+    while (this.#timestamps.length > 0 && this.#timestamps[0] <= cutoff) {
+      this.#timestamps.shift();
+    }
+    this.#drain();
+  }
+
+  /** Drain waiters as long as capacity is available. */
+  #drain() {
+    while (this.#waiters.length > 0 && this.#count() < this.#cfg.maxRpm && this.#concurrent < this.#cfg.maxConcurrent) {
+      this.#timestamps.push(Date.now());
+      const waiter = this.#waiters.shift();
+      waiter?.resolve();
+    }
+  }
+}

package/lib/strategies/token-bucket.js

@@ -0,0 +1,168 @@
+/**
+ * Token-Bucket rate limiter strategy.
+ *
+ * Each model gets its own bucket.  A bucket has:
+ *  - `burstSize`  — maximum tokens the bucket can hold
+ *  - `refillRate` — tokens added per second
+ *  - a concurrent-slot counter (separate from tokens, so burst + concurrency are orthogonal)
+ *
+ * When the bucket is empty the request is queued (a promise resolver parked in
+ * `waiters[]`).  As tokens refill, waiters are drained in FIFO order.
+ *
+ * @module dsh-llm-rate-limiter/strategies/token-bucket
+ */
+
+export class TokenBucketStrategy {
+  /** @type {{ burstSize: number, refillRate: number, maxConcurrent: number }} */
+  #cfg;
+  #tokens;
+  #lastRefill;
+  #concurrent = 0;
+  /** @type {Array<{ resolve: (r: { granted: boolean }) => void, abort: () => void }>} */
+  #waiters = [];
+  #timer;
+
+  /**
+   * @param {object} config — `{ burstSize, refillRate, maxConcurrent }`
+   */
+  constructor(config) {
+    this.#cfg = { ...config };
+    this.#tokens = config.burstSize;
+    this.#lastRefill = Date.now();
+    this.#startRefill();
+  }
+
+  /* ── public API ─────────────────────────────────────── */
+
+  /**
+   * Wait until a request is allowed.
+   * Resolves `{ granted: true }` immediately or after the queue drains.
+   * Resolves `{ granted: false }` on abort or timeout (timeout is the caller's
+   * responsibility — it races this promise against a timer).
+   *
+   * @param {{ signal?: AbortSignal, timeoutMs: number }} opts
+   * @returns {Promise<{ granted: boolean, waitMs?: number }>}
+   */
+  acquire({ signal, timeoutMs }) {
+    const t0 = Date.now();
+
+    // Already aborted — fail fast.
+    if (signal?.aborted) {
+      return Promise.resolve({ granted: false });
+    }
+
+    // Fast path: concurrency room AND a token available.
+    if (this.#concurrent < this.#cfg.maxConcurrent && this.#tokens >= 1) {
+      this.#tokens -= 1;
+      return Promise.resolve({ granted: true });
+    }
+
+    // Slow path: park in the waiter queue.
+    if (this.#cfg.maxConcurrent <= 0) {
+      return Promise.resolve({ granted: false });
+    }
+
+    return new Promise((resolve) => {
+      const onDone = (result) => {
+        clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+        const idx = this.#waiters.indexOf(entry);
+        if (idx >= 0) this.#waiters.splice(idx, 1);
+        resolve({ ...result, waitMs: Date.now() - t0 });
+      };
+
+      const onAbort = () => onDone({ granted: false });
+
+      const timer = setTimeout(() => onDone({ granted: false }), timeoutMs);
+
+      const entry = {
+        resolve: () => {
+          // Token already deducted by _drain.
+          onDone({ granted: true });
+        },
+        abort: onAbort,
+      };
+
+      this.#waiters.push(entry);
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+
+  /**
+   * Non-blocking acquisition: consume a token and an implicit concurrent slot
+   * if both are available right now, without parking in the queue.
+   *
+   * Used by "reject" throttle mode, which must not wait, but must still deduct
+   * tokens so the rate limit is enforced (otherwise only the concurrency cap
+   * would bite).
+   *
+   * @returns {{ granted: boolean }} — granted means a token was consumed and a
+   *   concurrent slot taken; the caller MUST pair it with `releaseSlot()`.
+   */
+  acquireNonBlocking() {
+    if (this.#concurrent < this.#cfg.maxConcurrent && this.#tokens >= 1) {
+      this.#tokens -= 1;
+      this.#concurrent += 1;
+      return { granted: true };
+    }
+    return { granted: false };
+  }
+
+  /** Mark one concurrent slot as in-use. */
+  acquireSlot() {
+    this.#concurrent += 1;
+  }
+
+  /** Release one concurrent slot and try to drain waiters. */
+  releaseSlot() {
+    this.#concurrent = Math.max(0, this.#concurrent - 1);
+    this.#drain();
+  }
+
+  /** Live snapshot for the GUI. */
+  getStatus() {
+    return {
+      strategy: "token-bucket",
+      tokens: Math.round(this.#tokens * 100) / 100,
+      burstSize: this.#cfg.burstSize,
+      refillRate: this.#cfg.refillRate,
+      concurrent: this.#concurrent,
+      maxConcurrent: this.#cfg.maxConcurrent,
+      queued: this.#waiters.length,
+    };
+  }
+
+  /** Replace config at runtime (hot-reload). */
+  update(config) {
+    Object.assign(this.#cfg, config);
+  }
+
+  /** Dispose — release all waiters and stop the refill timer. */
+  dispose() {
+    clearInterval(this.#timer);
+    for (const w of this.#waiters) w.abort();
+    this.#waiters = [];
+  }
+
+  /* ── internals ─────────────────────────────────────── */
+
+  #startRefill() {
+    // Refill every 50 ms for smooth granularity.
+    this.#timer = setInterval(() => {
+      const now = Date.now();
+      const elapsed = (now - this.#lastRefill) / 1000;
+      this.#tokens = Math.min(this.#cfg.burstSize, this.#tokens + elapsed * this.#cfg.refillRate);
+      this.#lastRefill = now;
+      this.#drain();
+    }, 50);
+  }
+
+  /** Drain waiters as long as we have tokens and concurrency room. */
+  #drain() {
+    while (this.#waiters.length > 0 && this.#tokens >= 1 && this.#concurrent < this.#cfg.maxConcurrent) {
+      this.#tokens -= 1;
+      const waiter = this.#waiters.shift();
+      waiter?.resolve();
+    }
+  }
+}

package/lib/types/config.js

@@ -0,0 +1,53 @@
+/**
+ * Rate limiter configuration schema.
+ *
+ * The settings namespace is "llm-rate-limiter".  Users override values through
+ * the DSH settings document; the host merges them on top of `base`.
+ *
+ * @module dsh-llm-rate-limiter/types/config
+ */
+
+import Schema from "@deepseek-ai/schemastery";
+
+/**
+ * Per-model overrides — key is `"provider/model"` (e.g. `"deepseek/deepseek-chat"`).
+ * Every field is optional; omitted fields inherit from `defaults`.
+ */
+const ModelOverride = Schema.object({
+  maxConcurrent: Schema.number().step(1).min(1).description("Max concurrent requests for this model"),
+  maxRpm: Schema.number().step(1).min(1).description("Max requests per minute for this model"),
+  burstSize: Schema.number().step(1).min(1).description("Burst capacity for this model (token-bucket)"),
+  refillRate: Schema.number().min(0.1).description("Tokens refilled per second (token-bucket)"),
+  enabled: Schema.boolean().description("Enable/disable rate limiting for this model"),
+});
+
+export const RateLimiterConfig = Schema.object({
+  /** Master switch */
+  enabled: Schema.boolean().default(true).description("Enable the rate limiter globally"),
+
+  /** Default strategy */
+  strategy: Schema.union([
+    Schema.const("token-bucket").description("Token Bucket — allows bursts up to burstSize"),
+    Schema.const("sliding-window").description("Sliding Window — smooth, fixed requests-per-minute"),
+  ]).default("token-bucket").description("Rate limiting algorithm"),
+
+  /** Global defaults — applied to every model unless overridden */
+  defaults: Schema.object({
+    maxConcurrent: Schema.number().step(1).min(1).default(5).description("Max concurrent requests"),
+    maxRpm: Schema.number().step(1).min(1).default(60).description("Max requests per minute"),
+    burstSize: Schema.number().step(1).min(1).default(10).description("Burst capacity (token-bucket)"),
+    refillRate: Schema.number().min(0.1).default(1).description("Tokens per second (token-bucket)"),
+  }).default({}).description("Default limits applied to all models"),
+
+  /** Per-model overrides — key is "provider/model" */
+  models: Schema.dict(ModelOverride).description("Per-model rate limit overrides"),
+
+  /** Queue behaviour when a request is throttled */
+  onThrottled: Schema.union([
+    Schema.const("queue").description("Wait in queue until a slot opens"),
+    Schema.const("reject").description("Immediately return an error"),
+  ]).default("queue").description("What happens when a request exceeds the limit"),
+
+  /** Maximum time a request waits in queue before being rejected */
+  maxQueueWaitMs: Schema.number().step(1).min(1000).default(60_000).description("Max queue wait (ms)"),
+}).description("LLM call rate limiter settings");

package/lib/types/index.js

@@ -0,0 +1 @@
+export { RateLimiterConfig } from "./config.js";

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@leaf233/dsh-llm-rate-limiter",
+  "version": "0.1.1",
+  "description": "Per-model LLM call rate limiter for DeepSeek Harness with queue support",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-settings"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "echo 'no build needed'",
+    "test": "node test-strategies.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Leafyezi233/dsh-llm-rate-limiter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Leafyezi233/dsh-llm-rate-limiter/issues"
+  },
+  "homepage": "https://github.com/Leafyezi233/dsh-llm-rate-limiter#readme",
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "rate-limiter",
+    "llm",
+    "token-bucket",
+    "sliding-window",
+    "cordis-plugin"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.0",
+    "@deepseek-ai/schemastery": ">=3.18.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.0"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "package.json",
+    "README.md",
+    "CHANGELOG.md",
+    "COMPATIBILITY.md",
+    "LICENSE"
+  ]
+}