dsh-usage-state 0.3.2 → 0.4.0

package/README.en.md

@@ -22,7 +22,8 @@ hover any segment:           Source DeepSeek · Mode API balance · Granted 0 ·
 
 ## Install
 
-**Requirements**: DSH `0.1.5-rc.2` through `0.2.x`, Node ≥ 20, installed into the `web` profile. The package **ships the prebuilt `lib/`**, so installation has no build step.
+**Requirements**: DSH `0.2.0-rc.2` or a later 0.2 release, Node ≥ 20, installed into the `web` profile. The package **ships the prebuilt `lib/`**, so installation has no build step.
+**On the 0.1 line install `0.3.2` instead**: DSH 0.2 replaced the whole settings API (`settingsScope` / `settings.register` → `configForms` / the plugin's own `Config`), and the two share no surface, so `0.4.0` and up support the 0.2 line only (see revision 17 of [`docs/design-consensus.md`](docs/design-consensus.md)).
 
 ```bash
 # 1) install (npm package)
@@ -98,9 +99,11 @@ Expanding **Advanced** lets you override the source and endpoint, name a credent
 
 ## Compatibility
 
-- Verified against DSH `0.1.5-rc.2` and `0.2.0-rc.2`, Node ≥ 20. The DSH requirement is declared as `>=0.1.5-rc.1 <0.3.0-0` through `engines.dsh` — the whole 0.1 line from 0.1.5 up, plus the 0.2 line (this is what dsh-market's compatibility badge and install gate read).
+- **0.2 line only**: `engines.dsh` = `>=0.2.0-rc.2 <0.3.0-0` (this is what dsh-market's badge and install gate read). On an earlier host, install `0.3.2`.
+- `peerDependencies` carry `@deepseek-ai/dsh-settings` (`^0.2.0-rc.2`) and `@deepseek-ai/schemastery` (`^3.18.2`). The first one is deliberate: the runtime install gate only reads `@deepseek-ai/dsh*` peers, so declaring it makes a 0.1.x host **refuse the install** instead of accepting it and then failing to boot. Both are platform-provided; pnpm may print a `missing peer` warning for them, which is expected.
+- Version `0.4.0` migrates to the 0.2 settings model (`Config` + `configForms`, with cross-entry config read through `configEditor`). Verification and results: [`docs/implementation.md`](docs/implementation.md) §10; rationale: [`docs/design-consensus.md`](docs/design-consensus.md) revision 17.
+- Version `0.3.2` (last of the 0.1 line) only widened `engines.dsh`; **its claimed 0.2 compatibility was wrong** — on `0.2.0-rc.2` it fails the entire web boot because `settingsScope` does not exist there.
 - Published to npm as [`dsh-usage-state`](https://www.npmjs.com/package/dsh-usage-state); GitHub installs work too.
-- Version `0.3.2`: 0.2-line compatibility review (no code change — only `engines.dsh` was widened); DeepSeek, z.ai and OpenCode Zen Go are verified against live accounts; see the limitations below.
 
 ## Limitations
 

package/README.md

@@ -24,7 +24,8 @@
 
 ## 安装
 
-**前置条件**：DSH `0.1.5-rc.2` ～ `0.2.x`、Node ≥ 20，装进 `web` profile。包内**自带预构建的 `lib/`**，安装时没有构建步骤。
+**前置条件**：DSH `0.2.0-rc.2` 或更新的 0.2 线、Node ≥ 20，装进 `web` profile。包内**自带预构建的 `lib/`**，安装时没有构建步骤。
+**用 0.1 线请装 `0.3.2`**：DSH 0.2 换掉了整套设置 API（`settingsScope` / `settings.register` → `configForms` / 插件自带 `Config`），两套 API 没有重叠，所以 `0.4.0` 起只支持 0.2 线（原因见 [`docs/design-consensus.md`](docs/design-consensus.md) 修订 17）。
 
 ```bash
 # 1) 安装（npm 包）
@@ -122,9 +123,11 @@ dsh plugin --profile web add /path/to/dsh-usage-state
 
 ## 兼容性
 
-- 实测环境：DSH `0.1.5-rc.2` 与 `0.2.0-rc.2`，Node ≥ 20。DSH 版本要求通过 `engines.dsh` 声明为 `>=0.1.5-rc.1 <0.3.0-0`，即 **0.1.5 起的整条 0.1 线与 0.2 线**（dsh-market 的兼容徽标与"可安装"判定读的就是它）。
+- **只支持 DSH 0.2 线**：`engines.dsh` = `>=0.2.0-rc.2 <0.3.0-0`（市场读它做徽标与"可安装"判定）。0.2 之前的宿主请装 `0.3.2`。
+- `peerDependencies` 里有 `@deepseek-ai/dsh-settings`（`^0.2.0-rc.2`）与 `@deepseek-ai/schemastery`（`^3.18.2`）：前者是**故意的**——平台的运行时安装闸门只读 `@deepseek-ai/dsh*` 的 peer，声明它可以让 0.1.x 宿主在**安装时**就拒绝，而不是装上之后把启动搞崩；两者都由平台提供，pnpm 可能为此打一行 `missing peer` 警告，属预期。
+- 版本 `0.4.0`：迁到 0.2 原生设置模型（`Config` + `configForms`，宿主侧 `configEditor` 读跨条目配置）。验证方式与结论见 [`docs/implementation.md`](docs/implementation.md) §10、决策见 [`docs/design-consensus.md`](docs/design-consensus.md) 修订 17。
+- 版本 `0.3.2`（0.1 线末版）：仅放宽 `engines.dsh`；**它声称的 0.2 兼容是错的**（0.3.2 在 0.2.0-rc.2 上会因 `settingsScope` 不存在而让整个 web 启动失败）。
 - 同名发布在 npm（[`dsh-usage-state`](https://www.npmjs.com/package/dsh-usage-state)），也可从 GitHub 直接安装。
-- 版本 `0.3.2`：DSH 0.2 发布线的兼容复核（无代码改动，只放宽 `engines.dsh`）；DeepSeek、z.ai 与 OpenCode Zen Go 已在真机验证，其余见下。
 
 ## 已知限制
 

package/cordis.patch.yml

@@ -1,7 +1,18 @@
 # Mount layer contributed by this plugin.
 #
 # `dsh plugin add` appends this package to the profile's `dsh.profile.bundles`,
-# which applies this patch on boot; the row id only has to be unique.
+# which applies this patch on boot.
+#
+# The row id **is the settings namespace** on DSH 0.2 (`configForms.get(id)` on the
+# client, `entry.options.id` on the host), so it has to keep matching
+# `USAGE_STATE_NS` in `src/host/settings.ts`.
+#
+# `config: {}` gives every install a section to resolve: without it the entry has
+# no config at all, the settings projection answers `undefined`, and the status
+# line stays silent until the user saves something. A user's own
+# `- id: usage-state, config: { … }` row still replaces this whole value, because
+# the profile patch layer applies after every bundle layer.
 - insert:
     - id: usage-state
       name: dsh-usage-state
+      config: {}

package/lib/client.js

@@ -1524,6 +1524,54 @@ window.__ModuleLoader__.load({
 			}
 		}
 		//#endregion
+		//#region src/client/settings-form.ts
+		/**
+		* Present one `configForms` entry as the settings scope the components consume.
+		*
+		* Two things the platform form does not do for us:
+		*
+		* - **Decoding.** The host hands the stored section through unchanged, because this
+		*   plugin's schema declares no fields on purpose (see `host/settings.ts`). So
+		*   `normalizeConfig` runs here, keeping the single lenient decoder the plugin has
+		*   always had. A namespace the platform has not answered yet keeps `value`
+		*   undefined, which is what makes the status line stay silent instead of drawing
+		*   defaults the host never accepted.
+		* - **Snapshot identity.** `useSettingsValue` stores whatever `getSnapshot()`
+		*   returns, so a fresh object per call would re-render forever. The decoded
+		*   snapshot is cached against the platform snapshot it came from.
+		*/
+		function usageStateSettings(form) {
+			let source;
+			let decoded;
+			const snapshot = () => {
+				const next = form.getSnapshot();
+				if (decoded === void 0 || next !== source) {
+					source = next;
+					decoded = {
+						status: next.status,
+						value: next.value === void 0 ? void 0 : normalizeConfig(next.value),
+						revision: next.revision,
+						writable: next.writable,
+						mode: next.mode
+					};
+				}
+				return decoded;
+			};
+			return {
+				getSnapshot: snapshot,
+				subscribe: (listener) => form.subscribe(listener),
+				set: async (field, value) => {
+					await form.set(field, value);
+				},
+				unset: async (field) => {
+					await form.unset(field);
+				},
+				mutate: async (ops, expectedRevision) => {
+					await form.mutate(ops, expectedRevision);
+				}
+			};
+		}
+		//#endregion
 		//#region src/client/slots.ts
 		const STATUS_LINE_SLOTS = [{
 			name: "conversation.composer.dock",
@@ -1680,7 +1728,7 @@ window.__ModuleLoader__.load({
 		const inject = [
 			"slots",
 			"locale",
-			"settingsScope",
+			"configForms",
 			"remote",
 			"remote.session",
 			"remote.credentials"
@@ -1727,10 +1775,7 @@ window.__ModuleLoader__.load({
 				en
 			}), "dsh-usage-state: dictionaries");
 			const t = ctx.locale.bind(LOCALE_NS);
-			const settings = ctx.settingsScope.bind({
-				namespace: USAGE_STATE_NS,
-				decode: (section) => normalizeConfig(section)
-			});
+			const settings = usageStateSettings(ctx.configForms.get(USAGE_STATE_NS));
 			const usageStateRemote = () => remoteService(ctx, "remote.usageState");
 			const store = new UsageStateClientStore({
 				getState: async (force) => {

package/lib/index.js

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import z from "@deepseek-ai/schemastery";
 //#region src/shared/config.ts
 const DEFAULT_CONFIG = {
 	models: [],
@@ -1410,29 +1411,42 @@ var UsageStateService = class {
 };
 //#endregion
 //#region src/host/settings.ts
-/** Settings namespace owned by this plugin; must match `/^[a-z][a-z0-9-]*$/`. */
-const USAGE_STATE_NS = "usage-state";
-const usageStateSchema = Object.assign((section) => normalizeConfig(section), { toJSON: () => ({
-	uid: 1,
-	refs: { 1: {
-		type: "object",
-		meta: {},
-		dict: {}
-	} }
-}) });
 /**
-* Register the namespace and keep a live in-process snapshot of it.
+* The plugin's `Config`, which the 0.2 loader resolves from this module export
+* (`entry.fiber.runtime.Config`), validates with `Config['~standard']`, and hands
+* to `apply` as its second argument.
 *
-* `ctx.inject` is the graceful-degradation boundary: on a host without a settings
-* provider the callback never runs and the plugin's own defaults stand. `applies`
-* is metadata in this DSH version — what actually makes a change live is the
-* `watch` subscription below.
+* Two deliberate choices, both about staying compatible with documents this
+* plugin does not fully control:
+*
+* - **A volatile root.** The loader hands a volatile schema's value over as a live
+*   reference, commits edits into it in place, and announces them as
+*   `loader/volatile-update`. A non-volatile schema would instead find the config
+*   "changed" on every settings write and remount the plugin.
+* - **`any`, not a field-by-field object.** The settings service projects form
+*   values *through* the schema, so a declared object schema silently drops every
+*   field it does not declare — including keys a hand-edited document carries, and
+*   including keys a future version adds. Validation stays where it has always
+*   been: `normalizeConfig`, which is deliberately lenient, so a dirty document
+*   still loads instead of failing the entry.
+*/
+const Config = z.any().volatile();
+/**
+* Keep a live snapshot of the plugin's own config.
+*
+* `reference` is `apply`'s second argument. On a host that does not model volatile
+* config (or when the entry carries no schema) the loader passes nothing, and the
+* plugin keeps its own defaults — the same graceful degradation the 0.1 path got
+* from `ctx.inject(['settings'], …)`, which 0.2 no longer offers.
 */
-function installUsageStateSettings(ctx, onConfig) {
-	ctx.inject(["settings"], (settingsCtx) => {
-		const scope = settingsCtx.settings.register(USAGE_STATE_NS, usageStateSchema, { applies: "live" });
-		onConfig(normalizeConfig(scope.get()));
-		scope.watch((next) => onConfig(normalizeConfig(next)));
+function installUsageStateSettings(ctx, reference, onConfig) {
+	if (reference === void 0) return;
+	const publish = () => {
+		onConfig(normalizeConfig(reference.get()));
+	};
+	publish();
+	ctx.on("loader/volatile-update", () => {
+		publish();
 	});
 }
 //#endregion
@@ -1598,11 +1612,38 @@ function resolveTargets(config, options = {}) {
 const name = "usage-state";
 /** `timer` is what provides `ctx.timeout` / `ctx.interval`. */
 const inject = ["timer"];
+/** The shared volatile-reference protocol (`cosmokit.volatile.write`). */
+const VOLATILE_WRITE = Symbol.for("cosmokit.volatile.write");
+/** Whether a loader config value is a live volatile reference rather than data. */
+function isVolatileRef(value) {
+	return typeof value === "object" && value !== null && VOLATILE_WRITE in value && typeof value.get === "function";
+}
+/**
+* Detach a loader config: volatile fields are live references, and a snapshot is
+* only useful once they are read out. Mirrors the platform's own `plainConfig`,
+* including its refusal to guard against cycles (config cannot contain one).
+*/
+function plainConfig(value) {
+	if (isVolatileRef(value)) return plainConfig(value.get());
+	if (Array.isArray(value)) return value.map((item) => plainConfig(item));
+	if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, plainConfig(item)]));
+	return value;
+}
+/**
+* Another plugin's resolved config, by profile entry id.
+*
+* DSH 0.1 answered this from `settings.get(namespace)`; 0.2 derives every
+* namespace from the entry that owns it, so the resolved value lives on that
+* entry's fiber (the same place the platform's settings service reads it).
+* A host without a config editor degrades to `undefined`, which is what this
+* plugin's provider refinement has always done when a namespace was absent.
+*/
 function readNamespace(ctx, namespace) {
-	const settings = ctx.get("settings");
-	if (settings?.get === void 0) return void 0;
+	const editor = ctx.get("configEditor");
+	if (typeof editor?.entries !== "function") return void 0;
 	try {
-		return settings.get(namespace);
+		const entry = editor.entries().find((candidate) => candidate.options?.id === namespace);
+		return entry?.fiber?.config === void 0 ? void 0 : plainConfig(entry.fiber.config);
 	} catch {
 		return;
 	}
@@ -1675,7 +1716,7 @@ function createUsageState(ctx, deps = {}) {
 	const catalog = toSourceCatalog(ALL_SOURCES);
 	const lookup = createCredentialLookup(ctx, deps.credentialFallback ?? {});
 	let config = DEFAULT_CONFIG;
-	installUsageStateSettings(ctx, (next) => {
+	installUsageStateSettings(ctx, deps.config, (next) => {
 		config = next;
 	});
 	/**
@@ -1757,8 +1798,12 @@ function createUsageState(ctx, deps = {}) {
 	store.start();
 	return provideUsageState(ctx, service);
 }
-function apply(ctx) {
-	createUsageState(ctx);
+/**
+* Cordis entry point. The second argument is the loader's resolved config for this
+* entry — a live reference, because the exported schema is a volatile root.
+*/
+function apply(ctx, config) {
+	createUsageState(ctx, { config });
 }
 //#endregion
-export { apply, createCredentialLookup, createUsageState, inject, name, provideUsageState };
+export { Config, apply, createCredentialLookup, createUsageState, inject, isVolatileRef, name, plainConfig, provideUsageState };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "dsh-usage-state",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "type": "module",
   "description": "DSH plugin: show account balance (API mode) or coding-plan quota (5h/7d/30d) for the model in use",
   "license": "MIT",
   "engines": {
     "node": ">=20",
-    "dsh": ">=0.1.5-rc.1 <0.3.0-0"
+    "dsh": ">=0.2.0-rc.2 <0.3.0-0"
   },
   "scripts": {
     "test": "node --import ./tests/support/client-render-hook.mjs --test",
@@ -28,12 +28,13 @@
     "./package.json": "./package.json"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-client-locale": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-store": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-conversation": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-primitives": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-client-ui-slots": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-typert-loader": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-client-locale": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-store": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-conversation": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.2.0-rc.2",
+    "@deepseek-ai/dsh-typert-loader": "^0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.2",
     "@types/node": "^24.0.0",
     "@types/react": "~18.3.1",
     "@types/react-dom": "~18.3.1",
@@ -43,6 +44,10 @@
     "typescript": "^5.9.2",
     "unrun": "^0.2.39"
   },
+  "peerDependencies": {
+    "@deepseek-ai/dsh-settings": "^0.2.0-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
   "dependencies": {
     "zod": "4.5.1"
   },