dsh-grok-subscription 1.0.0 → 1.0.2

package/CONTRIBUTING.md

@@ -0,0 +1,42 @@
+# Contributing
+
+Bug reports, focused fixes, and compatibility updates are welcome.
+
+## Before changing code
+
+- Keep one pull request focused on one problem. Do not bundle unrelated
+  refactors, generated artifacts, or release preparation.
+- Never commit credentials. This plugin reads a real Grok Build session, so no
+  `~/.grok/auth.json` contents, access or refresh tokens, account identifiers,
+  or raw subscription responses belong in the repository, tests, or issues.
+- Reuse DSH's native model, settings, tool, and plugin-lifecycle contracts
+  instead of introducing a parallel subsystem.
+
+## Local verification
+
+```sh
+npm install
+npm test
+npm run build
+```
+
+`lib/` is committed and generated by the build — never edit it by hand. Run
+`npm run build` and commit the result whenever `src/` changes; CI fails if the
+committed `lib/` differs from a fresh build.
+
+Changes that affect the DSH UI or the plugin lifecycle also need a check in a
+real DSH installation; source tests alone are not installed-product acceptance.
+The host-side adapter is loaded into memory, so restart `dsh web` before judging
+a host change, and hard-refresh the browser for client changes.
+
+## Pull requests
+
+Describe the user-visible problem, the smallest implemented change, the checks
+you ran, and any remaining compatibility risk. When user instructions change,
+keep `README.md` and `README.en.md` behaviourally aligned.
+
+The READMEs are user documentation. They explain the product and its supported
+use, not internal debugging history or private design discussion.
+
+A merged pull request does not imply an immediate npm release; maintainers batch
+fixes into planned releases.

package/README.en.md

@@ -0,0 +1,218 @@
+<div align="center">
+
+# DSH Grok Subscription — Use SuperGrok / X Premium subscriptions in DeepSeek Harness
+
+[简体中文](https://github.com/BaronCyrus/dsh-grok-subscription/blob/main/README.md) · **English**
+
+**Use your SuperGrok / X Premium (Grok Build) subscription directly in DeepSeek Harness**
+
+Reuse the official Grok Build CLI session — no `XAI_API_KEY` needed.
+Models, reasoning effort, and weekly quota all stay inside DSH.
+
+[![CI](https://github.com/BaronCyrus/dsh-grok-subscription/actions/workflows/ci.yml/badge.svg)](https://github.com/BaronCyrus/dsh-grok-subscription/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-grok-subscription?logo=npm&label=npm)](https://www.npmjs.com/package/dsh-grok-subscription)
+[![total npm downloads](https://img.shields.io/npm/dt/dsh-grok-subscription?logo=npm&label=total%20downloads)](https://www.npmjs.com/package/dsh-grok-subscription)
+[![MIT](https://img.shields.io/badge/license-MIT-111111.svg)](LICENSE)
+[![Star](https://img.shields.io/github/stars/BaronCyrus/dsh-grok-subscription?style=flat&logo=github&label=Star)](https://github.com/BaronCyrus/dsh-grok-subscription/stargazers)
+
+[Three-step start](#three-step-start) · [Install](#install) · [Contribute](CONTRIBUTING.md) · [Update and uninstall](#update-and-uninstall)
+
+</div>
+
+<p align="center">
+  <img src="docs/assets/grok-subscription-overview.webp" width="900" alt="Select Grok 4.7 in DeepSeek Harness and chat through a SuperGrok subscription">
+</p>
+
+## Three-step start
+
+1. **Install the plugin.** Run the command below; to select a candidate version, enter the full `package@version`, for example `dsh-grok-subscription@1.0.2`.
+
+   ```sh
+   dsh plugin --profile web add BaronCyrus/dsh-grok-subscription
+   ```
+
+2. **Sign in to the subscription.** Open **Settings → Grok Subscription** and click **CLI login** or **Device-code login**, then finish the official prompt in the terminal that started DSH. If you already ran `grok login` yourself, just click **Pull from Grok CLI** — nothing has to be pasted.
+3. **Start using it.** Pick a model such as Grok 4.7 in the model picker. The round badge next to the picker shows weekly remaining quota, and the model menu offers reasoning effort levels.
+
+Restart `dsh web` after installing or upgrading, otherwise the old `lib/` keeps running.
+
+## Why this plugin
+
+| Capability | What you get |
+| --- | --- |
+| **Direct subscription routing** | Reuse the official Grok Build CLI session — no `XAI_API_KEY` needed |
+| **Real model catalog** | Read the models the account can actually use (such as `grok-4.7`, `grok-4.6`, `grok-4.5`) from `/v1/models-v2`; nothing is exposed while signed out |
+| **Reasoning effort** | The model picker offers `low` / `medium` / `high` / `xhigh`, defaulting to `high`, matching the Codex interaction |
+| **Composer quota** | A badge beside the model picker shows weekly remaining percentage; hover or click for "Weekly quota · N% left · resets M/D HH:mm" |
+| **Usage panel (experimental)** | Settings shows the used and remaining percentages the backend reports, and never invents numbers when the read fails |
+| **Credentials stay local** | Only the short-lived access token from `~/.grok/auth.json` is read on the host; no token is handed to browser RPC |
+| **Sign-in state refreshes the UI** | Login, pull, and logout emit `llm/adapters-updated`, so the chat model list updates with them |
+| **Failures stay visible** | When subscription routing is unavailable it reports an error instead of silently using another paid route |
+
+These capabilities reuse the same local Grok Build sign-in.
+
+## Product screen
+
+<p align="center">
+  <img src="docs/assets/settings-account.webp" width="820" alt="The Grok Subscription page in DSH Settings: sign-in status, account, login buttons and credential notes">
+</p>
+
+The **Settings → Grok Subscription** screen shows sign-in status and a masked account, offers CLI login, device-code login, pull from the Grok CLI, and logout, and explains how credentials are read. Account and time values in the screenshot are demo data.
+
+<p align="center">
+  <img src="docs/assets/settings-usage.webp" width="820" alt="The experimental usage panel in Grok Subscription settings: 6% used, about 94% remaining">
+</p>
+
+The experimental usage panel comes from an undocumented subscription billing endpoint (`/v1/billing?format=credits`). It is informational: the endpoint may change or disappear, a failed read never shows an invented percentage, and chat is unaffected.
+
+## Prepare DSH
+
+This plugin supports the latest DeepSeek Harness release recorded in its package metadata and requires a **SuperGrok or X Premium** account that currently has Grok Build access.
+
+- **Already able to run `dsh`**: use the standard command below;
+- **Prefer the official path**: see the [DeepSeek Harness documentation](https://github.com/deepseek-ai/deepseek-harness#run).
+
+The plugin is strict about `~/.grok/auth.json`: it refuses symbolic links, files readable by group or others, and files not owned by the current user. If permissions are wrong:
+
+```sh
+chmod 600 "${GROK_HOME:-$HOME/.grok}/auth.json"
+```
+
+## Install
+
+### Standard DSH command
+
+```sh
+dsh plugin --profile web add BaronCyrus/dsh-grok-subscription
+```
+
+You can also install the version published on npm:
+
+```sh
+dsh plugin --profile web add dsh-grok-subscription@1.0.2
+```
+
+DSH handles target selection, the profile lock, dependency resolution, and bundle activation.
+
+### Headless
+
+Sign in and select a Grok model once in the Web UI, then install the same plugin into the standard DSH Headless profile:
+
+```sh
+dsh plugin --profile headless add BaronCyrus/dsh-grok-subscription
+dsh --profile headless "reply with exactly: ok"
+```
+
+<details>
+<summary>Official npm route (Node.js installed)</summary>
+
+The official `npx @deepseek-ai/dsh web` does not create a global `dsh` command, so keep the full `npx` prefix when installing the plugin:
+
+```sh
+npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web add BaronCyrus/dsh-grok-subscription
+npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web list dsh-grok-subscription --depth 0
+npx -y @deepseek-ai/dsh@0.1.5-rc.2 --profile web --dump-config
+```
+
+</details>
+
+<details>
+<summary>Verify the install when <code>dsh</code> already works</summary>
+
+```sh
+dsh plugin --profile web list dsh-grok-subscription --depth 0
+dsh --profile web --dump-config
+```
+
+The package list should contain exactly one `dsh-grok-subscription`, and the config exactly one `grok-build` route.
+
+</details>
+
+Restart DSH manually afterwards, then:
+
+1. Open **Settings → Grok Subscription**;
+2. Sign in with an account that has Grok Build access (browser login or device-code login);
+3. Select a Grok model in the model picker.
+
+## Features
+
+- Reuses the official Grok Build CLI session; credentials stay local and the account is identified by a partially masked email;
+- Models appear directly in DSH sessions with no `XAI_API_KEY`, and no token is exposed to the browser;
+- The model catalog is pulled after sign-in; a failed or timed-out read falls back to a built-in list and records the error, and it stays empty while signed out;
+- The model menu offers `low` / `medium` / `high` / `xhigh` reasoning effort, defaulting to `high`;
+- A weekly remaining quota badge sits beside the model picker in the composer, with remaining percentage and reset time on hover or click;
+- Settings can show the used and remaining percentages the backend reports, and says so plainly instead of guessing when the read fails;
+- Supports CLI login, device-code login, pull from the Grok CLI, and logout; the chat model list refreshes whenever sign-in state changes;
+- When subscription routing is unavailable it reports an error instead of silently switching to another paid route.
+
+### Composer quota
+
+<p align="center">
+  <img src="docs/assets/composer-quota.webp" width="820" alt="DSH composer: weekly remaining quota badge beside the Grok 4.7 model picker">
+</p>
+
+The badge appears only when the current session's provider is `grok-build` and the usage read succeeds; hover or click for "Weekly quota · N% left · resets M/D HH:mm". It reflects only the weekly quota the backend returns, and when the read fails the badge is simply hidden — chat is unaffected.
+
+### Reasoning effort
+
+After selecting a Grok model, the model menu exposes a reasoning effort submenu: `low` / `medium` / `high` / `xhigh`, defaulting to `high`. The levels come from `model.reasoning` metadata (`efforts` + `defaultEffort`), so the interaction matches Codex in DSH; the levels actually available depend on the account's model catalog.
+
+### Model catalog and sign-in state
+
+After sign-in the plugin reads the model catalog the account can actually use from the subscription proxy; while signed out it registers no models at all. If the read fails or times out it falls back to a built-in list (`grok-4.7` / `grok-4.6` / `grok-4.5`) and records the error in status, so the catalog is never left empty and plugin startup is never blocked.
+
+## Update and uninstall
+
+### Update and verify
+
+```sh
+dsh plugin --profile web update dsh-grok-subscription
+dsh plugin --profile web list dsh-grok-subscription --depth 0
+dsh --profile web --dump-config
+```
+
+### Uninstall
+
+Confirm you want the plugin removed, then run:
+
+```sh
+dsh plugin --profile web remove dsh-grok-subscription
+```
+
+These operations keep the DSH profile, other plugins, and the sign-in stored in `~/.grok/auth.json`.
+
+<details>
+<summary>Official npm fallback</summary>
+
+```sh
+npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web update dsh-grok-subscription
+npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web remove dsh-grok-subscription
+```
+
+</details>
+
+## Troubleshooting
+
+- **`dsh` is not recognized**: the official npm route never creates a global `dsh` command — use the full `npx -y @deepseek-ai/dsh@0.1.5-rc.2 ...` command above;
+- **The model list is empty**: nothing is exposed while signed out. Finish signing in, then click **Pull from Grok CLI**;
+- **Nothing changed after upgrading**: the plugin keeps running the old `lib/` — reinstall the plugin, restart `dsh web`, and hard-refresh (Ctrl+Shift+R);
+- **It reports `auth.json` permissions**: apply the `chmod 600` above; the plugin refuses symlinks and group- or other-readable files;
+- **"No reply" after sending a message**: upgrade to `1.0.1` or later. `1.0.0` had a defect where tool-calling turns aborted with a non-serializable stream chunk, leaving no reply in the UI at all.
+
+## Scope and support
+
+The Grok subscription backend and DSH can change independently; this is a community project with no affiliation or endorsement from DeepSeek or xAI.
+
+For sensitive issues read [SECURITY.md](SECURITY.md) first. For bug reports use [Issues](https://github.com/BaronCyrus/dsh-grok-subscription/issues).
+
+### Development checks
+
+```sh
+npm install
+npm test
+npm run build
+```
+
+`lib/` is a committed build artifact, so run `npm run build` after changing `src/`.
+
+[MIT](LICENSE)

package/README.md

@@ -1,186 +1,218 @@
-# dsh-grok-subscription
+# DSH Grok Subscription — 在 DeepSeek Harness 使用 SuperGrok / X Premium 订阅
 
-一个第一方形态的 **DeepSeek Harness 社区插件**：复用官方 Grok Build CLI 的 SuperGrok / X Premium 登录，在 DSH 中提供独立的 `grok-build` 模型路由，不覆盖 DSH 内置的 `xai` API-key 路由。
+<div align="center">
 
-## 它做什么
+**简体中文** · [English](https://github.com/BaronCyrus/dsh-grok-subscription/blob/main/README.en.md)
 
-- 读取 `${GROK_HOME:-~/.grok}/auth.json` 中的 OAuth 会话（不接受纯 API-key 项作为订阅登录）。
-- 通过 DSH credentials 仅保存短期 access token；refresh token 不离开 Grok CLI 文件。
-- 推理使用 OpenAI Responses：`https://cli-chat-proxy.grok.com/v1/responses`，不是 `api.x.ai`。
-- 登录后从 `GET https://cli-chat-proxy.grok.com/v1/models-v2` 获取账号可用模型；实时目录不可用或为空时使用小型静态目录（包含 `grok-4.7`）。`grok-4.7` 优先来自实时 `models-v2` 返回。
-- 未登录时仍注册 adapter，但模型列表为 **0**（fail closed）。
-- 设置页显示脱敏账户、登录状态、模型与最近一次目录错误，并提供 CLI 登录、设备码登录、从 Grok CLI 拉取、退出登录。
-- **实验性用量显示**：登录后从未文档化的 `GET /v1/billing?format=credits` 读取 `config.creditUsagePercent`（兼容顶层）与周期结束时间；失败时显示「不可用」且**绝不编造百分比**。不影响 Chat。
-- Pull / 登录 / 退出 / 目录刷新后通过 `llm/adapters-updated` 通知 Web 客户端刷新 Chat / New Session 模型选择器（emit 延后，避免与 Pull RPC 重入）。
-- 设置页 Pull **零出站网络、内存优先**：只读本地 auth.json，同步写入 `memoryAccessToken` 后立即返回；credentials.set / credentialRef 延后（带超时），不堵 Pull RPC；目录与用量由后台及客户端 fire-and-forget 的 `catalog/refresh` / `usage/refresh` 更新（不占用全局 busy）；`status` / `currentToken` 优先内存。
+**把 SuperGrok / X Premium（Grok Build）订阅直接接入 DeepSeek Harness**
 
-## 安装
+复用官方 Grok Build CLI 的登录会话，不需要 `XAI_API_KEY`。
+模型、推理档位和每周额度都留在 DSH 里。
 
-要求 Node.js `^22.19.0 || >=24`，并建议先安装官方 `grok` CLI。
+[![CI](https://github.com/BaronCyrus/dsh-grok-subscription/actions/workflows/ci.yml/badge.svg)](https://github.com/BaronCyrus/dsh-grok-subscription/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-grok-subscription?logo=npm&label=npm)](https://www.npmjs.com/package/dsh-grok-subscription)
+[![npm 总下载量](https://img.shields.io/npm/dt/dsh-grok-subscription?logo=npm&label=%E6%80%BB%E4%B8%8B%E8%BD%BD%E9%87%8F)](https://www.npmjs.com/package/dsh-grok-subscription)
+[![MIT](https://img.shields.io/badge/license-MIT-111111.svg)](LICENSE)
+[![Star](https://img.shields.io/github/stars/BaronCyrus/dsh-grok-subscription?style=flat&logo=github&label=Star)](https://github.com/BaronCyrus/dsh-grok-subscription/stargazers)
 
-```bash
-grok login
-# 从 GitHub 安装（推荐）
-dsh plugin --profile web add BaronCyrus/dsh-grok-subscription
-# 或本地路径
-# dsh plugin --profile web add /absolute/path/to/dsh-grok-subscription
-# 或 npm（发布后）
-# dsh plugin --profile web add dsh-grok-subscription@1.0.0
-```
+[三步开始](#三步开始) · [安装](#安装) · [参与贡献](CONTRIBUTING.md) · [更新与卸载](#更新与卸载)
 
-然后重启 `dsh web`，打开 **Settings → Grok 订阅**。也可以在设置页点击“CLI 登录”或“设备码登录”；设备码流程会在启动 DSH 的终端中显示提示。登录完成后点击“从 Grok CLI 拉取”可立即同步；Chat 模型列表会随之刷新。
+</div>
 
-升级到新版本后请重新安装插件（`add` 同一路径）并重启 `dsh web`，否则会继续跑旧的 `lib/`。
+<p align="center">
+  <img src="docs/assets/grok-subscription-overview.webp" width="900" alt="在 DeepSeek Harness 中选择 Grok 4.7 并使用 SuperGrok 订阅进行多轮对话">
+</p>
 
-若权限不正确：
+## 三步开始
 
-```bash
-chmod 600 "${GROK_HOME:-$HOME/.grok}/auth.json"
-```
+1. **安装插件**：在终端运行下面的命令；指定候选版本时填写完整的 `包名@版本`，例如 `dsh-grok-subscription@1.0.2`。
 
-开发检查：
+   ```sh
+   dsh plugin --profile web add BaronCyrus/dsh-grok-subscription
+   ```
 
-```bash
-npm install
-npm test
-npm run build
-```
+2. **登录订阅**：打开 **设置 → Grok 订阅**，点击 **CLI 登录** 或 **设备码登录**，在启动 DSH 的终端里完成官方提示。已经自己跑过 `grok login` 的话，直接点 **从 Grok CLI 拉取** 即可，不需要粘贴任何 token。
+3. **开始使用**：在模型选择器中选择 Grok 4.7 等模型。输入框旁的圆形徽章显示每周剩余额度，模型菜单里有推理档位。
 
-## v1.0.0
+安装或升级后需要重启 `dsh web`，否则会继续运行旧的 `lib/`。
 
-首个稳定版，已发布 npm：`dsh-grok-subscription@1.0.0`。内置模型选择器现可通过 `model.reasoning`（efforts + defaultEffort）展示 Grok Build 的 reasoning effort 子菜单（low/medium/high/xhigh），与 Codex 一致。修复 duck `listModels`/`resolveModel` 此前省略该元数据的问题。
+## 核心优势
 
-## v0.1.13
+| 能力 | 用户得到什么 |
+| --- | --- |
+| **订阅直连** | 复用官方 Grok Build CLI 会话，不需要 `XAI_API_KEY` |
+| **真实模型目录** | 登录后从 `/v1/models-v2` 读取账号实际可用的模型（如 `grok-4.7`、`grok-4.6`、`grok-4.5`）；未登录时不暴露任何模型 |
+| **推理档位** | 模型选择器内置 `low` / `medium` / `high` / `xhigh` 子菜单，默认 `high`，与 Codex 的交互一致 |
+| **输入框额度** | 模型选择器旁的徽章直接显示每周剩余比例，悬停或点击查看「每周额度 剩余 N% · 重置于 M/D HH:mm」 |
+| **用量面板（实验性）** | 设置页显示服务端返回的已用与剩余百分比，读取失败时不猜数字、不虚构额度 |
+| **凭据留在本机** | 只在主机侧读取 `~/.grok/auth.json` 的短期 access token；不会把 token 交给浏览器 RPC |
+| **登录状态会刷新界面** | 登录、拉取或登出后自动派发 `llm/adapters-updated`，Chat 模型列表随之更新 |
+| **失败可见** | 订阅路由不可用时明确报错，不会静默改用其他付费路由 |
 
-Chat 输入区模型选择旁增加 Codex 风格的每周剩余额度徽章（如 `16%`）；悬停/点击显示「每周额度 剩余 N% · 重置于 M/D HH:mm」。仅在当前会话 provider 为 `grok-build` 且用量 `ok` 时显示。Settings 中 Pull/登录成功后会派发刷新事件更新徽章。本地 0.1.13 供复测，**未发 npm**。升级后请用新 token URL 硬刷新。
+这些能力共用同一份本机 Grok Build 登录。
 
-## v0.1.12
+## 实际界面
 
-升级后请用 `dsh web` 新打印的带 token URL 打开，并硬刷新（Ctrl+Shift+R），避免旧 `/plugins` client 缓存。
+<p align="center">
+  <img src="docs/assets/settings-account.webp" width="820" alt="DSH 设置中的 Grok 订阅页面：登录状态、账号、登录按钮与凭据说明">
+</p>
 
-修复 0.1.11 实机：Settings → Plugins 仍卡在「Reading plugins…」，Pull 等到客户端 45s 超时。根因是 `status` / `currentToken` 仍可能无超时地 `await credentials.resolve` 与裸 `import('@deepseek-ai/dsh-credentials')`，楔住连接桥后 Plugins 清单也跟着挂。现：`credentialRefOf` 用 timed `optionalImport`；resolve 硬超时（默认 1.5s）；`status` 先内存 / auth.json，再可选 credentials；宿主 RPC 每端点 8s 硬超时；`llm/adapters-updated` 一律延后；`inject` 保持 `['llm','web']`；客户端缺 connection 软跳过，RPC 客户端超时降至 12s。本地 0.1.12 供复测，未发 npm。
+上图为 **设置 → Grok 订阅** 主界面：显示登录状态与脱敏账号，提供 CLI 登录、设备码登录、从 Grok CLI 拉取和登出，并说明凭据的读取方式。截图中的账号与时间均为演示数据。
 
-## v0.1.10
+<p align="center">
+  <img src="docs/assets/settings-usage.webp" width="820" alt="Grok 订阅设置页中的实验性用量面板：已用 6%、剩余约 94%">
+</p>
 
-修复 0.1.9 实机：Pull 仍可能 45s 超时，且 **Settings → Plugins** 卡在 `Reading plugins…`（宿主 Settings/RPC 通道被楔住）。根因是 `apply`/`boot` 路径会 `await` 无超时的动态 `import`（`pi-ai` / `dsh-llm-pi-ai` / schemastery），且 `inject` 含 sticky 的 `credentials`。现 `inject` 收窄为 `['llm','web']`；`apply` 同步注册 duck adapter 后立即返回；schemastery / `session.pull` / pi-ai 升级全部 `setImmediate` 延后；所有动态 import 硬超时（默认 2.5s），超时则保持 duck。保留 0.1.9 内存优先 Pull 与 0.1.8 客户端 fire-and-forget。
+实验性用量面板来自未公开的订阅计费接口（`/v1/billing?format=credits`）。它仅供参考：接口可能随时变化或消失，读取失败时不会显示编造的百分比，也不影响聊天。
 
-## v0.1.9
+## 准备 DSH
 
-修复 0.1.8 实机：Pull RPC 本身卡到客户端 45s 超时。根因是零网络 Pull 仍 `await storeToken` → `credentialRefOf()`（动态 import `@deepseek-ai/dsh-credentials`）无超时，import/set 与 DSH credentials 死锁时会拖死整个 Pull。现会话服务持有 `memoryAccessToken`；Pull 成功路径同步写入内存后立即返回，credentials 持久化与 clear 全部 `scheduleDeferred`；`currentToken` / `status` 优先内存。客户端仍保持 0.1.8 的 fire-and-forget 刷新行为。
+本插件支持软件包元数据中记录的最新版 DeepSeek Harness，并需要一个具有 Grok Build 使用资格的 **SuperGrok 或 X Premium** 账号。
 
-## v0.1.8
+- **已经能运行 `dsh`**：直接使用下面的标准命令；
+- **想按官方方式运行**：查看 [DeepSeek Harness 官方说明](https://github.com/deepseek-ai/deepseek-harness#run)。
 
-修复 0.1.7 实机：Pull 成功后客户端仍 await `usage/refresh` 并占用全局 busy，导致 Working… 卡住、按钮一直 disabled。现 Pull/登录成功后立即清 busy 并显示成功提示；`catalog/refresh` 与 `usage/refresh` 为 fire-and-forget（不置全局 busy）。仅「刷新用量」按钮使用本地 `usageBusy`。`fetchBillingUsage` 增加独立于 AbortSignal 的硬 `Promise.race` 超时（默认 8s）；空 JSON `{}` 与非 JSON Content-Type 会写入更明确的不可用原因。
+插件读取 `~/.grok/auth.json` 时较为严格：拒绝符号链接、拒绝组或其他用户可读的文件、拒绝非当前用户拥有的文件。如果权限不正确：
 
-## v0.1.7
+```sh
+chmod 600 "${GROK_HOME:-$HOME/.grok}/auth.json"
+```
 
-修复设置页 Pull 仍卡住 Working…（0.1.6 去掉 billing 后仍可能卡在 `credentials.set` 或 `loadCatalog`）：Pull 关键路径**零出站网络**，`storeToken` 硬超时（默认 5s），立即返回缓存目录/用量；后台 kick `refreshCatalog` + `refreshUsage`；客户端在 Pull 成功后另行 `catalog/refresh` 与 `usage/refresh`（独立 busy 文案）。`notifyCatalogChange` 仍仅延后触发。
+## 安装
+
+### DSH 标准命令
 
-## v0.1.6
+```sh
+dsh plugin --profile web add BaronCyrus/dsh-grok-subscription
+```
 
-修复设置页 Pull 卡住 Working…、用量长期「不可用」：Pull 关键路径不再等待 billing；`status()` 只返回缓存用量；Pull 成功后由客户端另行 `usage/refresh`；`llm/adapters-updated` 延后发出；客户端 RPC 增加超时保护。解析逻辑仍沿用 0.1.5 的 config.* 兼容。
+也可以按 npm 上的已发布版本安装：
 
-## v0.1.5
+```sh
+dsh plugin --profile web add dsh-grok-subscription@1.0.2
+```
 
-修复实验性用量解析：官方 `/v1/billing?format=credits` 实际把 `creditUsagePercent`、`currentPeriod`、`productUsage` 放在 `config` 下（非顶层）。0.1.4 因严格读顶层字段在 QA 中显示「不可用」。现同时接受 `config.*` 与顶层；不可用原因会附带顶层 key 名以便排查。**绝不编造百分比。**
+目标选择、profile 锁、依赖解析和 bundle 激活均由 DSH 负责。
 
-## v0.1.4
+### Headless
 
-实验性 SuperGrok 周用量显示：设置页新增「用量（实验性）」区块，只读请求 `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits`（与现有 OAuth + CLI fingerprint 请求头相同）。解析 `config.creditUsagePercent` / 顶层 `creditUsagePercent` 与 `config.currentPeriod.end`；RPC 提供 `usage` / `usage/refresh`，永不回传 token。失败 fail-closed 为「不可用」。**账单 API 未公开文档，可能随时变更。**
+先在 Web 中完成登录并选择一次 Grok 模型，再把同一个插件安装到 DSH 的标准 Headless profile：
 
-## v0.1.3
+```sh
+dsh plugin --profile headless add BaronCyrus/dsh-grok-subscription
+dsh --profile headless "只回复：ok"
+```
 
-修复多轮 Chat 中助手正文不显示的问题：自定义 Responses 流在 `block-end` 时把已累计的 text/reasoning 写成空字符串，Harness `BlockAssembler` 会用空块覆盖流式增量，导致第 2 轮起界面只见思考（如 “Deep diving…”）不见正文。同时为 `grok-build` 强制 `include: reasoning.encrypted_content`（与 pi-ai 对 `xai` 的处理对齐），保证推理密文可回放。
+<details>
+<summary>官方 npm 方式（已安装 Node.js）</summary>
 
-## v0.1.2
+官方的 `npx @deepseek-ai/dsh web` 不会创建全局 `dsh` 命令，因此安装插件时也要保留完整的 `npx` 前缀：
 
-设置页 Pull / 登录 / 退出成功后显示明确的内联成功反馈。
+```sh
+npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web add BaronCyrus/dsh-grok-subscription
+npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web list dsh-grok-subscription --depth 0
+npx -y @deepseek-ai/dsh@0.1.5-rc.2 --profile web --dump-config
+```
 
-## v0.1.1
+</details>
 
-修复 Chat / New Session 模型选择器在 Settings 已 Pull 到 `models-v2` 后仍只显示 DeepSeek 模型的问题：
+<details>
+<summary>已经能运行 <code>dsh</code> 时检查安装结果</summary>
 
-- PiAiAdapter 的 `profiles` 每次重建 provider，且 `getModels()` 读取当前 `session.models()`（不再依赖一次性的 `models: []` + `fetchModels`）。
-- Pull / 登录 / 退出 / 目录刷新后发出 `llm/adapters-updated`，让选择器刷新。
+```sh
+dsh plugin --profile web list dsh-grok-subscription --depth 0
+dsh --profile web --dump-config
+```
 
-v0.1.0 范围仍适用：仅文本/工具调用所需的 Responses 流、账号同步、动态模型目录和设置页。没有图片生成、画板、额度预测或 Codex 功能。官方 CLI 负责登录与 refresh-token 生命周期；插件不会实现或写回供应商 OAuth refresh。
+安装列表中应只有一个 `dsh-grok-subscription`，配置中应只有一个 `grok-build` 路由。
 
-## 注意事项
+</details>
 
-- 这是社区插件，不是 xAI、Grok 或 DeepSeek 官方产品。
-- 订阅账号用于非官方客户端可能处于供应商条款灰色地带；**只使用你自己的账号**，风险自担。
-- 官方文档没有发布完整 HTTP wire protocol；代理协议、请求头、模型 ID 或权限规则可能随时改变。
-- 用量面板依赖的 `/v1/billing?format=credits` **未公开文档**，属实验性功能；字段形状或可用性可能变化，失败时仅显示不可用。
-- 设置页发起 CLI 登录时，浏览器/设备码提示由官方 CLI 处理；远程部署请优先用 `grok login --device-auth`。
+安装完成后手动重启 DSH，然后：
 
-## English
+1. 打开 **设置 → Grok 订阅**；
+2. 登录具有 Grok Build 资格的账号（浏览器登录或设备码登录）；
+3. 在模型选择器中选择 Grok 模型。
 
-`dsh-grok-subscription` is a small community DSH plugin that reuses an official Grok Build CLI SuperGrok/X Premium session. It adds a separate `grok-build` route, calls the subscription Responses proxy, discovers models from `/v1/models-v2` (with a signed-in-only fallback including `grok-4.7`), and never exposes tokens to browser RPC. Settings also shows an **experimental** weekly usage panel from the undocumented `/v1/billing?format=credits` endpoint (fail-closed; never invents percentages; chat is unaffected). After Pull/login/logout the plugin emits `llm/adapters-updated` so the Chat model picker refreshes. Install locally with:
+## 功能
 
-```bash
-dsh plugin --profile web add BaronCyrus/dsh-grok-subscription
-```
+- 复用官方 Grok Build CLI 会话登录，凭据保留在本机；账号以部分隐藏的邮箱区分；
+- 模型直接出现在 DSH 会话中，无需 `XAI_API_KEY`，也不向浏览器暴露 token；
+- 模型目录登录后自动拉取；读取失败或超时时回退到内置列表并记录错误，未登录时保持为空；
+- 模型菜单提供 `low` / `medium` / `high` / `xhigh` 推理档位，默认 `high`；
+- 输入框模型选择器旁显示每周剩余额度徽章，悬停或点击查看剩余比例与重置时间；
+- 设置页可查看服务端返回的用量与剩余百分比，失败时明确提示而不是显示猜测值；
+- 支持 CLI 登录、设备码登录、从 Grok CLI 拉取和登出；登录状态变化后 Chat 模型列表自动刷新；
+- 订阅路由不可用时明确报错，不会静默切换到其他付费路由。
 
-Reinstall after upgrades, restart `dsh web`, then open **Settings → Grok Subscription**.
+### 输入框额度
 
-### v1.0.0
+<p align="center">
+  <img src="docs/assets/composer-quota.webp" width="820" alt="DSH 输入框：Grok 4.7 模型选择器旁的每周剩余额度徽章">
+</p>
 
-First stable release, published to npm as `dsh-grok-subscription@1.0.0`. Stock model picker now shows Grok Build reasoning effort (low/medium/high/xhigh) via `model.reasoning` metadata (`efforts` + `defaultEffort`), matching Codex. Fixes duck `listModels`/`resolveModel` omitting that shape.
+仅当当前会话的 provider 为 `grok-build` 且用量读取成功时显示徽章；悬停或点击可查看「每周额度 剩余 N% · 重置于 M/D HH:mm」。徽章只反映服务端返回的每周额度；读取失败时徽章不显示，聊天不受影响。
 
-### v0.1.13
+### 推理档位
 
-Chat 输入区模型选择旁增加 Codex 风格的每周剩余额度徽章（如 `16%`）；悬停/点击显示「每周额度 剩余 N% · 重置于 M/D HH:mm」。仅在当前会话 provider 为 `grok-build` 且用量 `ok` 时显示。Settings 中 Pull/登录成功后会派发刷新事件更新徽章。本地 0.1.13 供复测，**未发 npm**。升级后请用新 token URL 硬刷新。
+选择 Grok 模型后，模型菜单里会出现推理档位子菜单：`low` / `medium` / `high` / `xhigh`，默认 `high`。档位通过 `model.reasoning`（`efforts` + `defaultEffort`）元数据提供，因此与 Codex 在 DSH 中的交互一致；具体可用档位以账号模型目录为准。
 
-## v0.1.12
+### 模型目录与登录状态
 
-After upgrading, open the fresh token URL from `dsh web` and hard-refresh (Ctrl+Shift+R) so the old immutable `/plugins` client is not reused.
+登录后插件从订阅代理读取账号实际可用的模型目录；未登录时不注册任何模型。读取失败或超时时回退到内置列表（`grok-4.7` / `grok-4.6` / `grok-4.5`）并在状态里记录错误，因此目录不会留空，也不会让插件启动卡住。
 
-修复 0.1.11 实机：Settings → Plugins 仍卡在「Reading plugins…」，Pull 等到客户端 45s 超时。根因是 `status` / `currentToken` 仍可能无超时地 `await credentials.resolve` 与裸 `import('@deepseek-ai/dsh-credentials')`，楔住连接桥后 Plugins 清单也跟着挂。现：`credentialRefOf` 用 timed `optionalImport`；resolve 硬超时（默认 1.5s）；`status` 先内存 / auth.json，再可选 credentials；宿主 RPC 每端点 8s 硬超时；`llm/adapters-updated` 一律延后；`inject` 保持 `['llm','web']`；客户端缺 connection 软跳过，RPC 客户端超时降至 12s。本地 0.1.12 供复测，未发 npm。
+## 更新与卸载
 
-## v0.1.10
+### 更新并检查
 
-Fixes 0.1.9 live hang: Pull could still hit the 45s client timeout, and **Settings → Plugins** stuck on `Reading plugins…` (host Settings/RPC channel wedged). Root cause: `apply`/`boot` awaited untimed dynamic `import`s (`pi-ai` / `dsh-llm-pi-ai` / schemastery), and `inject` listed sticky `credentials`. Now `inject` is `['llm','web']`; `apply` synchronously registers a duck adapter and returns; schemastery / `session.pull` / pi-ai upgrade are deferred via `setImmediate`; every dynamic import has a hard timeout (default 2.5s) and falls back to duck. Keeps 0.1.9 memory-first Pull and 0.1.8 client fire-and-forget.
+```sh
+dsh plugin --profile web update dsh-grok-subscription
+dsh plugin --profile web list dsh-grok-subscription --depth 0
+dsh --profile web --dump-config
+```
 
-### v0.1.9
+### 卸载
 
-Fixes 0.1.8 live hang where the Pull RPC itself hit the client 45s timeout: zero-network Pull still awaited `storeToken` → `credentialRefOf()` (dynamic import of `@deepseek-ai/dsh-credentials`) with no timeout, so a credentials import/set deadlock stalled Pull. Session now keeps `memoryAccessToken`; success Pull writes memory and returns immediately, deferring credential persist/clear; `currentToken` / `status` prefer memory. Keeps 0.1.8 client fire-and-forget refresh behavior.
+确认需要移除插件后再运行：
 
-### v0.1.8
+```sh
+dsh plugin --profile web remove dsh-grok-subscription
+```
 
-Fixes 0.1.7 live hang: after Pull the client no longer awaits `usage/refresh` while holding global busy (Working… / all buttons disabled). Pull/login clear busy and show success immediately; catalog + usage refresh are fire-and-forget. Only the Usage Refresh button uses local `usageBusy`. `fetchBillingUsage` has a hard Promise.race timeout (default 8s) independent of AbortSignal; empty `{}` and non-JSON Content-Type get clearer unavailable reasons.
+这些操作会保留 DSH profile、其他插件和 `~/.grok/auth.json` 中的登录信息。
 
-### v0.1.7
-Fixes Settings Pull hang after 0.1.6: zero-network Pull path, `storeToken` hard timeout (default 5s), returns cached catalog/usage immediately; background kick of `refreshCatalog` + `refreshUsage`; client follows up with `catalog/refresh` and `usage/refresh`. Catalog notify stays deferred.
+<details>
+<summary>官方 npm 备用方式</summary>
 
-## v0.1.6
-Fixes Settings Pull hang (Working…) and stale Unavailable usage: Pull no longer awaits billing; `status()` returns cached usage only; client calls `usage/refresh` after successful Pull; catalog notify is deferred; client RPC has a safety timeout. Keeps 0.1.5 config.* parsing.
+```sh
+npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web update dsh-grok-subscription
+npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web remove dsh-grok-subscription
+```
 
-### v0.1.5
-Fixes experimental usage parsing: live `/v1/billing?format=credits` nests `creditUsagePercent`, `currentPeriod`, and `productUsage` under `config` (not top-level). 0.1.4 failed QA with Unavailable. Parser now accepts `config.*` and top-level; unavailable reasons include top-level key names. Never invents percentages.
+</details>
 
-### v0.1.4
-Experimental SuperGrok weekly usage in Settings: read-only `GET /v1/billing?format=credits` with the same OAuth + CLI fingerprint headers; shows used % and period end; RPC `usage` / `usage/refresh` never return tokens; fail closed to Unavailable. The billing API is undocumented and may change.
+## 常见问题
 
-### v0.1.3
-Fixes multi-turn Chat where assistant body text vanished from turn 2 onward: the custom Responses SSE mapper ended text/reasoning blocks with empty strings, so Harness `BlockAssembler` replaced streamed deltas with blanks (UI could show "Deep diving…" then no body). Also forces `include: reasoning.encrypted_content` for `grok-build` so encrypted reasoning can replay on later turns. This is unofficial, may fall into a vendor-ToS gray area, and the undocumented wire protocol can change. Use your own account only.
+- **`dsh` 无法识别**：官方 npm 方式本来就不会创建全局 `dsh` 命令，请使用上面的完整 `npx -y @deepseek-ai/dsh@0.1.5-rc.2 ...` 命令；
+- **模型列表是空的**：未登录时插件不暴露任何模型。先完成登录，再点 **从 Grok CLI 拉取**；
+- **升级后界面没变化**：插件会继续运行旧的 `lib/`，请重新安装插件并重启 `dsh web`，然后硬刷新（Ctrl+Shift+R）；
+- **提示 `auth.json` 权限不正确**：按上面的 `chmod 600` 处理；插件拒绝读取符号链接或组/其他用户可读的文件；
+- **出现「没有回复」**：请升级到 `1.0.1` 或更高版本。`1.0.0` 存在一个缺陷：工具调用轮次会因流片段无法无损序列化而整轮中止，界面上完全没有回复。
 
-## 还需要实机验证的部分
+## 边界与支持
 
-单元测试覆盖 auth.json 解析、目录解析、请求头、RPC 脱敏、signed-out 空目录与 catalog-change 回调，不访问网络。以下需要本机已安装的 DSH + 已登录 SuperGrok 才能确认：
+Grok 订阅后端和 DSH 可能独立变化；本项目为社区项目，与 DeepSeek、xAI 无隶属或背书关系。
 
-- Settings 页槽位、locale、connection.rpc 与 DSH web client 的实际装配
-- Pull 后 Chat / New Session 是否出现 `grok-4.7` 等 `grok-build` 模型并可发起推理
-- `PiAiAdapter` 对 `grok-build` 路由的流式映射（若宿主没有 `@deepseek-ai/dsh-llm-pi-ai` / `@earendil-works/pi-ai`，插件会降级到自带的 Responses SSE MVP adapter）
-- 官方 CLI `grok login` / `grok login --device-auth` 从 Settings 按钮拉起后的终端交互
-- 实时 `GET /v1/models-v2` 是否返回 `grok-4.7`（目录为空时使用静态回退）
-- Settings「用量（实验性）」：登录后刷新是否显示已用 % 与周期结束时间；401/网络失败是否显示「不可用」且无假百分比；Chat 在用量失败时仍可正常对话
+敏感问题请先阅读 [SECURITY.md](SECURITY.md)。问题反馈请使用 [Issues](https://github.com/BaronCyrus/dsh-grok-subscription/issues)。
 
-## 致谢 / Acknowledgments
+### 开发检查
 
-- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)
-- [dsh-kimi-subscription](https://github.com/BaronCyrus/dsh-kimi-subscription)（插件形态与发布方式参考）
-- [dsh-codex-subscription](https://github.com/WSL043/dsh-codex-subscription)
+```sh
+npm install
+npm test
+npm run build
+```
 
-## License
+`lib/` 是提交进仓库的构建产物，改动 `src/` 后请运行 `npm run build`。
 
 [MIT](LICENSE)

package/lib/client.js

@@ -34,7 +34,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 1.0.0",
+  subtitle: "\u7528 SuperGrok / X Premium\uFF08Grok Build\uFF09\u4F1A\u8BDD\uFF0C\u800C\u4E0D\u662F XAI_API_KEY\u3002\xB7 1.0.2",
   signedIn: "\u5DF2\u767B\u5F55",
   signedOut: "\u672A\u767B\u5F55",
   account: "\u8D26\u6237",
@@ -81,7 +81,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 1.0.0",
+  subtitle: "Use a SuperGrok / X Premium (Grok Build) session, not XAI_API_KEY. \xB7 1.0.2",
   signedIn: "Signed in",
   signedOut: "Signed out",
   account: "Account",

package/lib/index.js

@@ -788,7 +788,31 @@ function mapFinish(reason) {
   if (reason === "length" || reason === "max_tokens") return { kind: "max-tokens" };
   return { kind: "stop" };
 }
-async function* streamResponses(options, token) {
+function finiteOr(value, fallback) {
+  return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+function jsonSafeChunk(value) {
+  if (value === null) return null;
+  const type = typeof value;
+  if (type === "string" || type === "boolean") return value;
+  if (type === "number") return Number.isFinite(value) && !Object.is(value, -0) ? value : void 0;
+  if (type !== "object") return void 0;
+  if (Array.isArray(value)) {
+    const list = [];
+    for (const item of value) {
+      const safe = jsonSafeChunk(item);
+      if (safe !== void 0) list.push(safe);
+    }
+    return list;
+  }
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    const safe = jsonSafeChunk(item);
+    if (safe !== void 0) out[key] = safe;
+  }
+  return out;
+}
+async function* streamResponsesUnsafe(options, token) {
   const headers = {
     Accept: "text/event-stream",
     "Content-Type": "application/json",
@@ -839,8 +863,24 @@ async function* streamResponses(options, token) {
   let reasoningContent = "";
   let nextIndex = 0;
   const toolBlocks = /* @__PURE__ */ new Map();
+  const toolNames = /* @__PURE__ */ new Map();
   let usage;
   let finish = { kind: "stop" };
+  const toolIdOf = (payload) => {
+    const id = payload?.item_id ?? payload?.call_id ?? payload?.id;
+    return typeof id === "string" && id ? id : void 0;
+  };
+  const learnToolName = (id, name2) => {
+    if (typeof id !== "string" || !id || typeof name2 !== "string" || !name2) return;
+    toolNames.set(id, name2);
+    const tool = toolBlocks.get(id);
+    if (tool) tool.name = name2;
+  };
+  const adoptToolArguments = (id, value) => {
+    if (typeof id !== "string" || typeof value !== "string" || !value) return;
+    const tool = toolBlocks.get(id);
+    if (tool && value.length > tool.arguments.length) tool.arguments = value;
+  };
   const flushSse = function* (raw) {
     const lines = raw.split("\n");
     let event = "message";
@@ -880,12 +920,33 @@ async function* streamResponses(options, token) {
       yield { type: "reasoning-delta", index: reasoningIndex, text: String(delta) };
       return;
     }
+    if (type === "response.output_item.added" || type === "response.output_item.done") {
+      const item = payload.item;
+      if (item?.type === "function_call") {
+        learnToolName(item.id, item.name);
+        learnToolName(item.call_id, item.name);
+        adoptToolArguments(item.id, item.arguments);
+      }
+      return;
+    }
+    if (type === "response.function_call_arguments.done") {
+      const id = toolIdOf(payload);
+      learnToolName(id, payload.name);
+      adoptToolArguments(id, payload.arguments);
+      return;
+    }
     if (type === "response.function_call_arguments.delta") {
-      const id = payload.item_id ?? payload.call_id ?? payload.id;
+      const id = toolIdOf(payload);
       if (!id) return;
       let tool = toolBlocks.get(id);
       if (!tool) {
-        tool = { index: nextIndex++, id, name: payload.name ?? payload.item?.name, arguments: "" };
+        tool = {
+          index: nextIndex++,
+          id,
+          // Never leave this undefined: an unserializable chunk aborts the turn.
+          name: toolNames.get(id) ?? "tool",
+          arguments: ""
+        };
         toolBlocks.set(id, tool);
         yield { type: "block-start", index: tool.index, blockType: "tool-call" };
       }
@@ -895,20 +956,38 @@ async function* streamResponses(options, token) {
       return;
     }
     if (type === "response.completed") {
+      for (const item of payload.response?.output ?? []) {
+        if (item?.type !== "function_call") continue;
+        learnToolName(item.id, item.name);
+        learnToolName(item.call_id, item.name);
+        const id = typeof item.id === "string" && item.id ? item.id : void 0;
+        if (id && !toolBlocks.has(id)) {
+          const tool = { index: nextIndex++, id, name: toolNames.get(id) ?? "tool", arguments: "" };
+          toolBlocks.set(id, tool);
+          yield { type: "block-start", index: tool.index, blockType: "tool-call" };
+        }
+        adoptToolArguments(id, item.arguments);
+      }
       const responseUsage = payload.response?.usage ?? payload.usage;
       if (responseUsage) {
         usage = {
-          inputTokens: responseUsage.input_tokens ?? responseUsage.prompt_tokens ?? 0,
-          outputTokens: responseUsage.output_tokens ?? responseUsage.completion_tokens ?? 0,
-          totalTokens: responseUsage.total_tokens
+          inputTokens: finiteOr(responseUsage.input_tokens ?? responseUsage.prompt_tokens, 0),
+          outputTokens: finiteOr(responseUsage.output_tokens ?? responseUsage.completion_tokens, 0)
         };
+        usage.totalTokens = finiteOr(responseUsage.total_tokens, usage.inputTokens + usage.outputTokens);
       }
       finish = mapFinish(payload.response?.status === "incomplete" ? "length" : "stop");
       if (toolBlocks.size) finish = { kind: "tool-calls" };
     }
     if (type === "response.failed" || type === "error") {
-      const message = payload.error?.message ?? payload.message ?? "Grok Build stream failed";
-      finish = { kind: "error", failure: { message, code: "PROVIDER", status: payload.error?.status } };
+      const raw2 = payload.error?.message ?? payload.message;
+      const failure = {
+        message: typeof raw2 === "string" && raw2 ? raw2 : "Grok Build stream failed",
+        code: "PROVIDER"
+      };
+      const status = finiteOr(payload.error?.status, void 0);
+      if (status !== void 0) failure.status = status;
+      finish = { kind: "error", failure };
     }
   };
   for await (const chunk of response.body) {
@@ -937,6 +1016,12 @@ async function* streamResponses(options, token) {
   if (usage) yield { type: "usage", usage };
   yield { type: "finish", reason: finish };
 }
+async function* streamResponses(options, token) {
+  for await (const chunk of streamResponsesUnsafe(options, token)) {
+    const safe = jsonSafeChunk(chunk);
+    if (safe) yield safe;
+  }
+}
 function visiblePiModels(session) {
   if (session.publicAccount()?.signedIn !== true) return [];
   return toPiModels(session.models()).map((model) => model.provider === PROVIDER_ID ? model : { ...model, provider: PROVIDER_ID });
@@ -992,17 +1077,13 @@ function createDuckAdapter(session) {
         yield* streamResponses(options, token);
       } catch (error) {
         const aborted = options.signal?.aborted === true;
-        yield {
-          type: "finish",
-          reason: {
-            kind: aborted ? "aborted" : "error",
-            failure: {
-              message: error instanceof Error ? error.message : "Grok Build request failed",
-              code: aborted ? "ABORTED" : "PROVIDER",
-              status: error?.status
-            }
-          }
+        const failure = {
+          message: error instanceof Error ? error.message : "Grok Build request failed",
+          code: aborted ? "ABORTED" : "PROVIDER"
         };
+        const status = finiteOr(error?.status, void 0);
+        if (status !== void 0) failure.status = status;
+        yield { type: "finish", reason: { kind: aborted ? "aborted" : "error", failure } };
       }
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-grok-subscription",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Use a SuperGrok or X Premium Grok Build subscription in DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
@@ -12,8 +12,11 @@
   },
   "files": [
     "lib",
+    "docs/assets",
     "cordis.patch.yml",
     "README.md",
+    "README.en.md",
+    "CONTRIBUTING.md",
     "SECURITY.md",
     "LICENSE"
   ],