dsh-grok-subscription 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 2.0.2 — 2026-09-29
+
+- Read an omitted weekly percentage as **0% used / 100% remaining**, instead of telling a fresh billing period that the account has no quota number. Right after the 2026-09-28 rollover, `GET /v1/billing?format=credits` returned the unified-billing `config` (`isUnifiedBillingUser`, zero prepaid balance, zero on-demand cap, and a weekly `currentPeriod`) with no `creditUsagePercent`. That omission is proto3 dropping a zero scalar, not a new meter: the same account's `GetGrokCreditsConfig` response on grok.com (HTTP 200, `grpc-status: 0`) carried the same window and also omitted the usage-ratio field. Once usage was non-zero the field came back on the wire, and an explicit number still wins. The zero is adopted only when the period type is weekly or monthly, both bounds parse, the window contains the current time, and no percentage exists on the body or on a product row. Prepaid balance and on-demand cap are still not a percentage. Outside that window the card stays unavailable. An explicit `0` is shown the same way but is not marked as omitted.
+- The reading carries `percentSource: 'omitted-zero'`. Settings prints that caveat under the gauge (both locales), and the composer badge shows the remaining 100% because the status is now `ok`. `sanitizeUsage` forwards only that exact source tag.
+- The **256k context window is the live catalog, not a plugin cap**. `models-v2` on 2026-09-29 returns `context_window: 256000` for `grok-4.7`, `grok-4.7-build-fast`, `grok-4.6` and `grok-4.5`. The plugin already prefers that field; 500000 was only the fallback used when the field was absent, which is why the picker used to say 500. The static fallback now matches the current catalog (256000) so an empty listing does not advertise a window the proxy no longer publishes. A catalog value, including a future 500000, still wins.
+
+## 2.0.1 — 2026-09-29
+
+- Fix **the quota card reporting a raw parser error for an account the upstream API stopped describing with a percentage**. Since the weekly period rolled over on 2026-09-28T16:46Z, `GET /v1/billing?format=credits` answers with a `config` object that carries `isUnifiedBillingUser`, `prepaidBalance`, `onDemandCap`, `onDemandUsed`, `topUpMethod` and the period bounds — and no `creditUsagePercent`, no `productUsage`, and no used/total pair. Every reader in the plugin is unchanged since 1.0.20, so the card simply failed closed with `不可用: Missing creditUsagePercent (keys: config)`, which reads like a broken plugin rather than an upstream shape the plugin does not recognise. Reproduced on a second machine with the same account: same build, same headers, only the clock moved.
+- Name the shape instead of a missing field. The unavailable reading now carries a `code` (`unified-billing` or `missing-percent`) plus the period bounds, the panel renders localized copy for a named code and keeps the raw diagnostic as a hint underneath, and an unnamed failure still shows its own reason.
+- **Show the window even when there is no percentage.** The period start and end come from the same response, so the card now prints `本期窗口: 2026/09/29 00:46:29 → 2026/10/06 00:46:29` whether or not a reading came back. A reset time is never lost to a shape change.
+- Still no invented numbers. A zero prepaid balance and a zero on-demand cap are not a percentage, so the card shows no gauge and the composer badge stays hidden; `parseBillingCredits` is asserted against the captured live body to keep it that way.
+- No adapter, routing, session or RPC-surface changes. `sanitizeUsage` carries the new diagnostic fields through the RPC without exposing anything else.
+
+## 2.0.0 — 2026-09-28
+
 ## 2.0.0 — 2026-09-28
 
 - **Remove the bundled Responses adapter. The `grok-build` route is now always the host's own pi-ai adapter.** The bundled implementation and everything that existed only to support it are gone: its request building, encrypted-reasoning envelope, prompt-cache and usage mapping and image collection (`src/adapter.js` drops from 1081 to 467 lines), the synchronous duck registration, `createGrokBuildAdapterSync` / `createDuckHostAdapter`, the release-then-re-register upgrade 1.2.0 added, and the `DSH_GROK_ADAPTER=fallback` switch. `apply` still returns immediately and builds the adapter from a deferred task, but registers exactly once.

package/README.en.md

@@ -61,13 +61,13 @@ Pick a Grok model your account can use, adjust reasoning effort as needed, and s
 <details>
 <summary>Check the version / pin one / fall back when the UI install fails</summary>
 
-**Settings → Plugins** lists the installed plugins and their versions, and the plugin's own **Settings → Grok Subscription** page shows a version card. To pin a version, put the full `package@version` in the install field, for example `dsh-grok-subscription@2.0.0`.
+**Settings → Plugins** lists the installed plugins and their versions, and the plugin's own **Settings → Grok Subscription** page shows a version card. To pin a version, put the full `package@version` in the install field, for example `dsh-grok-subscription@2.0.2`.
 
 If the UI install fails (an unusual profile directory, say), the equivalent runs against the desktop profile itself (pnpm ≥ 11):
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.2
 ```
 
 `dsh plugin --profile desktop …` is refused: the Electron application owns that profile exclusively. CLI paths, sign-in, and troubleshooting are in the [full user guide](docs/guide.en.md).

package/README.md

@@ -61,13 +61,13 @@
 <details>
 <summary>确认版本 / 固定版本 / 界面安装失败时的兜底</summary>
 
-**设置 → 插件** 会列出已安装插件与版本，插件自己的 **设置 → Grok 订阅** 页也有版本卡片。要固定版本，在安装框里填入完整的 `包名@版本`，例如 `dsh-grok-subscription@2.0.0`。
+**设置 → 插件** 会列出已安装插件与版本，插件自己的 **设置 → Grok 订阅** 页也有版本卡片。要固定版本，在安装框里填入完整的 `包名@版本`，例如 `dsh-grok-subscription@2.0.2`。
 
 界面安装失败时（例如 profile 目录权限异常），可以对桌面版 profile 手动执行等价操作（pnpm ≥ 11）：
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.2
 ```
 
 `dsh plugin --profile desktop …` 会被拒绝：桌面版 profile 由 Electron 应用独占。CLI 路径、登录方式与故障排查见 [完整使用指南](docs/guide.zh-CN.md)。

package/docs/guide.en.md

@@ -8,7 +8,7 @@ For quick setup, see the [README](../README.en.md#install). This guide covers de
 
 You need the DeepSeek Harness desktop app, the official Grok Build CLI, and an account with Grok Build access. The plugin declares Node.js `^22.19.0 || >=24.0.0`; DSH peers use `>=0.1.5-rc.2 <0.3.0-0`, which spans the whole 0.1 and 0.2 lines. See [package.json](../package.json) for the full requirements. Declared compatibility is not a claim that every version has passed live verification.
 
-**Install:** in the desktop app open **Settings → Plugins**, type the package name `dsh-grok-subscription` into the install field, and install it. Then **quit and restart the desktop app completely**; refreshing the page alone does not reload the Host adapter. To pin a version, put the full `package@version` in that field, for example `dsh-grok-subscription@2.0.0`.
+**Install:** in the desktop app open **Settings → Plugins**, type the package name `dsh-grok-subscription` into the install field, and install it. Then **quit and restart the desktop app completely**; refreshing the page alone does not reload the Host adapter. To pin a version, put the full `package@version` in that field, for example `dsh-grok-subscription@2.0.2`.
 
 **The plugin depends on the host's own pi-ai adapter.** From 2.0.0 the `grok-build` route is served entirely by the host's `@deepseek-ai/dsh-llm-pi-ai` / `@earendil-works/pi-ai`, which every DSH installation carries (`@deepseek-ai/dsh` → `dsh-base` → `dsh-llm-pi-ai`, with the `llm-pi-ai` row mounted unconditionally). If those packages cannot be resolved from the DSH installation, the plugin registers no route at all and **Active path** in Settings reads **unavailable**.
 
@@ -16,7 +16,7 @@ If the UI install fails (an unusual profile directory, say), the equivalent runs
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.2
 ```
 
 `dsh plugin --profile desktop …` is refused: the Electron application owns that profile exclusively.
@@ -69,7 +69,7 @@ The `grok-build` route is served by the host's official pi-ai adapter, which als
 
 Usage is read through the undocumented `/v1/billing?format=credits` endpoint and is experimental. Settings displays the used and remaining percentages actually returned. Interface changes, network failures, or invalid authentication can make the data unavailable.
 
-The composer badge appears only for `grok-build` with a successful usage read; hover or click for weekly quota and its reset time. Missing data does not mean zero quota. A failed read does not invent percentages or independently block chat.
+The composer badge appears only for `grok-build` with a successful usage read; hover or click for weekly quota and its reset time. A failed read does not invent a percentage or independently block chat. The one exception is protobuf omitting a zero: a complete weekly or monthly `currentPeriod` that contains the current time, with no percentage field anywhere, displays as 0% used and 100% remaining, and the card says that zero was omitted rather than reported. A window that does not contain now, a prepaid balance or on-demand cap alone, or a product row that already has a percentage still produces no number.
 
 For prefix caching, the plugin pins one stable `prompt_cache_key` per DSH session (`grok:<sessionId>`) and writes it into every request; tool ordering stays stable. Auxiliary requests (compaction, session titles) share the session's key rather than taking a separate one; measured against the proxy, isolating them did not improve the chat prefix's cache reads. These are request-construction measures, not a guarantee of backend cache hits or quota savings. No invented hit rate is reported. See [adapter.js](../src/adapter.js).
 
@@ -101,7 +101,7 @@ In the desktop app the `desktop` profile is owned exclusively by the Electron ap
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.2
 ```
 
 Then quit and restart the desktop app completely. After a successful update the profile's `package.json` dependency should show the target version while its `dsh.profile.bundles` entry is unchanged. Refreshing the browser is not enough: without a Host restart the old version keeps loading.

package/docs/guide.zh-CN.md

@@ -8,7 +8,7 @@
 
 需要 DeepSeek Harness 桌面版、官方 Grok Build CLI，以及当前具有 Grok Build 使用资格的订阅账号。插件的 Node.js 要求为 `^22.19.0 || >=24.0.0`，DSH peer 声明以 [package.json](../package.json) 为准；其中 DSH 依赖使用 `>=0.1.5-rc.2 <0.3.0-0`，覆盖 0.1 与 0.2 全线。声明范围不等于所有版本都已经过实机验证。
 
-**安装：** 在桌面版打开 **设置 → 插件**，在安装输入框里填入包名 `dsh-grok-subscription` 并安装，然后**完全退出并重启桌面应用**。仅刷新页面不会重新加载 Host 中的适配器。需要可重复安装时，填入完整的 `包名@版本`，例如 `dsh-grok-subscription@2.0.0`。
+**安装：** 在桌面版打开 **设置 → 插件**，在安装输入框里填入包名 `dsh-grok-subscription` 并安装，然后**完全退出并重启桌面应用**。仅刷新页面不会重新加载 Host 中的适配器。需要可重复安装时，填入完整的 `包名@版本`，例如 `dsh-grok-subscription@2.0.2`。
 
 **插件依赖宿主自带的 pi-ai 适配器。** 从 2.0.0 起，`grok-build` 路由完全由宿主的 `@deepseek-ai/dsh-llm-pi-ai` / `@earendil-works/pi-ai` 服务；DSH 的任何安装方式都带有它们（`@deepseek-ai/dsh` → `dsh-base` → `dsh-llm-pi-ai`，且 `llm-pi-ai` 行无条件挂载）。这两个包无法从 DSH 安装目录解析时，插件不会注册任何路由，设置页的「运行通路」显示**不可用**。
 
@@ -16,7 +16,7 @@
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.2
 ```
 
 `dsh plugin --profile desktop …` 会被直接拒绝：桌面版 profile 由 Electron 应用独占。
@@ -69,7 +69,7 @@ grok-4.6
 
 用量通过未公开的 `/v1/billing?format=credits` 接口读取，属于实验性能力。设置页展示实际返回的已用和剩余比例；接口变化、网络异常或认证失效都可能使数据不可用。
 
-输入框徽章仅在当前 provider 为 `grok-build` 且用量读取成功时显示，悬停或点击查看每周余量与重置时间。缺失数据不是额度为零；读取失败不会编造百分比，也不会因为单独的额度读取故障阻止聊天。
+输入框徽章仅在当前 provider 为 `grok-build` 且用量读取成功时显示，悬停或点击查看每周余量与重置时间。读取失败不会编造百分比，也不会因为单独的额度读取故障阻止聊天。唯一的例外是 protobuf 把 0 省略掉：响应里有完整的周或月 `currentPeriod`、窗口包住当前时间、并且没有任何百分比字段时，显示已用 0%、剩余 100%，并标明这是零值省略。窗口对不上、只有预付余额或按量上限、或者产品明细里已经有百分比时，仍然不显示数字。
 
 前缀缓存方面，插件为同一 DSH 会话固定同一个 `prompt_cache_key`（`grok:<sessionId>`），并在请求里显式写入，工具顺序保持稳定。压缩、会话标题这类辅助请求与会话共用同一个 key，而不是另开一个——对代理实测下来，隔离它们并不会提高聊天前缀的缓存命中。这些是请求构造措施，不保证服务端缓存命中或节省额度；项目不提供虚构的命中率。实现见 [adapter.js](../src/adapter.js)。
 
@@ -101,7 +101,7 @@ grok-4.6
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.2
 ```
 
 然后完全退出并重启桌面版。更新成功后该 profile 的 `package.json` 里依赖应变为目标版本，`dsh.profile.bundles` 条目保持不变。仅刷新网页不够：Host 未重启时仍会加载旧版本。

package/lib/client.js

@@ -39,7 +39,7 @@ var import_react2 = require("react");
 var zh = {
   nav: "Grok \u8BA2\u9605",
   title: "Grok \u8BA2\u9605",
-  subtitle: "\u7528 SuperGrok / X Premium\uFF08Grok Build\uFF09\u4F1A\u8BDD\uFF0C\u800C\u4E0D\u662F XAI_API_KEY\u3002\xB7 2.0.0",
+  subtitle: "\u7528 SuperGrok / X Premium\uFF08Grok Build\uFF09\u4F1A\u8BDD\uFF0C\u800C\u4E0D\u662F XAI_API_KEY\u3002\xB7 2.0.2",
   signedIn: "\u5DF2\u767B\u5F55",
   signedOut: "\u672A\u767B\u5F55",
   account: "\u8D26\u6237",
@@ -86,6 +86,10 @@ var zh = {
   usageUsed: "\u5DF2\u7528",
   usageRemaining: "\u5269\u4F59\u7EA6",
   usageReset: "\u5468\u671F\u7ED3\u675F / \u91CD\u7F6E",
+  usageWindow: "\u672C\u671F\u7A97\u53E3",
+  usageUnifiedBilling: "\u4E0A\u6E38\u672A\u8FD4\u56DE\u989D\u5EA6\u767E\u5206\u6BD4\uFF1A\u8BE5\u8D26\u53F7\u5DF2\u662F\u7EDF\u4E00\u8BA1\u8D39\u5F62\u6001\uFF08\u4EE5\u9884\u4ED8\u4F59\u989D\u4E0E\u6309\u91CF\u4E0A\u9650\u8BA1\u91CF\uFF09\uFF0C\u56E0\u6B64\u6CA1\u6709\u53EF\u5C55\u793A\u7684\u5468\u989D\u5EA6\u8BFB\u6570\u3002",
+  usageMissingPercent: "\u4E0A\u6E38\u672A\u8FD4\u56DE\u989D\u5EA6\u767E\u5206\u6BD4\uFF0C\u672C\u671F\u6682\u65E0\u53EF\u7528\u8BFB\u6570\u3002",
+  usageOmittedZero: "\u63A5\u53E3\u7701\u7565\u4E86 0 \u503C\u767E\u5206\u6BD4\uFF0C\u56E0\u6B64\u663E\u793A\u4E3A\u5DF2\u7528 0%\u3001\u5269\u4F59 100%\u3002\u8FD9\u4E0D\u662F\u53E6\u62A5\u7684\u6570\u5B57\uFF1B\u7A97\u53E3\u5BF9\u4E0D\u4E0A\u5F53\u524D\u65F6\u95F4\u65F6\u4E0D\u4F1A\u8FD9\u6837\u663E\u793A\u3002",
   usageUnavailable: "\u4E0D\u53EF\u7528",
   usageRefresh: "\u5237\u65B0\u7528\u91CF",
   usageOpenGrok: "\u5728 grok.com \u67E5\u770B\u7528\u91CF",
@@ -120,7 +124,7 @@ var zh = {
 var en = {
   nav: "Grok Subscription",
   title: "Grok Subscription",
-  subtitle: "Use a SuperGrok / X Premium (Grok Build) session, not XAI_API_KEY. \xB7 2.0.0",
+  subtitle: "Use a SuperGrok / X Premium (Grok Build) session, not XAI_API_KEY. \xB7 2.0.2",
   signedIn: "Signed in",
   signedOut: "Signed out",
   account: "Account",
@@ -167,6 +171,10 @@ var en = {
   usageUsed: "Used",
   usageRemaining: "Remaining \u2248",
   usageReset: "Period end / reset",
+  usageWindow: "Current window",
+  usageUnifiedBilling: "The upstream API returned no credit percentage: this account is on unified billing (measured by prepaid balance and an on-demand cap), so there is no weekly credit reading to show.",
+  usageMissingPercent: "The upstream API returned no credit percentage for this period.",
+  usageOmittedZero: "The API omitted a zero percentage, so this shows 0% used and 100% remaining. It is not a separately reported number, and it is not shown unless the billing window contains the current time.",
   usageUnavailable: "Unavailable",
   usageRefresh: "Refresh usage",
   usageOpenGrok: "View usage on grok.com",
@@ -830,6 +838,7 @@ function VersionCard({ call, t }) {
     ] }) : null
   ] });
 }
+var EXPLAINED_USAGE_CODES = /* @__PURE__ */ new Set(["unified-billing", "missing-percent"]);
 function UsagePanel({ usage, t, usageBusy, onRefresh, signedIn }) {
   const ok = usage?.status === "ok";
   const usedNumber = ok && Number.isFinite(usage.usedPercent) ? usage.usedPercent : void 0;
@@ -866,10 +875,18 @@ function UsagePanel({ usage, t, usageBusy, onRefresh, signedIn }) {
           resetLabel
         ] }) : null,
         usage.periodEnd && usage.periodEndLocal ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("code", { children: usage.periodEnd }) : null
-      ] })
-    ] }) : /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("p", { className: "gsEmpty", children: [
-      t("usageUnavailable"),
-      usage?.reason ? `: ${usage.reason}` : ""
+      ] }),
+      usage.percentSource === "omitted-zero" ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: "gsHint", children: t("usageOmittedZero") }) : null
+    ] }) : /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "gsEmpty", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { children: EXPLAINED_USAGE_CODES.has(usage?.code) ? t(usage.code === "unified-billing" ? "usageUnifiedBilling" : "usageMissingPercent") : `${t("usageUnavailable")}${usage?.reason ? `: ${usage.reason}` : ""}` }),
+      usage?.periodStartLocal || usage?.periodEndLocal ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("p", { className: "gsHint", children: [
+        t("usageWindow"),
+        ": ",
+        usage?.periodStartLocal ?? usage?.periodStart ?? "\u2014",
+        " \u2192 ",
+        usage?.periodEndLocal ?? usage?.periodEnd ?? "\u2014"
+      ] }) : null,
+      EXPLAINED_USAGE_CODES.has(usage?.code) && usage?.reason ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: "gsHint", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("code", { children: usage.reason }) }) : null
     ] }),
     products.length > 0 ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "gsRows", children: products.map((row, index) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "gsRow", children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { children: row.name ?? "\u2014" }),

package/lib/index.js

@@ -323,6 +323,7 @@ async function readResponseJson(response, options = {}) {
 
 // src/catalog.js
 var REASONING_LEVELS = Object.freeze(["low", "medium", "high", "xhigh"]);
+var FALLBACK_CONTEXT_WINDOW = 256e3;
 function asId(value) {
   return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
@@ -360,8 +361,8 @@ function extractLiveModels(body) {
     models.push(Object.freeze({
       id,
       name: displayNameOf(id, object),
-      contextWindow: contextWindowOf(object) ?? 5e5,
-      maxTokens: contextWindowOf(object) ?? 5e5,
+      contextWindow: contextWindowOf(object) ?? FALLBACK_CONTEXT_WINDOW,
+      maxTokens: contextWindowOf(object) ?? FALLBACK_CONTEXT_WINDOW,
       reasoning: object.reasoning !== false,
       reasoningEfforts: reasoningEffortsOf(object)
     }));
@@ -372,8 +373,8 @@ function fallbackModels() {
   return FALLBACK_MODEL_IDS.map((id) => Object.freeze({
     id,
     name: id === "grok-4.7" ? "Grok 4.7" : id === "grok-4.6" ? "Grok 4.6" : "Grok 4.5",
-    contextWindow: 5e5,
-    maxTokens: 5e5,
+    contextWindow: FALLBACK_CONTEXT_WINDOW,
+    maxTokens: FALLBACK_CONTEXT_WINDOW,
     reasoning: true,
     reasoningEfforts: id === "grok-4.5" ? ["low", "medium", "high"] : ["low", "medium", "high", "xhigh"],
     defaultEffort: "high",
@@ -411,8 +412,8 @@ function toPiModels(models) {
       thinkingLevelMap,
       input: supportsImageInput(model.id) ? ["text", "image"] : ["text"],
       cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-      contextWindow: model.contextWindow ?? 5e5,
-      maxTokens: model.maxTokens ?? 5e5,
+      contextWindow: model.contextWindow ?? FALLBACK_CONTEXT_WINDOW,
+      maxTokens: model.maxTokens ?? FALLBACK_CONTEXT_WINDOW,
       compat: { supportsLongCacheRetention: false, supportsDeveloperRole: false }
     };
   });
@@ -457,10 +458,11 @@ async function loadCatalog(accessToken, options = {}) {
 // src/usage.js
 var USAGE_SOURCE = "billing-credits-undocumented";
 var SHANGHAI_TZ = "Asia/Shanghai";
-function unavailable(reason) {
+function unavailable(reason, extra = {}) {
   return Object.freeze({
     status: "unavailable",
     reason: typeof reason === "string" && reason.trim() ? reason.trim() : "Usage unavailable",
+    ...extra,
     experimental: true,
     source: USAGE_SOURCE
   });
@@ -516,6 +518,23 @@ function missingPercentReason(body) {
   }
   return `Missing creditUsagePercent (keys: ${keys.join(",")})`;
 }
+function isUnifiedBillingBody(body) {
+  const config = isPlainObject(body.config) ? body.config : void 0;
+  return config?.isUnifiedBillingUser === true || isPlainObject(config?.onDemandCap) || isPlainObject(config?.prepaidBalance);
+}
+function unifiedBillingReason(body) {
+  const config = isPlainObject(body.config) ? body.config : {};
+  const balance = asFiniteNumber(config.prepaidBalance);
+  const cap = asFiniteNumber(config.onDemandCap);
+  return `No credit percentage in this billing response (unified billing: prepaidBalance ${balance ?? "n/a"}, onDemandCap ${cap ?? "n/a"})`;
+}
+function periodFields(body) {
+  const { start, end } = resolvePeriodBounds(body);
+  return {
+    ...start ? { periodStart: start, periodStartLocal: formatShanghai(start) } : {},
+    ...end ? { periodEnd: end, periodEndLocal: formatShanghai(end) } : {}
+  };
+}
 function firstDefined(...values) {
   for (const value of values) {
     if (value !== void 0 && value !== null) return value;
@@ -567,6 +586,48 @@ function resolveUsedPercent(body) {
   }
   return void 0;
 }
+function nowMillis(options) {
+  if (options?.now instanceof Date) {
+    const ms = options.now.getTime();
+    return Number.isFinite(ms) ? ms : Date.now();
+  }
+  if (typeof options?.now === "number" && Number.isFinite(options.now)) return options.now;
+  return Date.now();
+}
+function currentPeriodOf(body) {
+  const config = isPlainObject(body.config) ? body.config : void 0;
+  if (isPlainObject(config?.currentPeriod)) return config.currentPeriod;
+  if (isPlainObject(body.currentPeriod)) return body.currentPeriod;
+  return void 0;
+}
+function productHasPercent(body) {
+  const raw = resolveProductUsage(body);
+  if (!Array.isArray(raw)) return false;
+  return raw.some((item) => {
+    if (!item || typeof item !== "object") return false;
+    return asFinitePercent(firstDefined(
+      item.creditUsagePercent,
+      item.usedPercent,
+      item.usagePercent,
+      item.percentUsed,
+      item.used_percent
+    )) !== void 0;
+  });
+}
+function omittedZeroReading(body, nowMs) {
+  const period = currentPeriodOf(body);
+  if (!period) return void 0;
+  const type = typeof period.type === "string" ? period.type.trim() : "";
+  if (!/weekly$/i.test(type) && !/monthly$/i.test(type)) return void 0;
+  const start = asIsoString(period.start);
+  const end = asIsoString(period.end);
+  if (!start || !end) return void 0;
+  const startMs = Date.parse(start);
+  const endMs = Date.parse(end);
+  if (!(endMs > startMs) || nowMs < startMs || nowMs >= endMs) return void 0;
+  if (productHasPercent(body)) return void 0;
+  return { start, end };
+}
 function resolvePeriodBounds(body) {
   const config = isPlainObject(body.config) ? body.config : void 0;
   const period = firstDefined(
@@ -620,16 +681,25 @@ function sanitizeProductUsage(raw) {
   }
   return rows.length ? Object.freeze(rows) : void 0;
 }
-function parseBillingCredits(body) {
+function parseBillingCredits(body, options = {}) {
   if (body === null || body === void 0) {
     return unavailable("Empty billing response");
   }
   if (typeof body !== "object" || Array.isArray(body)) {
     return unavailable("Unexpected billing response shape");
   }
-  const usedPercent = resolveUsedPercent(body);
+  const explicitPercent = resolveUsedPercent(body);
+  const omittedZero = explicitPercent === void 0 ? omittedZeroReading(body, nowMillis(options)) : void 0;
+  const usedPercent = explicitPercent ?? (omittedZero ? 0 : void 0);
   if (usedPercent === void 0) {
-    return unavailable(missingPercentReason(body));
+    const unified = isUnifiedBillingBody(body);
+    return unavailable(
+      unified ? unifiedBillingReason(body) : missingPercentReason(body),
+      {
+        code: unified ? "unified-billing" : "missing-percent",
+        ...periodFields(body)
+      }
+    );
   }
   const { start: periodStart, end: periodEnd } = resolvePeriodBounds(body);
   const productUsage = sanitizeProductUsage(resolveProductUsage(body));
@@ -640,12 +710,13 @@ function parseBillingCredits(body) {
     source: USAGE_SOURCE,
     usedPercent,
     remainingPercent,
+    ...omittedZero ? { percentSource: "omitted-zero" } : {},
     ...periodStart ? { periodStart, periodStartLocal: formatShanghai(periodStart) } : {},
     ...periodEnd ? { periodEnd, periodEndLocal: formatShanghai(periodEnd) } : {},
     ...productUsage ? { productUsage } : {}
   });
 }
-function parseBillingCreditsJson(text) {
+function parseBillingCreditsJson(text, options = {}) {
   if (typeof text !== "string") return unavailable("Non-text billing response");
   if (!text.trim()) return unavailable("Empty billing response");
   let body;
@@ -654,7 +725,7 @@ function parseBillingCreditsJson(text) {
   } catch {
     return unavailable("Invalid JSON from billing API");
   }
-  return parseBillingCredits(body);
+  return parseBillingCredits(body, options);
 }
 async function fetchBillingUsageOnce(accessToken, options = {}) {
   const fetchImpl = options.fetch ?? globalThis.fetch;
@@ -1936,6 +2007,10 @@ function sanitizeUsage(usage) {
   };
   if (out.status !== "ok") {
     out.reason = typeof usage.reason === "string" ? usage.reason : "Usage unavailable";
+    if (typeof usage.code === "string") out.code = usage.code;
+    for (const field of ["periodStart", "periodStartLocal", "periodEnd", "periodEndLocal"]) {
+      if (typeof usage[field] === "string") out[field] = usage[field];
+    }
     return out;
   }
   if (typeof usage.usedPercent === "number" && Number.isFinite(usage.usedPercent)) out.usedPercent = usage.usedPercent;
@@ -1945,6 +2020,7 @@ function sanitizeUsage(usage) {
   if (typeof usage.periodEnd === "string") out.periodEnd = usage.periodEnd;
   if (typeof usage.periodEndLocal === "string") out.periodEndLocal = usage.periodEndLocal;
   if (typeof usage.fetchedAt === "string") out.fetchedAt = usage.fetchedAt;
+  if (usage.percentSource === "omitted-zero") out.percentSource = "omitted-zero";
   if (Array.isArray(usage.productUsage)) {
     out.productUsage = usage.productUsage.filter((row) => row && typeof row === "object").map((row) => ({
       ...typeof row.name === "string" ? { name: row.name } : {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-grok-subscription",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Use a SuperGrok or X Premium Grok Build subscription in DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",