@leaf233/dsh-llm-rate-limiter 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/).
 
+## [0.2.0] - 2026-09-13
+
+### Added
+- **Live status panel** in the settings card: request/granted/rejected/timeout/aborted counters, average wait, per-model progress bars (token balance or window occupancy), concurrency and queue badges, and a rolling event log
+- **`connection.rpc` status channel** at `/llm-rate-limiter` with `snapshot` and `reset` endpoints — the framework supplies POST+JSON transport, the Host/Origin fence (403) and browser authentication (401), and withdraws the channel with the plugin fiber
+- **"清零" button** that zeroes all statistics and drops retained events
+- `lib/status-rpc.js` — channel handler and envelope helpers (`success` / `failure`)
+- `test-status-rpc.mjs` (61 assertions): envelopes, endpoint routing, JSON-safety, ring-buffer bounds, every counter path
+- `test-client-bundle.mjs` (70 assertions): loads the real client bundle in a VM and mounts the card and panel on a miniature React runtime — covers live rendering, collapse-stops-polling, and every degraded phase
+
+### Changed
+- `dsh.client.inject` now also requires `@deepseek-ai/dsh-client-connection`, so the connection service is available before the panel mounts
+- `dsh.compatibility.dshReleases` declares the verified DSH release (aligned with dsh-context's convention)
+- CI runs the two new suites and syntax-checks `lib/status-rpc.js`
+
+### Notes
+- The status channel is optional: on a host without a connection service it is never registered and the panel shows "状态通道不可用" instead, leaving configuration untouched
+- Statistics are in-memory only and reset when the host restarts
+
 ## [0.1.1] - 2026-09-12
 
 ### Changed

package/COMPATIBILITY.md

@@ -30,6 +30,19 @@
 | 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 |
 
+### v0.2.0 新增依赖（状态通道）
+
+| # | API | 所属包 | 本地存在 | 稳定性评估 |
+|---|-----|--------|----------|------------|
+| 1 | `ctx.inject(["connection"], cb)` + `conn.rpc.handle(channel, handler)` | dsh-client-connection | ✅ `HostConnectionService.register`（lib/index.js 572-589） | **公开通用 API**；注册包在 `owner.effect` 中，卸载自动撤通道。通道名须匹配 `/^\/[A-Za-z0-9._~-]+$/` 且非 `/api` |
+| 2 | handler 签名 `(endpoint, payload, signal) => envelope` | dsh-client-connection | ✅ `rpcFetchHandler`（605-631） | 框架强制 POST + `application/json`（否则 404/415），并自动套 `requestRejection`（Host/Origin 不信→403，未认证→401） |
+| 3 | envelope `{ok:true,value}` / `{ok:false,error:{code,message,details}}` | dsh-client-connection | ✅ 与 `clientRequestSchema` / `errorResponse` 一致 | 契约字面量，dsh-context 逐字复制同一范式 |
+| 4 | 客户端 `ctx.get("connection")?.rpc.call(channel, endpoint, payload, signal)` | dsh-client-connection | ✅ `createWebConnectionRpc.call`（client.js 4606-4628） | 传输失败 reject；返回 `result`（即 envelope）。经 `rpcCallOf` 反射读取，服务缺席/敌意时降级为 `undefined` |
+| 5 | `dsh.client.inject` 声明 `@deepseek-ai/dsh-client-connection` | DSH web shell | ✅ | bundle 依赖声明，确保连接服务先于本插件可用；**不放进模块级 `inject`**，以便服务缺席时面板降级而非整卡不加载 |
+| 6 | `dsh.compatibility.dshReleases` 声明 | DSH 打包约定 | ✅ 对齐 `dsh-context` | 成熟插件物料约定 |
+
+> 证据：dsh-context v0.50.0 使用同一组 API（`watchDetailChannel`，lib/index.js 1943-2012），其 compatibility 矩阵覆盖 DSH `0.1.2-rc.1` → `0.1.5-rc.1`，说明 `connection.rpc` 是**持久公开契约**而非临时接口。
+
 ### Schema 依赖 — 1 个包
 
 | 包 | 本地版本 | 用到的 API |
@@ -130,4 +143,8 @@
    - [ ] `settings.register` 返回值结构是否变化
    - [ ] `settingsScope.set/mutate` 接口是否变化
    - [ ] `settings.plugin.item` slot 是否仍可注入
+   - [ ] **状态通道（v0.2.0）**：`connection.rpc.handle` 仍为公开 API 且通道名规则未变
+   - [ ] **状态通道（v0.2.0）**：`snapshot` / `reset` 端点往返成功（面板显示"● 实时"而非"状态通道不可用"）
+   - [ ] **状态通道（v0.2.0）**：折叠卡片后 DevTools Network 无 `/llm-rate-limiter/snapshot` 轮询
+   - [ ] **状态通道（v0.2.0）**：无 connection 服务的组合下，卡片配置区仍可用且面板显示降级文案
 4. **如果 cordis 升级到 5.0+**：整个 `apply(ctx)` 接口、`ctx.effect()`、`ctx.on()` 签名可能重写，需要全面适配

package/README.md

@@ -17,9 +17,39 @@ Per-model LLM call rate limiter for [DeepSeek Harness](https://github.com/deepse
 - **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
+- **Live status panel** — real-time counters, per-model progress bars and an event log (v0.2.0)
 - **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
 
+---
+
+## Status Panel (v0.2.0)
+
+Expanding the card shows a live panel at the top of its body:
+
+```
+📊 实时状态                          ● 实时   [清零]
+ 请求 42 · 通过 38 · 拒绝 2 · 超时 1 · 中止 1 · 平均等待 214ms
+ deepseek/deepseek-chat   [令牌桶]  ▓▓▓▓▓▓▓░░░ 7.5/10   并发 2/5   排队 1
+ openai/gpt-4o            [滑动窗口] ▓▓▓▓▓▓▓▓▓▓ 3/3 rpm  并发 1/5
+ 12:00:03  timeout   openai/gpt-4o              等待 1m
+ 12:00:01  rejected  openai/gpt-4o
+ 12:00:00  granted   deepseek/deepseek-chat     等待 4.2s
+```
+
+| Aspect | Behaviour |
+|--------|-----------|
+| Data channel | Framework `connection.rpc` channel `/llm-rate-limiter` — authenticated (401/403 fence), POST+JSON, auto-cleaned with the plugin fiber |
+| Cadence | 1 s polling while the card is expanded; backs off 2 s → 4 s → 8 s after failures |
+| Collapsed card | The panel unmounts, so **no polling runs at all** |
+| Endpoints | `snapshot` (live counters) and `reset` (zero the statistics) |
+| Without a channel | Shows "状态通道不可用" and leaves the rest of the card fully functional |
+| Counters | `requests` / `granted` / `rejected` / `timeouts` / `aborted` / `totalWaitMs`, plus the last 8 events (ring buffer of 64) |
+| Progress bars | Token bucket shows `tokens/burstSize`; sliding window shows `countInWindow/maxRpm`; both turn amber as the limit approaches |
+
+> 🧠 **From Hindsight memory (dsh-context-host-client)** — the channel idiom is dsh-context's: `ctx.inject(["connection"])` → `conn.rpc.handle(channel, handler)`, with the browser side resolving `ctx.get("connection")?.rpc.call` defensively so a missing service degrades instead of throwing.
+
+
 ---
 
 ## Installation

package/lib/client.js

@@ -53,6 +53,34 @@ window.__ModuleLoader__.load({
 				".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}",
+				// ── status panel ──
+				".rlr-statusHead{display:flex;align-items:center;gap:8px;margin:10px 0 0}",
+				".rlr-statusTitle{font-size:14px;font-weight:500;flex:1}",
+				".rlr-chips{display:flex;flex-wrap:wrap;gap:6px;margin:8px 0}",
+				".rlr-chip{font-size:11px;padding:2px 8px;border-radius:10px;background:var(--dsw-alias-surface-s2);color:var(--dsw-alias-label-secondary);white-space:nowrap;font-variant-numeric:tabular-nums}",
+				".rlr-chipOk{background:var(--dsw-alias-state-success-primary,#16a34a);color:#fff}",
+				".rlr-chipWarn{background:var(--dsw-alias-state-warning-primary,#d97706);color:#fff}",
+				".rlr-chipErr{background:var(--dsw-alias-state-error-primary,#dc2626);color:#fff}",
+				".rlr-phase{font-size:11px;color:var(--dsw-alias-label-tertiary)}",
+				".rlr-phaseLive{color:var(--dsw-alias-state-success-primary,#16a34a)}",
+				".rlr-phaseFailed{color:var(--dsw-alias-state-error-primary,#dc2626)}",
+				".rlr-models{display:flex;flex-direction:column;gap:4px;margin:6px 0}",
+				".rlr-mRow{display:flex;align-items:center;gap:10px;padding:6px 10px;border-radius:10px;border:1px solid var(--dsw-alias-border-l4)}",
+				".rlr-mName{font-size:12px;font-family:monospace;min-width:0;flex:1;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}",
+				".rlr-mKind{font-size:10px;padding:1px 6px;border-radius:8px;background:var(--dsw-alias-surface-s2);color:var(--dsw-alias-label-tertiary);white-space:nowrap}",
+				".rlr-mMeta{font-size:11px;color:var(--dsw-alias-label-tertiary);white-space:nowrap;font-variant-numeric:tabular-nums}",
+				".rlr-mIdle{opacity:.55}",
+				".rlr-bar{width:90px;height:6px;border-radius:3px;background:var(--dsw-alias-surface-s2);overflow:hidden;flex:none}",
+				".rlr-barFill{height:100%;background:var(--dsw-alias-brand-primary,#4f46e5);transition:width .3s}",
+				".rlr-barFillWarn{background:var(--dsw-alias-state-warning-primary,#d97706)}",
+				".rlr-log{display:flex;flex-direction:column;gap:1px;margin:6px 0;font-family:monospace;font-size:11px}",
+				".rlr-logRow{display:flex;gap:8px;padding:1px 4px;border-radius:4px;color:var(--dsw-alias-label-tertiary)}",
+				".rlr-logRowNew{background:var(--dsw-alias-surface-s2)}",
+				".rlr-logEv{min-width:66px}",
+				".rlr-logEvOk{color:var(--dsw-alias-state-success-primary,#16a34a)}",
+				".rlr-logEvWarn{color:var(--dsw-alias-state-warning-primary,#d97706)}",
+				".rlr-logEvErr{color:var(--dsw-alias-state-error-primary,#dc2626)}",
+				".rlr-logMs{min-width:56px;text-align:right}",
 			].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) {
@@ -75,8 +103,209 @@ window.__ModuleLoader__.load({
 			scope.mutate([{ op: "unset", path }]);
 		}
 
+		/* ── status channel access (dsh-context defensive idiom) ─────────── */
+		const STATUS_CHANNEL = "/llm-rate-limiter";
+
+		/**
+		 * The connection's bound generic-RPC caller, or undefined when the
+		 * service is absent or hostile. Every read is guarded, so this can
+		 * never throw — a missing channel degrades the panel, not the card.
+		 */
+		function rpcCallOf(ctx) {
+			try {
+				const rpc = ctx.get("connection")?.rpc;
+				const fn = rpc?.call;
+				if (rpc && typeof fn === "function") return fn.bind(rpc);
+			} catch {}
+			return undefined;
+		}
+
+		/** Format a duration in ms for the chips/log (compact). */
+		function fmtMs(ms) {
+			if (!Number.isFinite(ms) || ms <= 0) return "0";
+			if (ms < 1000) return Math.round(ms) + "ms";
+			if (ms < 60_000) return (ms / 1000).toFixed(1) + "s";
+			return Math.round(ms / 60_000) + "m";
+		}
+
+		/** Human label for a strategy id. */
+		function strategyLabel(id) {
+			return id === "sliding-window" ? "滑动窗口" : "令牌桶";
+		}
+
+		/** Tunable polling cadence: first retry delay doubles up to 8s. */
+		const POLL_MS = 1000;
+		const POLL_MAX_MULTIPLIER = 8;
+
+		/* ── React component: live status panel ──────────────────────────── */
+		function RateLimiterStatus({ statusCall, cfg }) {
+			const [snap, setSnap] = react.useState(null);
+			const [phase, setPhase] = react.useState("connecting");
+			const prevRev = react.useRef(-1);
+			const [highlight, setHighlight] = react.useState(false);
+
+			react.useEffect(() => {
+				const call = statusCall();
+				if (call === undefined) {
+					setPhase("no-channel");
+					return undefined;
+				}
+				let stop = false;
+				let timer = null;
+				let failures = 0;
+
+				const tick = async () => {
+					try {
+						const r = await call(STATUS_CHANNEL, "snapshot", {});
+						if (stop) return;
+						if (r?.ok !== true || !r.value) throw new Error("bad envelope");
+						setSnap(r.value);
+						setPhase("live");
+						failures = 0;
+					} catch {
+						if (stop) return;
+						failures += 1;
+						setPhase("failed");
+					}
+					if (stop) return;
+					const multiplier = Math.min(2 ** Math.min(failures, 3), POLL_MAX_MULTIPLIER);
+					timer = setTimeout(tick, POLL_MS * multiplier);
+				};
+
+				tick();
+				return () => {
+					stop = true;
+					if (timer) clearTimeout(timer);
+				};
+			}, [statusCall]);
+
+			// Flash newly arrived events when `rev` advances between polls.
+			react.useEffect(() => {
+				if (!snap) return undefined;
+				if (prevRev.current === -1) { prevRev.current = snap.rev; return undefined; }
+				if (snap.rev === prevRev.current) return undefined;
+				prevRev.current = snap.rev;
+				setHighlight(true);
+				const t = setTimeout(() => setHighlight(false), 700);
+				return () => clearTimeout(t);
+			}, [snap]);
+
+			// ── non-live phases ──
+			if (phase === "no-channel") {
+				return jsx("div", { className: "rlr-status", children: "状态通道不可用（需要 DSH web 组合）" });
+			}
+			if (phase === "connecting" && !snap) {
+				return jsx("div", { className: "rlr-status", children: "正在连接状态通道…" });
+			}
+			if (!snap) {
+				return jsx("div", { className: "rlr-status", children: "连接中断，重试中…" });
+			}
+
+			const t = snap.totals ?? {};
+			const avgWait = t.granted > 0 ? (t.totalWaitMs ?? 0) / t.granted : 0;
+			const live = phase === "live";
+
+			function onReset() {
+				const call = statusCall();
+				if (call === undefined) return;
+				Promise.resolve(call(STATUS_CHANNEL, "reset", {})).catch(() => undefined);
+			}
+
+			// Union of configured models and models that have actually been used.
+			const snapModels = snap.models ?? {};
+			const keys = Array.from(new Set([...Object.keys(cfg.models ?? {}), ...Object.keys(snapModels)]));
+
+			const chips = [
+				{ label: "请求 " + (t.requests ?? 0) },
+				{ label: "通过 " + (t.granted ?? 0), tone: "ok" },
+				(t.rejected ?? 0) > 0 && { label: "拒绝 " + t.rejected, tone: "err" },
+				(t.timeouts ?? 0) > 0 && { label: "超时 " + t.timeouts, tone: "warn" },
+				(t.aborted ?? 0) > 0 && { label: "中止 " + t.aborted, tone: "warn" },
+				{ label: "平均等待 " + fmtMs(avgWait) },
+			].filter(Boolean);
+
+			const events = Array.isArray(snap.events) ? snap.events.slice().reverse() : [];
+
+			return jsxs("div", { className: "rlr-section", children: [
+				jsxs("div", { className: "rlr-statusHead", children: [
+					jsx("span", { className: "rlr-statusTitle", children: "📊 实时状态" }),
+					jsx("span", {
+						className: "rlr-phase" + (live ? " rlr-phaseLive" : " rlr-phaseFailed"),
+						children: live ? "● 实时" : "○ 重试中",
+					}),
+					jsx("button", { type: "button", className: "rlr-btnSec", onClick: onReset, children: "清零" }),
+				] }),
+
+				snap.enabled === false
+					? jsx("div", { className: "rlr-status", children: "限速已停用" })
+					: null,
+
+				jsx("div", { className: "rlr-chips", children: chips.map((c, i) =>
+					jsx("span", {
+						key: i,
+						className: "rlr-chip" + (c.tone === "ok" ? " rlr-chipOk" : c.tone === "warn" ? " rlr-chipWarn" : c.tone === "err" ? " rlr-chipErr" : ""),
+						children: c.label,
+					}),
+				) }),
+
+				keys.length === 0
+					? jsx("div", { className: "rlr-status", children: "尚无模型调用记录" })
+					: jsx("div", { className: "rlr-models", children: keys.map((key) => {
+						const m = snapModels[key];
+						if (!m) {
+							return jsxs("div", { key, className: "rlr-mRow rlr-mIdle", children: [
+								jsx("span", { className: "rlr-mName", children: key }),
+								jsx("span", { className: "rlr-mMeta", children: "未调用" }),
+							] });
+						}
+						const isBucket = m.strategy !== "sliding-window";
+						const numerator = isBucket ? (m.tokens ?? 0) : (m.countInWindow ?? 0);
+						const denominator = isBucket ? (m.burstSize ?? 0) : (m.maxRpm ?? 0);
+						const pct = denominator > 0 ? Math.min(100, Math.round((numerator / denominator) * 100)) : 0;
+						// A nearly empty bucket / a nearly full window both mean "close to throttling".
+						const nearLimit = isBucket ? pct <= 20 : pct >= 80;
+						return jsxs("div", { key, className: "rlr-mRow", children: [
+							jsx("span", { className: "rlr-mName", title: key, children: key }),
+							jsx("span", { className: "rlr-mKind", children: strategyLabel(m.strategy) }),
+							jsx("span", { className: "rlr-bar", children:
+								jsx("span", { className: "rlr-barFill" + (nearLimit ? " rlr-barFillWarn" : ""), style: { width: pct + "%" } }),
+							}),
+							jsx("span", { className: "rlr-mMeta", children:
+								(isBucket ? numerator + "/" + denominator : numerator + "/" + denominator + " rpm"),
+							}),
+							jsx("span", { className: "rlr-mMeta", children: "并发 " + (m.concurrent ?? 0) + "/" + (m.maxConcurrent ?? 0) }),
+							(m.queued ?? 0) > 0
+								? jsx("span", { className: "rlr-chip rlr-chipWarn", children: "排队 " + m.queued })
+								: null,
+						] });
+					}) }),
+
+				events.length > 0
+					? jsx("div", { className: "rlr-log", children: events.map((e, i) => {
+						const good = e.event === "granted" || e.event === "completed";
+						const bad = e.event === "rejected";
+						const d = new Date(e.ts ?? Date.now());
+						const hh = String(d.getHours()).padStart(2, "0");
+						const mm = String(d.getMinutes()).padStart(2, "0");
+						const ss = String(d.getSeconds()).padStart(2, "0");
+						return jsxs("div", {
+							className: "rlr-logRow" + (highlight && i === 0 ? " rlr-logRowNew" : ""),
+							children: [
+								jsx("span", { children: hh + ":" + mm + ":" + ss }),
+								jsx("span", { className: "rlr-logEv " + (good ? "rlr-logEvOk" : bad ? "rlr-logEvErr" : "rlr-logEvWarn"), children: e.event }),
+								jsx("span", { className: "rlr-mName", title: e.model, children: e.model }),
+								(e.waitMs ?? 0) > 0
+									? jsx("span", { className: "rlr-logMs", children: "等待 " + fmtMs(e.waitMs) })
+									: null,
+							],
+						});
+					}) })
+					: null,
+			] });
+		}
+
 		/* ── React component: collapsible card ───────────────────────────── */
-		function RateLimiterCard({ settingsScope }) {
+		function RateLimiterCard({ settingsScope, statusCall }) {
 			const [cfg, setCfg] = react.useState(() => {
 				const snap = settingsScope.getSnapshot?.();
 				return snap?.status === "ready" && snap.value ? { ...snap.value } : {};
@@ -129,6 +358,8 @@ window.__ModuleLoader__.load({
 					]
 				}),
 				open && jsxs("div", { className: "rlr-body", children: [
+					/* ── 实时状态面板（折叠即卸载 → 停止轮询） ── */
+					jsx(RateLimiterStatus, { statusCall, cfg }),
 					/* ── 启用开关 ── */
 					jsxs("div", { className: "rlr-row", children: [
 						jsx("label", { children: [
@@ -220,7 +451,10 @@ window.__ModuleLoader__.load({
 					name: "settings.plugin.item",
 					key: name,
 					locale: name,
-					inject: () => ({ settingsScope: scope }),
+					// `statusCall` is resolved per render (never cached) so a
+					// late-arriving or hot-reloaded connection service is picked
+					// up without re-registering the card.
+					inject: () => ({ settingsScope: scope, statusCall: () => rpcCallOf(ctx) }),
 				}, RateLimiterCard);
 			});
 		}

package/lib/index.js

@@ -21,10 +21,16 @@
 import { TokenBucketStrategy } from "./strategies/token-bucket.js";
 import { SlidingWindowStrategy } from "./strategies/sliding-window.js";
 import { RateLimiterConfig } from "./types/config.js";
+import { CHANNEL, createStatusChannel } from "./status-rpc.js";
 
 const name = "llm-rate-limiter";
 const SETTINGS_NS = "llm-rate-limiter";
 
+/** Maximum retained events in the status ring (bounded memory). */
+const EVENT_RING_LIMIT = 64;
+/** Events carried by one snapshot (the panel shows these). */
+const SNAPSHOT_EVENT_COUNT = 8;
+
 /* ── Helpers ─────────────────────────────────────────────────────────── */
 
 /**
@@ -106,6 +112,56 @@ function apply(ctx) {
   /** @type {Map<string, TokenBucketStrategy | SlidingWindowStrategy>} */
   const limiters = new Map();
 
+  // ── Live statistics (read by the status RPC channel) ───────
+  // Counters are plain numbers so a snapshot is always JSON-safe.
+  const totals = {
+    requests: 0,
+    granted: 0,
+    rejected: 0,
+    timeouts: 0,
+    aborted: 0,
+    totalWaitMs: 0,
+  };
+  /** Bumped on every recorded event and on reset — the panel's change cursor. */
+  let rev = 0;
+  /** Bounded ring of recent events (newest last). */
+  const eventRing = [];
+
+  function recordEvent(event) {
+    eventRing.push({ ...event, ts: Date.now() });
+    if (eventRing.length > EVENT_RING_LIMIT) eventRing.shift();
+    rev += 1;
+  }
+
+  /** Build the JSON-safe snapshot served on the "snapshot" endpoint. */
+  function buildSnapshot() {
+    const models = {};
+    for (const [key, limiter] of limiters) {
+      try {
+        models[key] = limiter.getStatus();
+      } catch {
+        // A strategy that cannot report status must not break the whole panel.
+      }
+    }
+    return {
+      rev,
+      ts: Date.now(),
+      enabled: cfg.enabled !== false,
+      strategy: cfg.strategy,
+      onThrottled: cfg.onThrottled,
+      totals: { ...totals },
+      models,
+      events: eventRing.slice(-SNAPSHOT_EVENT_COUNT),
+    };
+  }
+
+  /** Zero every counter and drop retained events (the panel's clear button). */
+  function resetTotals() {
+    for (const key of Object.keys(totals)) totals[key] = 0;
+    eventRing.length = 0;
+    rev += 1;
+  }
+
   // ── 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.
@@ -128,6 +184,30 @@ function apply(ctx) {
     }, "rate-limiter: settings scope teardown");
   });
 
+  // ── Status RPC channel (dynamic inject) ────────────────────
+  // Same defensive shape as the settings wiring: on a host without a
+  // connection service the callback never runs and the plugin stays silent.
+  // The registration is owned by this fiber, so unloading withdraws it.
+  ctx.inject(["connection"], (scopedCtx) => {
+    const connection = scopedCtx.get("connection");
+    const handle = typeof connection?.rpc?.handle === "function"
+      ? connection.rpc.handle.bind(connection.rpc)
+      : undefined;
+    if (handle === undefined) return; // older host: degrade silently
+
+    try {
+      scopedCtx.effect(() => {
+        const unregister = handle(CHANNEL, createStatusChannel({ buildSnapshot, resetTotals }));
+        return () => { unregister(); };
+      }, "rate-limiter: status rpc channel");
+    } catch (err) {
+      logger?.warn("status channel registration failed: %s", err instanceof Error ? err.message : String(err));
+      return;
+    }
+
+    logger?.info("rate limiter status channel mounted (%s)", CHANNEL);
+  });
+
   // ── 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
@@ -147,6 +227,7 @@ function apply(ctx) {
     }
 
     const limiter = ensureLimiter(limiters, modelKey, cfg);
+    totals.requests += 1;
 
     // ── Phase 1: acquire ────────────────────────────────────────
     let slotTaken = false;
@@ -156,12 +237,16 @@ function apply(ctx) {
       // reject mode still enforces the frequency limit, not just concurrency.
       const permit = limiter.acquireNonBlocking();
       if (!permit.granted) {
+        totals.rejected += 1;
+        recordEvent({ event: "rejected", model: modelKey });
         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;
+      totals.granted += 1;
+      recordEvent({ event: "granted", model: modelKey, waitMs: 0 });
     } else {
       // Queue mode — park until a slot opens.
       const permit = await limiter.acquire({
@@ -169,9 +254,17 @@ function apply(ctx) {
         timeoutMs: cfg.maxQueueWaitMs ?? 60_000,
       });
       if (!permit.granted) {
+        const aborted = options.signal?.aborted === true;
+        if (aborted) {
+          totals.aborted += 1;
+          recordEvent({ event: "aborted", model: modelKey, waitMs: permit.waitMs ?? 0 });
+        } else {
+          totals.timeouts += 1;
+          recordEvent({ event: "timeout", model: modelKey, waitMs: permit.waitMs ?? 0 });
+        }
         logger?.warn(
           "model %C %s after %d ms",
-          modelKey, options.signal?.aborted ? "aborted" : "queue timeout", permit.waitMs,
+          modelKey, aborted ? "aborted" : "queue timeout", permit.waitMs,
         );
         yield terminalChunk(modelKey, options.signal);
         return;
@@ -179,6 +272,9 @@ function apply(ctx) {
       // Queue mode: acquire() does NOT take a concurrent slot.
       // We must call acquireSlot() before the actual call.
       slotTaken = false;
+      totals.granted += 1;
+      totals.totalWaitMs += permit.waitMs ?? 0;
+      recordEvent({ event: "granted", model: modelKey, waitMs: permit.waitMs ?? 0 });
     }
 
     // ── Phase 2: run the real LLM call ─────────────────────────
@@ -187,6 +283,7 @@ function apply(ctx) {
       yield* next();
     } finally {
       limiter.releaseSlot();
+      recordEvent({ event: "completed", model: modelKey });
     }
   });
 

package/lib/status-rpc.js

@@ -0,0 +1,67 @@
+/**
+ * dsh-llm-rate-limiter — status RPC channel (Host half).
+ *
+ * Exposes live rate-limiter statistics to the browser over the framework's
+ * generic Connection RPC channel — the same idiom dsh-context uses for its
+ * detail channel. The framework supplies POST+JSON transport, the Host/Origin
+ * fence (403) and browser authentication (401); this module only answers
+ * endpoints and shapes envelopes.
+ *
+ * Registration is owned by the calling fiber (`register()` wraps
+ * `owner.webServer.register` in `owner.effect`), so unloading the plugin
+ * withdraws the channel automatically — there is no connection bookkeeping
+ * here.
+ *
+ * Envelope contract (mirrors the Connection wire schema):
+ *   success: { ok: true,  value: <JSON-safe> }
+ *   failure: { ok: false, error: { code, message, details } }
+ *
+ * @module dsh-llm-rate-limiter/status-rpc
+ */
+
+/**
+ * Channel name. Must satisfy the framework's `assertChannel` pattern
+ * `/^\/[A-Za-z0-9._~-]+$/` and must not be the reserved `/api` channel.
+ */
+const CHANNEL = "/llm-rate-limiter";
+
+/**
+ * Build a failure envelope. Field-for-field the same shape the Connection
+ * host accepts, so callers can rely on `ok` discrimination alone.
+ * @param {string} code - stable machine-readable error code.
+ * @param {string} message - human-readable detail.
+ * @param {Record<string, unknown>} [details] - optional structured context.
+ * @returns {{ ok: false, error: { code: string, message: string, details: Record<string, unknown> } }}
+ */
+function failure(code, message, details = {}) {
+  return { ok: false, error: { code, message, details } };
+}
+
+/** Build a success envelope. */
+function success(value) {
+  return { ok: true, value };
+}
+
+/**
+ * Create the channel handler.
+ *
+ * @param {object} deps
+ * @param {() => object} deps.buildSnapshot - live snapshot builder.
+ * @param {() => void} deps.resetTotals - zero the counters (and bump `rev`).
+ * @returns {(endpoint: string, payload: unknown, signal?: AbortSignal) => Promise<object>}
+ */
+function createStatusChannel({ buildSnapshot, resetTotals }) {
+  return async function statusChannel(endpoint) {
+    if (endpoint === "snapshot") return success(buildSnapshot());
+    if (endpoint === "reset") {
+      resetTotals();
+      return success({});
+    }
+    return failure(
+      "llm-rate-limiter/unknown-endpoint",
+      `unknown endpoint: ${String(endpoint)}`,
+    );
+  };
+}
+
+export { CHANNEL, createStatusChannel, failure, success };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@leaf233/dsh-llm-rate-limiter",
-  "version": "0.1.1",
-  "description": "Per-model LLM call rate limiter for DeepSeek Harness with queue support",
+  "version": "0.2.0",
+  "description": "Per-model LLM call rate limiter for DeepSeek Harness with queue support and a live status panel",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -14,9 +14,15 @@
     },
     "client": {
       "inject": [
+        "@deepseek-ai/dsh-client-connection",
         "@deepseek-ai/dsh-client-ui-settings"
       ],
       "platform": "web"
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.1.2-rc.1": "compatible"
+      }
     }
   },
   "scripts": {