@leaf233/dsh-llm-rate-limiter 0.2.1 → 0.3.0

package/lib/client.js

@@ -2,8 +2,17 @@
 /**
  * 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.
+ * Registers the rate limiter's configuration page in the Plugins page's
+ * `plugins.item` slot (DSH 0.1.7+). The page draws the card chrome — icon,
+ * title, crumb, and the "open" navigation — and asks the entry for two views:
+ *
+ *   - `view: "summary"` → the one-line description on the card;
+ *   - `view: "page"`    → the configuration body plus the live status panel.
+ *
+ * Configuration values and the write channel come from the page itself
+ * (`props.form.state` / `props.form.mutate`), not from a plugin-owned
+ * `settingsScope`: `dsh-settings` projects the Host entry's volatile Config
+ * fields into one shared form per entry, and the page owns that form.
  *
  * Browser format: CJS-style factory registered via window.__ModuleLoader__.load
  * (loaded as a plain <script>, so NO top-level ESM `export` allowed).
@@ -23,23 +32,35 @@ window.__ModuleLoader__.load({
 		({ jsx, jsxs } = require("react/jsx-runtime"));
 
 		// ── Shared constants ──
+		/**
+		 * Settings namespace = the Host profile entry's id (its
+		 * `cordis.patch.yml` row id). `dsh-settings` keys every form by
+		 * `entry.options.id`, so this constant must match the row id.
+		 */
 		const name = "llm-rate-limiter";
-		const inject = ["slots", "settingsScope"];
+		/** Locale dictionary namespace owned by this plugin. */
+		const NS = "settings.llmRateLimiter";
+		/** Static fiber inject: every service this bundle reads. */
+		const inject = ["slots", "locale", "configForms"];
+
+		/* ── locale dictionaries ─────────────────────────────────────────── */
+		const zh = {
+			title: "LLM 调用限速",
+			description: "按模型限制 LLM 请求频率，超出限制的请求排队等待",
+			unavailable: "该插件当前未加载，暂时无法配置。",
+			readOnly: "本部署的设置为只读。",
+		};
+		const en = {
+			title: "LLM rate limiter",
+			description: "Limit per-model LLM request rates; throttled calls wait in queue",
+			unavailable: "This plugin is not loaded, so it cannot be configured right now.",
+			readOnly: "This deployment stores settings read-only.",
+		};
 
 		/* ── 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-page{display:flex;flex-direction:column;gap:4px;list-style:none;margin:0}",
 				".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)}",
@@ -96,12 +117,6 @@ window.__ModuleLoader__.load({
 		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 }]);
-		}
 
 		/* ── status channel access (dsh-context defensive idiom) ─────────── */
 		const STATUS_CHANNEL = "/llm-rate-limiter";
@@ -109,7 +124,7 @@ window.__ModuleLoader__.load({
 		/**
 		 * 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.
+		 * never throw — a missing channel degrades the panel, not the page.
 		 */
 		function rpcCallOf(ctx) {
 			try {
@@ -304,164 +319,191 @@ window.__ModuleLoader__.load({
 			] });
 		}
 
-		/* ── React component: collapsible card ───────────────────────────── */
-		function RateLimiterCard({ settingsScope, statusCall }) {
-			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]);
+		/* ── React component: the settings page (summary + page views) ───── */
+		/**
+		 * Render the one-liner or the configuration body, as the Plugins page
+		 * asks. Configuration values arrive in `props.form.state` (a
+		 * `ConfigFormSnapshot`: `{status, value, base, user, revision,
+		 * writable, mode}`) and writes go through `props.form.mutate(ops)` with
+		 * the same `{op:'set'|'unset', path, value}` operations the Host
+		 * validated before. The page owns the form, so it re-renders this entry
+		 * whenever the settings mirror changes — the component keeps no
+		 * subscription of its own.
+		 *
+		 * @param props - `view`, the page-owned `form`, and the injected
+		 *   `statusCall` (plus the framework's `t` locale seat).
+		 */
+		function RateLimiterCard(props) {
+			const t = typeof props.t === "function" ? props.t : (key) => key;
+
+			if (props.view === "summary") return jsx("span", { children: t("description") });
+
+			const form = props.form;
+			const snap = form?.state;
+			const cfg = snap?.status === "ready" && snap.value ? snap.value : {};
+			const writable = snap === undefined ? true : snap.writable !== false;
+			const statusCall = props.statusCall;
+
+			/** Queue one atomic namespace mutation; failures leave the form as-is. */
+			function push(ops) {
+				if (!form || typeof form.mutate !== "function") return;
+				try {
+					Promise.resolve(form.mutate(ops)).catch(() => undefined);
+				} catch {}
+			}
+			const setPath = (path, value) => push([{ op: "set", path, value }]);
+			const unsetPath = (path) => push([{ op: "unset", path }]);
 
 			const modelKeys = Object.keys(cfg.models ?? {});
 
 			function addModel() {
-				const key = prompt('添加模型限速 (格式: provider/model)\n例如: deepseek/deepseek-chat');
+				const key = prompt("添加模型限速 (格式: provider/model)\n例如: deepseek/deepseek-chat");
 				if (!key) return;
-				setNested(settingsScope, ["models", key], {});
+				setPath(["models", key], {});
 			}
 			function removeModel(key) {
-				unsetNested(settingsScope, ["models", key]);
+				unsetPath(["models", key]);
 			}
 			function setModelField(key, field, value) {
 				const path = ["models", key, field];
-				if (value === undefined || value === "") unsetNested(settingsScope, path);
-				else setNested(settingsScope, path, value);
+				if (value === undefined || value === "") unsetPath(path);
+				else setPath(path, value);
 			}
 			function setDefault(field, value) {
-				setNested(settingsScope, ["defaults", field], value);
+				setPath(["defaults", field], value);
 			}
 			function setTop(field, value) {
-				settingsScope.set(field, value);
+				setPath([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: [
-					/* ── 实时状态面板（折叠即卸载 → 停止轮询） ── */
-					jsx(RateLimiterStatus, { statusCall, cfg }),
-					/* ── 启用开关 ── */
+			return jsxs("div", { className: "rlr-page", children: [
+				/* ── unavailable / read-only notices ── */
+				snap?.status === "unavailable"
+					? jsx("div", { className: "rlr-status", children: t("unavailable") })
+					: null,
+				snap !== undefined && !writable
+					? jsx("div", { className: "rlr-status", children: t("readOnly") })
+					: null,
+
+				/* ── 实时状态面板 ── */
+				jsx(RateLimiterStatus, { statusCall, cfg }),
+
+				/* ── 启用开关 ── */
+				jsxs("div", { className: "rlr-row", children: [
+					jsx("label", { children: [
+						jsx("input", { type: "checkbox", checked: cfg.enabled ?? true, disabled: !writable, 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("label", { children: [
-							jsx("input", { type: "checkbox", checked: cfg.enabled ?? true, onChange: (e) => setTop("enabled", e.target.checked) }),
-							" 启用限速",
+						jsx("span", { className: "rlr-label", children: "策略" }),
+						jsxs("select", { className: "rlr-select", value: cfg.strategy ?? "token-bucket", disabled: !writable, 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-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", disabled: !writable, 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", disabled: !writable, 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?.maxConcurrent ?? 5, onChange: (e) => setDefault("maxConcurrent", Number(e.target.value) || 1) }),
+							jsx("span", { className: "rlr-label", children: "突发容量" }),
+							jsx("input", { type: "number", min: 1, className: "rlr-input", disabled: !writable, 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: 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) }),
-							] }),
+							jsx("span", { className: "rlr-label", children: "补充速率 (个/秒)" }),
+							jsx("input", { type: "number", min: 0.1, step: 0.1, className: "rlr-input", disabled: !writable, 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: [
+					jsxs("div", { style: { display: "flex", justifyContent: "space-between", alignItems: "center" }, children: [
+						jsx("div", { className: "rlr-sectHead", children: "模型专属配置" }),
+						jsx("button", { className: "rlr-btn", disabled: !writable, onClick: addModel, 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") }),
-								"排队等待",
+					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") }),
 							] }),
-							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") }),
-								"拒绝请求",
+							jsxs("div", { style: { display: "flex", alignItems: "center", gap: 6, marginTop: 4 }, children: [
+								jsx("input", { type: "number", min: 1, className: "rlr-input", disabled: !writable, 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", disabled: !writable, 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", disabled: !writable, 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", disabled: !writable, onClick: () => { const v = cfg.models?.[key]?.enabled; setModelField(key, "enabled", v === false ? undefined : false); }, children: cfg.models?.[key]?.enabled === false ? "已禁用" : "禁用" }),
 							] }),
 						] }),
-						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) }),
+						jsx("button", { className: "rlr-danger", disabled: !writable, 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", disabled: !writable, 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", disabled: !writable, 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", disabled: !writable, value: cfg.maxQueueWaitMs ?? 60000, onChange: (e) => setTop("maxQueueWaitMs", Number(e.target.value) || 60000) }),
 					] }),
 				] }),
 			] });
 		}
 
 		/* ── Plugin registration ── */
+		/**
+		 * Mount the configuration page while the Host serves this entry's
+		 * namespace, and register the plugin's own dictionaries.
+		 *
+		 * @param ctx - the browser plugin context.
+		 */
 		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,
-					// `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);
-			});
+			const t = ctx.locale.bind(NS);
+			ctx.effect(() => ctx.locale.register(NS, { zh, en }), "llm-rate-limiter: dictionaries");
+
+			// `whileServed` keeps the card off the page entirely unless the Host
+			// exposes this namespace: `dsh-settings` drops any entry whose Config
+			// has no volatile field (`lib/index.js:419`), so an entry that never
+			// appears there has nothing to configure.
+			ctx.effect(() => ctx.configForms.whileServed([name], () => ctx.slots.inject("plugins.item", () => ctx.slots.register({
+				name: "plugins.item",
+				id: name,
+				// Official `plugins.item` occupants take 10/20/30/40; 900 parks
+				// this third-party card after all of them.
+				order: 900,
+				label: () => t("title"),
+				locale: NS,
+				// `statusCall` is resolved per render (never cached) so a
+				// late-arriving or hot-reloaded connection service is picked up
+				// without re-registering the page.
+				inject: () => ({ statusCall: () => rpcCallOf(ctx) }),
+			}, RateLimiterCard))), "llm-rate-limiter: plugins page");
 		}
 
 		exports.apply = apply;
 		exports.inject = inject;
 		exports.name = name;
+		exports.NS = NS;
 		return module.exports;
-	}
-});
+	},
+});

package/lib/index.js

@@ -2,28 +2,36 @@
  * 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.
+ *
+ * Configuration is the profile ENTRY's own `config` (this module's exported
+ * {@link Config} schema), read through the volatile references Cordis builds
+ * for it. `dsh-settings` projects the volatile fields of every active entry
+ * into a form the browser can edit, so the plugin ships no settings service
+ * of its own. (DSH 0.1.5 had a `ctx.settings.register()` namespace API; 0.1.7
+ * removed it, and its browser half dropped `settingsScope` for `configForms`.
+ * The migration record lives in CHANGELOG.md under `[0.3.0]`.)
  *
  * 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";
+import { Config } from "./types/config.js";
 import { CHANNEL, createChannelRoute, createStatusChannel } from "./status-rpc.js";
 
 const name = "llm-rate-limiter";
+/**
+ * Settings namespace / profile entry id.
+ *
+ * `dsh-settings` keys every form by `entry.options.id` (`lib/index.js:432`),
+ * which is the `id` this plugin's `cordis.patch.yml` row declares. Renaming
+ * that row id therefore renames this namespace too — keep the two in step.
+ */
 const SETTINGS_NS = "llm-rate-limiter";
 
 /** Maximum retained events in the status ring (bounded memory). */
@@ -33,9 +41,45 @@ const SNAPSHOT_EVENT_COUNT = 8;
 
 /* ── Helpers ─────────────────────────────────────────────────────────── */
 
+/** Built-in defaults, used when a reference yields nothing (or no config at all). */
+const FALLBACK = {
+  enabled: true,
+  strategy: "token-bucket",
+  defaults: { maxConcurrent: 5, maxRpm: 60, burstSize: 10, refillRate: 1 },
+  models: {},
+  onThrottled: "queue",
+  maxQueueWaitMs: 60_000,
+};
+
+/**
+ * Read one volatile reference from the parsed Config.
+ *
+ * The loader mutates volatile references IN PLACE when only raw config values
+ * changed (`cordis-plugin-loader/lib/index.js:393` `_commitVolatile()`), so
+ * the reference object stays valid for the plugin's whole lifetime and its
+ * `get()` always yields the current value. Call this at each use rather than
+ * caching the unwrapped value.
+ *
+ * @param ref - a `.volatile()` field of the parsed Config, or undefined when
+ *   the entry was mounted with no config at all.
+ * @param fallback - value used when the reference is absent.
+ * @returns the current plain value.
+ */
+function read(ref, fallback) {
+  if (ref === undefined || ref === null) return fallback;
+  if (typeof ref.get === "function") {
+    const value = ref.get();
+    return value === undefined || value === null ? fallback : value;
+  }
+  return ref;
+}
+
 /**
  * Merge defaults + per-model overrides into a flat config object that both
  * strategy constructors understand.
+ *
+ * @param cfg - plain config object (`{ enabled, strategy, defaults, models, ... }`).
+ * @param key - `"provider/model"` of the call being limited.
  */
 function resolveModelConfig(cfg, key) {
   const o = cfg.models?.[key] ?? {};
@@ -92,22 +136,26 @@ function terminalChunk(modelKey, signal) {
 
 /**
  * @param {import("@deepseek-ai/cordis").Context} ctx
+ * @param {object} [config] - parsed Config; volatile fields are live references.
  */
-function apply(ctx) {
+function apply(ctx, config) {
   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 };
+  /**
+   * Snapshot the whole config as one plain object, reading each reference at
+   * call time. Derived settings are not cached: a volatile-only change updates
+   * the references in place without re-running `apply`.
+   */
+  function readConfig() {
+    return {
+      enabled: read(config?.enabled, FALLBACK.enabled),
+      strategy: read(config?.strategy, FALLBACK.strategy),
+      defaults: read(config?.defaults, FALLBACK.defaults),
+      models: read(config?.models, FALLBACK.models),
+      onThrottled: read(config?.onThrottled, FALLBACK.onThrottled),
+      maxQueueWaitMs: read(config?.maxQueueWaitMs, FALLBACK.maxQueueWaitMs),
+    };
+  }
 
   /** @type {Map<string, TokenBucketStrategy | SlidingWindowStrategy>} */
   const limiters = new Map();
@@ -135,6 +183,7 @@ function apply(ctx) {
 
   /** Build the JSON-safe snapshot served on the "snapshot" endpoint. */
   function buildSnapshot() {
+    const cfg = readConfig();
     const models = {};
     for (const [key, limiter] of limiters) {
       try {
@@ -162,26 +211,18 @@ function apply(ctx) {
     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.
+  // ── Settings presentation (dynamic inject) ─────────────────
+  // This plugin ships its own browser page, so it opts out of any
+  // schema-generated page. Wrapped in ctx.inject so a host WITHOUT a settings
+  // service still runs the limiter — the callback simply never runs. The
+  // optional child ctx names the plugin fiber the policy belongs to, which is
+  // why `ctx.fiber` is passed explicitly (`dsh-settings/lib/index.js:370`).
   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");
+    if (typeof scopedCtx.settings?.configure !== "function") return; // older/foreign settings seam: keep running
+    scopedCtx.effect(
+      () => scopedCtx.settings.configure({ auto: false }, ctx.fiber),
+      "rate-limiter: settings presentation",
+    );
   });
 
   // ── Status channel (dynamic inject) ────────────────────────
@@ -207,6 +248,8 @@ function apply(ctx) {
   //      'cannot get property "webServer" without inject'. Registering the
   //      route on our own fiber (which injects webServer below) avoids that
   //      while still using the framework's own 403/401 fence.
+  //      Still unfixed in 0.1.7-rc.1 (dsh-client-connection/lib/index.js:798
+  //      keeps `inject = ["credentials"]`), so the fallback still fires.
   ctx.inject(["connection"], (scopedCtx) => {
     const connection = scopedCtx.get("connection");
     const channel = createStatusChannel({ buildSnapshot, resetTotals });
@@ -271,10 +314,11 @@ function apply(ctx) {
   });
 
   // ── 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).
+  // Reads the live Config on every call, so a settings edit that reaches the
+  // loader takes effect on the next request without a restart.
   const disposeLlmListener = ctx.on("llm/stream", async function* rateLimitInterceptor(options, next) {
+    const cfg = readConfig();
+
     if (!cfg.enabled) {
       yield* next();
       return;
@@ -359,4 +403,4 @@ function apply(ctx) {
   logger?.info("rate limiter active — llm/stream interceptor registered");
 }
 
-export { apply, name, SETTINGS_NS };
+export { apply, name, SETTINGS_NS, Config };