dsh-grok-subscription 1.2.0 → 2.0.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 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.
+- Why this is safe to drop: every DSH installation carries the adapter. `@deepseek-ai/dsh` depends on `dsh-base`, `dsh-base` depends on `@deepseek-ai/dsh-llm-pi-ai`, that package depends on `@earendil-works/pi-ai`, and `dsh-base`'s bundle patch mounts the `llm-pi-ai` row unconditionally (no `disabled:` gate). Checked on the npm registry for `dsh-base` 0.1.5-rc.2, 0.1.7-rc.2 and 0.2.0-rc.1, so the whole declared peer span ships it.
+- What happens instead when it is missing: nothing is registered and Settings' **Active path** reads **unavailable** (new copy in both locales). No substitute adapter is invented — a half-working replacement would hide the real problem behind subtler symptoms, which is exactly how the `DUPLICATE_ADAPTER` defect survived seven releases.
+- Behaviour deltas, stated plainly:
+  - **A rejected token is no longer renewed mid-stream and retried.** That retry lived in the bundled adapter; renewal is now proactive (through the official CLI, shortly before the recorded expiry). A session the server has already revoked surfaces as an authentication error until you sign in again. The session service keeps `refreshToken()` — tested, and the natural seam if a host-side hook is added later.
+  - **Settings reports three states instead of two**: `starting` while the deferred registration is pending, `official pi-ai` once it lands, `unavailable` when the host's packages cannot be resolved. The old `bundled fallback` state cannot occur.
+  - Request construction is unchanged: the pinned `grok:<sessionId>` `prompt_cache_key` and the forced `reasoning.encrypted_content` include still go through `withGrokRequestSemantics`, and the host still owns the image pipeline. Cache behaviour, quota, sign-in, catalog and the RPC surface are untouched.
+- Docs are now desktop-only, as asked: the READMEs and both guides lead with **Settings → Plugins** (type the package name, then restart the app), and the `--profile web`, `npx` and Headless instructions are gone. The guides explain the pi-ai dependency and keep a terminal fallback for the desktop profile.
+- Tests: 153 pass. Removed the files that only exercised the deleted adapter (`stream-history`, `stream-toolcall`, `usage-cache`, `image-input`) and the five duck-driven 401 tests in `session-renewal`; kept every assertion that still describes shipped behaviour (`visiblePiModels`, the cache-key format, session-level renewal). Added `tests/adapter-registration.test.mjs`: one registration per apply, nothing registered on an unavailable host, and a refused registration reported rather than left as a dead route.
+- Verified live on the real 0.2.0-rc.1 desktop runtime against the live subscription: the route serves `PiAiAdapter`, diagnostics read `pi-ai` with `hostPeersResolved: true`, a three-turn conversation through the host's durable message shape answered `stored` → `42` → `84` with replay state on every turn, a tool turn returned `finish: tool-calls` with `get_weather {"city":"Paris"}`, and a `purpose: 'compaction'` turn completed normally.
+
 ## 1.2.0 — 2026-09-28
 
 - Fix **the host's official pi-ai adapter never serving the route**. `ctx.llm.registerAdapter` refuses a second adapter for a provider that already has one (`DUPLICATE_ADAPTER`, all-or-nothing) in every Host this plugin supports, while the plugin registered its bundled adapter synchronously and then re-registered the same `grok-build` route from the deferred upgrade. That throw landed in the upgrade's `catch` and was logged at warn level, so **every release since 0.1.10 — the one that introduced the bundled-then-upgrade design — ran the bundled adapter** while Settings reported `Active path: bundled fallback`. The upgrade now releases the bundled registration and claims the route again in one synchronous step, and restores the bundled adapter if the Host refuses the replacement, so the route is never left unserved. This defect predates 1.1.3 and is unrelated to the 0.2.0 compatibility gate that release fixed. Reported in 1.1.3's release notes and fixed here.

package/README.en.md

@@ -46,11 +46,7 @@ For DSH setup, see the [official instructions](https://github.com/deepseek-ai/de
 
 ### 1. Install the plugin
 
-```sh
-dsh plugin --profile web add dsh-grok-subscription@latest
-```
-
-Then **manually restart the target DSH instance**. Refreshing the browser alone does not reload the Host adapter.
+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.
 
 ### 2. Sign in
 
@@ -63,19 +59,18 @@ Open **Settings → Grok Subscription** and select **CLI login** or **Device-cod
 Pick a Grok model your account can use, adjust reasoning effort as needed, and start chatting or coding. The badge beside the model shows weekly quota when usage can be read successfully.
 
 <details>
-<summary>Verify the install / use npx / pin a version</summary>
+<summary>Check the version / pin one / fall back when the UI install fails</summary>
 
-```sh
-dsh plugin --profile web list dsh-grok-subscription --depth 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.0`.
 
-Without a global `dsh` command, retain your full `npx` launcher prefix. This example uses the baseline version declared in the package metadata:
+If the UI install fails (an unusual profile directory, say), the equivalent runs against the desktop profile itself (pnpm ≥ 11):
 
 ```sh
-npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web add dsh-grok-subscription@latest
+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
 ```
 
-See the [full user guide](docs/guide.en.md) for pinned npm versions, GitHub-source installs, CLI paths, and Headless usage.
+`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).
 
 </details>
 
@@ -116,27 +111,17 @@ Identity and time values in the account screenshot are demo data. Usage screensh
 
 ## User guide
 
-The [full user guide](docs/guide.en.md) covers CLI sign-in, the model catalog, images, quota limitations, network troubleshooting, Headless usage, and development.
+The [full user guide](docs/guide.en.md) covers installation and compatibility, CLI sign-in, the model catalog, images, quota limitations, network troubleshooting, and development.
 
 Quick links: [Sign-in and credentials](docs/guide.en.md#sign-in-and-credentials) · [Image input](docs/guide.en.md#image-input) · [Troubleshooting](docs/guide.en.md#troubleshooting) · [Contributing](CONTRIBUTING.md).
 
 ## Update and uninstall
 
-**Update an npm installation:** check versions in Settings. Supported npm installs can update there, or you can run:
-
-```sh
-dsh plugin --profile web add dsh-grok-subscription@latest
-```
-
-For a GitHub-source install, use `dsh plugin --profile web update dsh-grok-subscription`. For a local `link:` install, pull and rebuild the checkout instead of replacing its development link.
+**Update:** put `dsh-grok-subscription` (or `dsh-grok-subscription@version`) into the **Settings → Plugins** install field again to install over the current copy; the plugin's own page also has a version card and an **Update plugin** button. Then **quit and restart the desktop app completely**.
 
 The desktop app owns its `desktop` profile exclusively, so `dsh plugin --profile desktop …` is refused there. The desktop **Update plugin** button therefore installs the exact version inside that profile directory with DSH's own bundled pnpm; before `1.1.1` that button always failed in the desktop app. Manual steps: [Updates and sign-out](docs/guide.en.md#updates-and-sign-out).
 
-**Uninstall:**
-
-```sh
-dsh plugin --profile web remove dsh-grok-subscription
-```
+**Uninstall:** remove `dsh-grok-subscription` in **Settings → Plugins**, or run `pnpm remove dsh-grok-subscription` in that profile directory, then restart the desktop app. Uninstalling leaves other plugins, the profile, and the CLI's `auth.json` intact, and is not the same as signing out of the official CLI; see [Updates and sign-out](docs/guide.en.md#updates-and-sign-out).
 
 Restart DSH afterwards. Removal does not delete other plugins, the whole profile, or the CLI's `auth.json`; it is not the same as signing out of the official CLI. See [Updates and sign-out](docs/guide.en.md#updates-and-sign-out).
 
@@ -148,7 +133,7 @@ Restart DSH afterwards. Removal does not delete other plugins, the whole profile
 
 **Sign-in or requests time out?** Check connectivity from the DSH host to account and subscription services, including its launch-time proxy settings. Network issues, authentication, or service errors can cause failures; do not assume the quota is exhausted. See [Troubleshooting](docs/guide.en.md#troubleshooting).
 
-**Images still unavailable after updating?** Fully restart DSH, check the model's image support, and check the attachment capability shown under **Active path** in Settings.
+**Images still unavailable after updating?** Fully restart the desktop app, check the model's image support, and check that **Active path** in Settings reads **official pi-ai** with attachment capability available. An **unavailable** row means the host has no pi-ai adapter.
 
 ## Scope and support
 

package/README.md

@@ -46,11 +46,7 @@
 
 ### 1. 安装插件
 
-```sh
-dsh plugin --profile web add dsh-grok-subscription@latest
-```
-
-完成后，**手动重启正在运行的目标 DSH**。仅刷新浏览器不会重新加载 Host 中的适配器。
+在桌面版打开 **设置 → 插件**，在安装输入框里填入包名 `dsh-grok-subscription` 并安装，然后**完全退出并重启桌面应用**。仅刷新页面不会重新加载 Host 中的适配器。
 
 ### 2. 登录订阅
 
@@ -63,19 +59,18 @@ dsh plugin --profile web add dsh-grok-subscription@latest
 在模型选择器中选择账号可用的 Grok 模型。按需要调整推理档位，开始对话或编程；模型旁的徽章显示成功读取到的每周余量。
 
 <details>
-<summary>检查安装 / 使用 npx / 安装指定版本</summary>
+<summary>确认版本 / 固定版本 / 界面安装失败时的兜底</summary>
 
-```sh
-dsh plugin --profile web list dsh-grok-subscription --depth 0
-```
+**设置 → 插件** 会列出已安装插件与版本，插件自己的 **设置 → Grok 订阅** 页也有版本卡片。要固定版本，在安装框里填入完整的 `包名@版本`，例如 `dsh-grok-subscription@2.0.0`。
 
-没有全局 `dsh` 命令时，保留你使用的完整 `npx` 前缀。以下使用项目元数据声明的基线版本作为示例：
+界面安装失败时（例如 profile 目录权限异常），可以对桌面版 profile 手动执行等价操作（pnpm ≥ 11）：
 
 ```sh
-npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web add dsh-grok-subscription@latest
+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
 ```
 
-固定 npm 版本、GitHub 来源安装、CLI 路径与 Headless 使用见 [完整使用指南](docs/guide.zh-CN.md)。
+`dsh plugin --profile desktop …` 会被拒绝：桌面版 profile 由 Electron 应用独占。CLI 路径、登录方式与故障排查见 [完整使用指南](docs/guide.zh-CN.md)。
 
 </details>
 
@@ -116,29 +111,17 @@ npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web add dsh-grok-subscriptio
 
 ## 使用指南
 
-[完整使用指南](docs/guide.zh-CN.md) 包含 CLI 登录、模型目录、图片输入、额度限制、网络排查、Headless 使用和本地开发。
+[完整使用指南](docs/guide.zh-CN.md) 包含安装与兼容性、CLI 登录、模型目录、图片输入、额度限制、网络排查和本地开发。
 
 常用入口：[登录与凭据](docs/guide.zh-CN.md#登录与凭据) · [图片输入](docs/guide.zh-CN.md#图片输入) · [故障排查](docs/guide.zh-CN.md#故障排查) · [参与贡献](CONTRIBUTING.md)。
 
 ## 更新与卸载
 
-**更新 npm 安装：** 可在设置页检查版本；支持的 npm 安装可一键更新，也可以运行：
+**更新：** 在 **设置 → 插件** 的安装框里重新填入 `dsh-grok-subscription`（或 `dsh-grok-subscription@版本`）安装即可覆盖；插件自己的设置页也有版本卡片与「更新插件」按钮。完成后**完全退出并重启桌面应用**。
 
-```sh
-dsh plugin --profile web add dsh-grok-subscription@latest
-```
-
-GitHub 来源安装可使用 `dsh plugin --profile web update dsh-grok-subscription`；本地 `link:` 安装应拉取对应仓库并重新构建，不要替换开发链接。
-
-桌面版由 Electron 应用独占 `desktop` profile，`dsh plugin --profile desktop …` 会被拒绝，因此桌面版的「更新插件」由插件自己在该 profile 目录中用 DSH 自带的 pnpm 安装精确版本；`1.1.1` 之前该按钮在桌面版必然失败，手动步骤见[更新与登出](docs/guide.zh-CN.md#更新与登出)。
-
-**卸载：**
-
-```sh
-dsh plugin --profile web remove dsh-grok-subscription
-```
+桌面版由 Electron 应用独占 `desktop` profile，`dsh plugin --profile desktop …` 会被直接拒绝，因此桌面版的「更新插件」由插件在该 profile 目录中用 DSH 自带的 pnpm 安装精确版本；`1.1.1` 之前该按钮在桌面版必然失败，手动步骤见[更新与登出](docs/guide.zh-CN.md#更新与登出)。
 
-完成后手动重启 DSH。卸载不会删除其他插件、整个 profile 或 Grok CLI 的 `auth.json`，也不等于从官方 CLI 登出；清理范围见 [更新与登出](docs/guide.zh-CN.md#更新与登出)。
+**卸载：** 在 **设置 → 插件** 里移除 `dsh-grok-subscription`，或在该 profile 目录执行 `pnpm remove dsh-grok-subscription`，然后重启桌面应用。卸载不会删除其他插件、整个 profile 或 Grok CLI 的 `auth.json`，也不等于从官方 CLI 登出；清理范围见 [更新与登出](docs/guide.zh-CN.md#更新与登出)。
 
 ## 常见问题
 
@@ -146,7 +129,7 @@ dsh plugin --profile web remove dsh-grok-subscription
 
 **登录或请求超时？** 检查 DSH 所在机器能否连接账号与订阅服务，以及启动环境的代理设置。网络、登录状态和服务端异常都可能导致失败，不要直接认定为额度耗尽。见 [故障排查](docs/guide.zh-CN.md#故障排查)。
 
-**更新后不能带图？** 完整重启 DSH，检查模型是否在图片支持列表，以及设置页的「运行通路」是否显示附件能力可用。
+**更新后不能带图？** 完整重启桌面应用，检查模型是否在图片支持列表，以及设置页的「运行通路」是否显示**官方 pi-ai** 且附件能力可用。若显示「不可用」，说明宿主缺少 pi-ai 适配器。
 
 ## 边界与支持
 

package/docs/guide.en.md

@@ -6,37 +6,20 @@ For quick setup, see the [README](../README.en.md#install). This guide covers de
 
 ## Installation and compatibility
 
-You need DeepSeek Harness, 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.
+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 from npm:**
+**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`.
 
-```sh
-dsh plugin --profile web add dsh-grok-subscription@latest
-dsh plugin --profile web list dsh-grok-subscription --depth 0
-```
-
-For reproducibility, pin a published version, for example:
-
-```sh
-dsh plugin --profile web add dsh-grok-subscription@1.2.0
-```
+**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**.
 
-**Install from GitHub:**
+If the UI install fails (an unusual profile directory, say), the equivalent runs against the desktop profile itself (pnpm ≥ 11):
 
 ```sh
-dsh plugin --profile web add BaronCyrus/dsh-grok-subscription
-```
-
-The GitHub branch and published npm package may differ. Choose an installation source deliberately; a source commit does not mean a new npm version has been published.
-
-If you launch DSH with `npx` and have no global `dsh` command, retain the full prefix for plugin operations. This example uses the baseline declared in the package:
-
-```sh
-npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web add dsh-grok-subscription@latest
-npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web list dsh-grok-subscription --depth 0
+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
 ```
 
-Restart the target DSH instance after installation. For local diagnosis, `dsh --profile web --dump-config` should show one `grok-build` route. Redact sensitive settings and personal paths before sharing diagnostics; do not post the full configuration.
+`dsh plugin --profile desktop …` is refused: the Electron application owns that profile exclusively.
 
 ## Sign-in and credentials
 
@@ -64,7 +47,7 @@ After sign-in, the plugin prefers the catalog from `/v1/models-v2`; while signed
 
 Reasoning options follow model metadata. The implementation recognizes `low` / `medium` / `high` / `xhigh`, usually defaulting to `high`; the built-in `grok-4.5` entry has only the first three. Follow the actual menu and backend-supported choices. See [catalog.js](../src/catalog.js).
 
-Login, pull, logout, and catalog refresh notify the model picker. Near a known token expiry, or after an authentication rejection, the plugin attempts renewal through the official CLI. If renewal fails, authorization may still be required again; uninterrupted sessions are not guaranteed.
+Login, pull, logout, and catalog refresh notify the model picker. Near a known token expiry the plugin renews through the official CLI. If renewal fails, or the server has already revoked the session, authorization may still be required again; uninterrupted sessions are not guaranteed.
 
 ## Image input
 
@@ -80,7 +63,7 @@ These exact IDs come from `IMAGE_INPUT_MODEL_IDS` in [constants.js](../src/const
 
 Paste or attach an image in the composer. DSH's attachment service processes it within pixel and byte budgets; over-budget images may degrade to a text description. Do not assume every image is sent at its original resolution.
 
-From 1.2.0 the plugin runs the host's official pi-ai adapter, which owns the image pipeline (attachment resolution plus pixel and byte budgets). The bundled adapter stays as the automatic fallback: it is what serves the route if the pi-ai packages are missing, or if the Host refuses the hand-over. The **Active path** row in Settings names the adapter actually serving the route, and whether image input is available. After an update, a refreshed browser can still be using an old adapter if the Host was not restarted. To pin the bundled adapter deliberately — for instance if a Host adapter misbehaves on your account — set `DSH_GROK_ADAPTER=fallback` in `~/.dsh/.env` and restart DSH.
+The `grok-build` route is served by the host's official pi-ai adapter, which also owns the image pipeline (attachment resolution plus pixel and byte budgets). The **Active path** row in Settings names the adapter serving the route and whether image input is available; **unavailable** means the host has no pi-ai adapter. After an update, a refreshed browser can still be running the old version if the Host was not restarted.
 
 ## Quota and caching
 
@@ -88,28 +71,10 @@ Usage is read through the undocumented `/v1/billing?format=credits` endpoint and
 
 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.
 
-For prefix caching, the plugin pins one stable `prompt_cache_key` per DSH session on **both** adapter paths — the bundled adapter builds it, and on the host's pi-ai path the plugin assigns the same `grok:<sessionId>` value into the 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).
-
-## Headless usage
-
-First complete subscription sign-in through the Grok CLI on the same host and verify Web usage. Then install the plugin into the target Headless profile:
-
-```sh
-dsh plugin --profile headless add dsh-grok-subscription@latest
-```
-
-Confirm that this profile's model configuration selects a `grok-build` model the account can use, then run a one-shot interactive task:
-
-```sh
-dsh --profile headless "reply with exactly: ok"
-```
-
-That task makes a real model request and uses the selected service's quota; it is not an offline check. Selecting a model in Web is not proof that another profile is configured correctly.
+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).
 
 ## Troubleshooting
 
-**`dsh` not found.** Use the full `npx` prefix you use to launch DSH, or check the installed launcher's path.
-
 **`grok` not found or no login window.** Check that the CLI is installed on the DSH Host and its process sees `DSH_GROK_BIN` / `PATH`. Look for a clickable login link in the panel. A browser failing to open does not by itself prove the authorization service is unreachable. On Windows, if the CLI is not on `PATH`, put the absolute `grok.exe` path in the user-level `DSH_GROK_BIN` (for example `setx DSH_GROK_BIN "C:\Users\<user>\.grok\bin\grok.exe"`) and restart DSH completely; note that `DSH_*` is a DSH bootstrap prefix, so declaring it in `~/.dsh/.env` makes that environment layer fail.
 
 **`fetch failed` or `Billing request timed out`.** Check access to the account service and `cli-chat-proxy.grok.com` separately. When a proxy is needed, set standard `https_proxy` / `http_proxy` variables in DSH's launch environment or `~/.dsh/.env`, not the project directory's `.env`, then manually restart DSH. The plugin uses the host network setup rather than providing its own proxy service. Network conditions are one possibility; also check authentication and backend errors.
@@ -118,28 +83,30 @@ That task makes a real model request and uses the selected service's quota; it i
 
 **Chat or usage returns `401`.** Check the CLI session. If automatic renewal fails, run `grok login` again, authorize, and pull the session. Do not repeatedly paste an old token.
 
-**Images rejected.** Check the supported IDs and attachment capability under **Active path**. Fully restart the Host after updating, then refresh the browser.
+**Images rejected.** Check the supported IDs, confirm **Active path** reads **official pi-ai** with attachment capability available, and fully restart the desktop app after updating.
 
 **Auth-file permission error.** Check the actual path, owner, symlink status, and permissions. `chmod 600` fixes permission bits only.
 
 **No response on an old release.** Version `1.0.0` had a tool-call serialization defect fixed in `1.0.1`; older versions may also lack later renewal fixes. Update to the current published version before diagnosing a persistent problem rather than attributing every missing response to that old defect.
 
-**The plugin vanished from Settings after a DSH update.** From 0.2.0 DSH refuses a plugin whose `@deepseek-ai/dsh*` peer ranges do not admit the running version, and it drops the whole bundle before any plugin code loads: no `grok-build` route, no Settings section, and nothing in the panel to explain it. The Host writes `skipping profile bundle "dsh-grok-subscription"` to its own stderr, and `dsh --profile web --dump-config` omits the `grok-subscription` row. Update the plugin rather than granting a version exemption: an exemption re-enables a build that was never checked against that Host.
+**The plugin vanished from Settings after a DSH update.** From 0.2.0 DSH refuses a plugin whose `@deepseek-ai/dsh*` peer ranges do not admit the running version, and it drops the whole bundle before any plugin code loads: no `grok-build` route, no Settings section, and nothing in the panel to explain it. The Host writes `skipping profile bundle "dsh-grok-subscription"` to its own stderr (the desktop app refuses `dsh --profile desktop --dump-config`, so that line is the evidence to look for). Update the plugin rather than granting a version exemption: an exemption re-enables a build that was never checked against that Host.
+
+**Active path reads "unavailable".** The host has no pi-ai adapter: `@earendil-works/pi-ai` or `@deepseek-ai/dsh-llm-pi-ai` cannot be resolved from the DSH installation. Check that the installation is complete, that `node_modules` was not pruned by hand, and restart the desktop app completely.
 
 ## Updates and sign-out
 
-For npm installs, update in Settings or run `dsh plugin --profile web add dsh-grok-subscription@latest`. For GitHub-source installs, run `dsh plugin --profile web update dsh-grok-subscription`. For local links, pull, test, and rebuild the checkout. Restart DSH afterwards.
+**Update:** put `dsh-grok-subscription` (or `dsh-grok-subscription@version`) into the **Settings → Plugins** install field again to install over the current copy; the plugin's own page also has a version card and an **Update plugin** button. Then **quit and restart the desktop app completely**.
 
 In the desktop app the `desktop` profile is owned exclusively by the Electron application, and `dsh plugin --profile desktop …` is refused outright (`profile "desktop" is managed exclusively by the Electron application`), so the desktop app can only be updated by the plugin itself. From 1.1.1 the **Update plugin** button installs the exact version inside that profile directory with DSH's own bundled pnpm. If you are still on an older version and the button reports an error, run the equivalent by hand (pnpm ≥ 11):
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact dsh-grok-subscription@1.2.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
 ```
 
 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.
 
-Uninstall with `dsh plugin --profile web remove dsh-grok-subscription`. This leaves the profile, other plugins, and the CLI's `auth.json` intact.
+**Uninstall:** remove `dsh-grok-subscription` in **Settings → Plugins**, or run `pnpm remove dsh-grok-subscription` in that profile directory. This leaves the profile, other plugins, and the CLI's `auth.json` intact.
 
 The Settings logout action clears plugin-side session state; it does not revoke the official CLI session. If the CLI file remains, a later pull or startup may sync it again. To end the official session, use the official CLI / account's sign-out and authorization-management flow. Do not delete an entire DSH profile to handle one account.
 

package/docs/guide.zh-CN.md

@@ -6,37 +6,20 @@
 
 ## 安装与兼容性
 
-需要 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 全线。声明范围不等于所有版本都已经过实机验证。
+需要 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 全线。声明范围不等于所有版本都已经过实机验证。
 
-**npm 安装：**
+**安装：** 在桌面版打开 **设置 → 插件**，在安装输入框里填入包名 `dsh-grok-subscription` 并安装，然后**完全退出并重启桌面应用**。仅刷新页面不会重新加载 Host 中的适配器。需要可重复安装时，填入完整的 `包名@版本`，例如 `dsh-grok-subscription@2.0.0`。
 
-```sh
-dsh plugin --profile web add dsh-grok-subscription@latest
-dsh plugin --profile web list dsh-grok-subscription --depth 0
-```
-
-需要可重复安装时，固定已发布版本，例如：
-
-```sh
-dsh plugin --profile web add dsh-grok-subscription@1.2.0
-```
+**插件依赖宿主自带的 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 安装目录解析时，插件不会注册任何路由，设置页的「运行通路」显示**不可用**。
 
-**GitHub 来源安装：**
+界面安装失败时（例如 profile 目录权限异常），可以对桌面版 profile 手动执行等价操作（pnpm ≥ 11）：
 
 ```sh
-dsh plugin --profile web add BaronCyrus/dsh-grok-subscription
-```
-
-GitHub 分支与 npm 发布版本可能不同；请明确选择安装来源，不要把某个源码提交当作已经发布的 npm 版本。
-
-如果 DSH 通过 `npx` 运行、没有全局 `dsh` 命令，插件操作也需要完整前缀。下面以包声明的基线版本为例：
-
-```sh
-npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web add dsh-grok-subscription@latest
-npx -y @deepseek-ai/dsh@0.1.5-rc.2 plugin --profile web list dsh-grok-subscription --depth 0
+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
 ```
 
-安装后手动重启目标 DSH。需要进一步检查时，在本机运行 `dsh --profile web --dump-config`，确认只有一个 `grok-build` 路由；分享诊断前先隐藏敏感配置与个人路径，不要公开整份配置。
+`dsh plugin --profile desktop …` 会被直接拒绝：桌面版 profile 由 Electron 应用独占。
 
 ## 登录与凭据
 
@@ -64,7 +47,7 @@ chmod 600 "${GROK_HOME:-$HOME/.grok}/auth.json"
 
 推理档位按模型元数据提供。当前实现识别 `low` / `medium` / `high` / `xhigh`，通常默认 `high`；内置 `grok-4.5` 目录只包含前三档。以实际菜单与服务端接受的选项为准。实现见 [catalog.js](../src/catalog.js)。
 
-登录、拉取、登出和目录刷新会通知模型选择器更新。临近已知的 token 到期时间或遇到认证拒绝时，插件会尝试通过官方 CLI 续期；若失败，仍可能需要重新授权，不承诺会话永不失效。
+登录、拉取、登出和目录刷新会通知模型选择器更新。临近已知的 token 到期时间时，插件会通过官方 CLI 续期；若续期失败或服务端已撤销会话，仍需要重新授权，不承诺会话永不失效。
 
 ## 图片输入
 
@@ -80,7 +63,7 @@ grok-4.6
 
 在输入框粘贴或附加图片后，DSH 的附件服务会按像素与体积预算处理。图片超出可用预算时可能降级为文本说明；不要假设每张原图都以原始分辨率发出。
 
-1.2.0 起，插件默认运行宿主官方的 pi-ai 适配器，图片通路（附件解析与像素、体积预算）由它负责。内置适配器保留为自动回退：pi-ai 相关包缺失、或宿主拒绝交接时，仍由它服务该路由。设置页的 **运行通路** 会显示实际在服务的适配器和图片输入是否可用。更新后只有界面刷新、Host 未重启时，可能仍运行旧适配器。若要主动固定在内置适配器（例如宿主适配器在你的账号上表现异常），在 `~/.dsh/.env` 里设置 `DSH_GROK_ADAPTER=fallback` 并重启 DSH。
+`grok-build` 路由由宿主官方的 pi-ai 适配器服务，图片通路（附件解析、像素与体积预算）也由它负责。设置页的 **运行通路** 会显示适配器是否在服务，以及图片输入是否可用；显示**不可用**时说明宿主缺少 pi-ai 适配器。更新后只有界面刷新、Host 未重启时，可能仍在运行旧版本。
 
 ## 额度与缓存
 
@@ -88,28 +71,10 @@ grok-4.6
 
 输入框徽章仅在当前 provider 为 `grok-build` 且用量读取成功时显示，悬停或点击查看每周余量与重置时间。缺失数据不是额度为零；读取失败不会编造百分比，也不会因为单独的额度读取故障阻止聊天。
 
-前缀缓存方面，插件在**两条通路**上都为同一 DSH 会话固定同一个 `prompt_cache_key`：内置适配器自行构造，宿主 pi-ai 通路上插件把同样的 `grok:<sessionId>` 注入请求；工具顺序保持稳定。压缩、会话标题这类辅助请求与会话共用同一个 key，而不是另开一个——对代理实测下来，隔离它们并不会提高聊天前缀的缓存命中。这些是请求构造措施，不保证服务端缓存命中或节省额度；项目不提供虚构的命中率。实现见 [adapter.js](../src/adapter.js)。
-
-## Headless 使用
-
-先在同一主机上完成 Grok CLI 订阅登录，并验证 Web 中可正常使用。然后把插件安装到目标 Headless profile：
-
-```sh
-dsh plugin --profile headless add dsh-grok-subscription@latest
-```
-
-确认该 profile 的模型配置确实选择了 `grok-build` 下你有权使用的模型，再执行一次性交互任务：
-
-```sh
-dsh --profile headless "只回复：ok"
-```
-
-这条任务命令会发起真实模型调用并使用所选服务的额度；它不是离线检查。Web 中选择模型，不应被当作另一个 profile 已正确配置的证明。
+前缀缓存方面，插件为同一 DSH 会话固定同一个 `prompt_cache_key`（`grok:<sessionId>`），并在请求里显式写入，工具顺序保持稳定。压缩、会话标题这类辅助请求与会话共用同一个 key，而不是另开一个——对代理实测下来，隔离它们并不会提高聊天前缀的缓存命中。这些是请求构造措施，不保证服务端缓存命中或节省额度；项目不提供虚构的命中率。实现见 [adapter.js](../src/adapter.js)。
 
 ## 故障排查
 
-**找不到 `dsh`。** 使用你运行 DSH 时的完整 `npx` 前缀，或检查已安装启动器的命令路径。
-
 **找不到 `grok` / 不弹出登录窗口。** 检查 CLI 是否安装在 DSH Host、`DSH_GROK_BIN` / `PATH` 是否对该进程可见，以及面板是否已显示可点击授权链接。浏览器没有弹出，不一定等于授权服务不可达。Windows 上若 CLI 不在 `PATH` 中，可把 `grok.exe` 的绝对路径写入用户级 `DSH_GROK_BIN`（例如 `setx DSH_GROK_BIN "C:\Users\<用户>\.grok\bin\grok.exe"`），再完全重启 DSH；注意 `DSH_*` 是 DSH 的 bootstrap 前缀，写进 `~/.dsh/.env` 会让该环境层直接报错。
 
 **`fetch failed` / `Billing request timed out`。** 分别检查账号服务和 `cli-chat-proxy.grok.com` 的网络连接。需要代理时，在 DSH 启动环境或 `~/.dsh/.env` 中设置标准 `https_proxy` / `http_proxy`，而不是放进项目目录的 `.env`；再手动重启 DSH。插件沿用宿主网络配置，不提供单独代理服务。网络只是可能原因，还应检查认证和服务端错误。
@@ -118,28 +83,30 @@ dsh --profile headless "只回复：ok"
 
 **聊天或用量返回 `401`。** 检查 CLI 会话是否有效。自动续期失败时，重新运行 `grok login`，完成授权后再次拉取。不要反复粘贴旧 token。
 
-**图片被拒绝。** 对照图片支持列表，检查「运行通路」的附件能力，并在更新后完整重启 Host，再刷新网页。
+**图片被拒绝。** 对照图片支持列表，确认设置页「运行通路」显示**官方 pi-ai** 且附件能力可用，并在更新后完整重启桌面应用。
 
 **文件权限错误。** 检查 auth 文件的真实路径、所有者、是否为符号链接以及权限；`chmod 600` 仅解决权限位问题。
 
 **旧版本发消息无回复。** `1.0.0` 存在已在 `1.0.1` 修正的工具调用序列化问题；旧版本也可能缺少后续续期修复。先更新到当前发布版，再定位仍然存在的问题，不要把所有无回复都归因于旧缺陷。
 
-**DSH 更新后插件从设置页消失。** 0.2.0 起，插件的 `@deepseek-ai/dsh*` peer 范围若不包含当前运行版本，DSH 会在加载任何插件代码之前丢掉整个 bundle：既没有 `grok-build` 路由，也没有设置分区，界面里没有任何提示。Host 自己的 stderr 会输出 `skipping profile bundle "dsh-grok-subscription"`，`dsh --profile web --dump-config` 里也不会出现 `grok-subscription` 行。此时应更新插件，而不是授予版本豁免——豁免会重新启用一个从未针对该 Host 验证过的构建。
+**DSH 更新后插件从设置页消失。** 0.2.0 起，插件的 `@deepseek-ai/dsh*` peer 范围若不包含当前运行版本，DSH 会在加载任何插件代码之前丢掉整个 bundle：既没有 `grok-build` 路由，也没有设置分区，界面里没有任何提示。Host 自己的 stderr 会输出 `skipping profile bundle "dsh-grok-subscription"`（桌面版不允许通过 `dsh --profile desktop --dump-config` 检查，以这行日志为准）。此时应更新插件，而不是授予版本豁免——豁免会重新启用一个从未针对该 Host 验证过的构建。
+
+**「运行通路」显示不可用。** 说明宿主缺少 pi-ai 适配器：`@earendil-works/pi-ai` 或 `@deepseek-ai/dsh-llm-pi-ai` 无法从 DSH 安装目录解析。确认 DSH 安装完整、没有手工裁剪 `node_modules`，然后完全重启桌面应用。
 
 ## 更新与登出
 
-npm 安装可在设置页更新，或运行 `dsh plugin --profile web add dsh-grok-subscription@latest`。GitHub 来源安装可运行 `dsh plugin --profile web update dsh-grok-subscription`。本地链接安装则拉取对应 checkout、测试并构建。更新后手动重启 DSH。
+**更新：** 在 **设置 → 插件** 的安装框里重新填入 `dsh-grok-subscription`（或 `dsh-grok-subscription@版本`）安装即可覆盖；插件自己的设置页也有版本卡片与「更新插件」按钮。完成后**完全退出并重启桌面应用**。
 
-桌面版的 `desktop` profile 由 Electron 应用独占，`dsh plugin --profile desktop …` 会被直接拒绝（`profile "desktop" is managed exclusively by the Electron application`），所以桌面版只能由插件自己更新。1.1.1 起「更新插件」会在该 profile 目录中用 DSH 自带的 pnpm 安装精确版本；若你仍停留在旧版本且按钮报错，可在终端手动执行（pnpm 需 ≥ 11）：
+桌面版的 `desktop` profile 由 Electron 应用独占，`dsh plugin --profile desktop …` 会被直接拒绝（`profile "desktop" is managed exclusively by the Electron application`），因此桌面版的更新由插件在该 profile 目录中用 DSH 自带的 pnpm 安装精确版本。1.1.1 之前插件自己的按钮在桌面版必然失败；界面安装失败时也可以在终端手动执行（pnpm 需 ≥ 11）：
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact dsh-grok-subscription@1.2.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
 ```
 
 然后完全退出并重启桌面版。更新成功后该 profile 的 `package.json` 里依赖应变为目标版本，`dsh.profile.bundles` 条目保持不变。仅刷新网页不够：Host 未重启时仍会加载旧版本。
 
-卸载使用 `dsh plugin --profile web remove dsh-grok-subscription`。这不删除整个 profile、其他插件或 Grok CLI 的 `auth.json`。
+**卸载：** 在 **设置 → 插件** 里移除 `dsh-grok-subscription`，或在该 profile 目录执行 `pnpm remove dsh-grok-subscription`。这不删除整个 profile、其他插件或 Grok CLI 的 `auth.json`。
 
 设置页「登出」清理的是插件侧会话状态，不等于撤销官方 CLI 会话。CLI 文件仍然存在时，之后重新拉取或启动可能再次同步登录；彻底结束官方会话应使用官方 CLI / 账号提供的登出与授权管理流程。不要靠删除整个 DSH profile 来处理一个账号。
 

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 1.2.0",
+  subtitle: "\u7528 SuperGrok / X Premium\uFF08Grok Build\uFF09\u4F1A\u8BDD\uFF0C\u800C\u4E0D\u662F XAI_API_KEY\u3002\xB7 2.0.0",
   signedIn: "\u5DF2\u767B\u5F55",
   signedOut: "\u672A\u767B\u5F55",
   account: "\u8D26\u6237",
@@ -66,11 +66,12 @@ var zh = {
   renderError: "\u754C\u9762\u6E32\u67D3\u5931\u8D25",
   diagnostics: "\u8FD0\u884C\u901A\u8DEF",
   adapterPiAi: "\u5B98\u65B9 pi-ai",
-  adapterFallback: "\u5185\u7F6E\u56DE\u9000",
+  adapterUnavailable: "\u4E0D\u53EF\u7528",
+  adapterStarting: "\u542F\u52A8\u4E2D",
   imageInput: "\u56FE\u7247\u8F93\u5165",
   imageInputOn: "\u53EF\u7528",
   imageInputOff: "\u4E0D\u53EF\u7528\uFF08\u672A\u89E3\u6790\u5230\u5BBF\u4E3B\u9644\u4EF6\u670D\u52A1\uFF09",
-  adapterHint: "\u82E5\u663E\u793A\u300C\u5185\u7F6E\u56DE\u9000\u300D\u4E14\u8D34\u56FE\u88AB\u62D2\uFF0C\u8BF7\u91CD\u542F dsh web \u8BA9\u65B0\u7248\u4E3B\u673A\u7AEF\u751F\u6548\u3002",
+  adapterHint: "\u82E5\u663E\u793A\u300C\u4E0D\u53EF\u7528\u300D\uFF0C\u8BF4\u660E\u5BBF\u4E3B\u7F3A\u5C11 pi-ai \u9002\u914D\u5668\uFF1B\u8BF7\u786E\u8BA4 DSH \u5B89\u88C5\u5B8C\u6574\u540E\u91CD\u542F\u3002",
   busy: "\u5904\u7406\u4E2D\u2026",
   busyCatalog: "\u6B63\u5728\u5237\u65B0\u6A21\u578B\u76EE\u5F55\u2026",
   busyUsage: "\u6B63\u5728\u5237\u65B0\u7528\u91CF\u2026",
@@ -119,7 +120,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.2.0",
+  subtitle: "Use a SuperGrok / X Premium (Grok Build) session, not XAI_API_KEY. \xB7 2.0.0",
   signedIn: "Signed in",
   signedOut: "Signed out",
   account: "Account",
@@ -146,11 +147,12 @@ var en = {
   renderError: "Failed to render this panel",
   diagnostics: "Active path",
   adapterPiAi: "official pi-ai",
-  adapterFallback: "bundled fallback",
+  adapterUnavailable: "unavailable",
+  adapterStarting: "starting",
   imageInput: "Image input",
   imageInputOn: "available",
   imageInputOff: "unavailable (host attachment service not resolved)",
-  adapterHint: 'If this says "bundled fallback" and images are rejected, restart dsh web so the new host bundle loads.',
+  adapterHint: 'If this says "unavailable", the host has no pi-ai adapter; check the DSH installation and restart.',
   busy: "Working\u2026",
   busyCatalog: "Refreshing model catalog\u2026",
   busyUsage: "Refreshing usage\u2026",
@@ -725,12 +727,18 @@ function Chip({ tone = "off", children }) {
     children
   ] });
 }
+var ADAPTER_LABELS = {
+  "pi-ai": "adapterPiAi",
+  unavailable: "adapterUnavailable",
+  starting: "adapterStarting"
+};
 function DiagnosticsRows({ diagnostics, t }) {
   if (!diagnostics) return null;
+  const adapterKey = ADAPTER_LABELS[diagnostics.adapter];
   return /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "gsRows", children: [
     /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "gsRow", children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { children: t("diagnostics") }),
-      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "gsRowValue", children: diagnostics.adapter === "pi-ai" ? t("adapterPiAi") : t("adapterFallback") })
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { className: "gsRowValue", children: adapterKey ? t(adapterKey) : diagnostics.adapter })
     ] }),
     /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "gsRow", children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { children: t("imageInput") }),