dsh-plugin-subscription-oauth 0.10.2 → 0.11.0

package/README.dev.md

@@ -0,0 +1,434 @@
+[English](README.md) · [简体中文](README.zh.md)
+
+# dsh-plugin-subscription-oauth
+
+[![Listed on dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/EricFL1998/dsh-subscription-oauth)
+[![npm](https://img.shields.io/npm/v/dsh-plugin-subscription-oauth.svg)](https://www.npmjs.com/package/dsh-plugin-subscription-oauth)
+[![Licence: MIT](https://img.shields.io/badge/licence-MIT-blue.svg)](LICENSE)
+
+**Use the AI subscriptions you already pay for as LLM providers in DeepSeek
+Harness — no API key.** Sign in once per provider from **Settings →
+Subscriptions** (订阅) and that account's models join the session model picker,
+with its plan quota shown next to the connection.
+
+```sh
+dsh plugin --profile web add dsh-plugin-subscription-oauth
+```
+
+The same package installs straight from the repository, which needs no registry:
+
+```sh
+dsh plugin --profile web add github:EricFL1998/dsh-subscription-oauth
+```
+
+| | |
+| --- | --- |
+| **Capability** | 模型与推理 / Model & inference — it registers LLM provider routes |
+| **Licence** | [MIT](LICENSE) |
+| **Built for** | DeepSeek Harness `0.2.0-rc.2` (`@deepseek-ai/dsh-llm`), Node ≥ 20 |
+| **Platforms** | Windows, macOS and Linux; nothing platform-specific beyond Node itself |
+| **Accounts** | your own subscriptions only — credentials stay on your machine |
+| **Network** | the providers' own hosts and the OAuth endpoints listed below; no telemetry, no third-party relay |
+
+| Route | Provider | Login | Wire |
+| --- | --- | --- | --- |
+| `kimi` | Kimi Code | OAuth **device flow** (RFC 8628) | OpenAI **Responses** — `https://api.kimi.com/coding/v1/responses` |
+| `grok` | Grok (X Premium) | OIDC **authorization code + PKCE** on a loopback callback | OpenAI **Responses** — `https://api.x.ai/v1/responses` |
+| `antigravity` | Google Antigravity | Google **authorization code + PKCE** (`/oauth-callback`) plus Cloud AI Companion project discovery | Cloud Code Assist `v1internal` — `streamGenerateContent?alt=sse` |
+| `glm` | GLM (BigModel) | ZCode's **browser sign-in with a polled flow** (China region) | OpenAI **Responses** — `https://open.bigmodel.cn/api/coding/paas/v4/responses` |
+| `ark` | Volcengine Ark | Volcengine **SSO** (authorization code + PKCE on a loopback callback) | OpenAI **Responses** — `https://ark.cn-beijing.volces.com/api/coding/v3/responses` |
+| `auto` | Auto | none — it holds no account of its own | delegates to whichever route owns the model it picks |
+
+The Kimi device flow is the one `opencodex` uses; the Grok flow is the one its
+CLI uses (`auth.x.ai` discovery, client `b1a00492-…`, port `56121`, scope
+`grok-cli:access`); the Antigravity flow is Google's desktop OAuth client
+(`accounts.google.com`, port `51121`, scopes including `cclog` and
+`experimentsandconfigs`), with the account's project discovered through
+`loadCodeAssist`.
+
+**GLM signs in the way ZCode does**, not with an API key: the plugin asks
+`zcode.z.ai` for a login flow, opens `bigmodel.cn/login` in the browser, and polls
+the flow until the subscription's tokens come back. Nothing has to receive a
+`zcode://oauth/callback` redirect and no app secret is involved, because the
+callback is completed server-side and the flow is authenticated by a secret the
+plugin generates itself. Allowances are read from BigModel's own
+`/api/monitor/usage/quota/limit`, which meters a rolling five-hour window and a
+weekly one.
+
+**Ark signs in with Volcengine SSO** (authorization code + PKCE on a loopback
+callback, the flow its own CLI uses) and then has to satisfy two planes that want
+different credentials. The **data plane** takes only an ordinary API key as a plain
+bearer — it refuses STS credentials outright — while the **control plane**, a
+different host, is signed with the temporary STS credentials that the SSO token
+response carries. So a sign-in mints one API key through the control plane (reusing
+a key this plugin already created, if there is one) and keeps the STS set for the
+quota, which is read per subscription period and per model's free allowance.
+
+## What it registers
+
+| Surface | What appears |
+| --- | --- |
+| `ctx.llm` | the `kimi`, `grok`, `antigravity`, `glm` and `auto` provider routes (models, reasoning efforts, streaming) |
+| Settings | a **Subscriptions** section: one card per provider — sign in, sign out, default account, token refresh, plan quota, model catalog, manage dialog |
+| Model picker | each provider's own models, plus **`auto` as its own route** spanning them — Kimi ships `kimi-for-coding`, `k3`, `k3[1m]`, `k3-256k`; Grok seeds `grok-4.6`, `grok-4.5` and adds whatever its live catalog reports; Antigravity lists the agent-callable subset of what its endpoint reports (`fetchAvailableModels`), filtering out tabs, commit-message and transcription surfaces; GLM ships the `glm-5.3` family (`glm-5.3`, `glm-5.3-flash`, `glm-5.2`, `glm-5.1`, `glm-5`) and adds whatever its coding host lists |
+
+Credentials live at `~/.dsh/plugins/kimi-oauth/auth.json` (mode `0600`,
+written atomically, one section per provider). The directory keeps the name this
+plugin had when it served Kimi Code alone: it holds **live logins**, so it is left
+in place rather than renamed, and every profile that mounted the earlier version
+finds its accounts exactly where it left them. This machine's Kimi device id
+lives beside it in `kimi-device-id`; it is stable across restarts, because the
+service correlates usage to it.
+
+### Token lifetimes, and why the card may say "expired"
+
+Kimi Code access tokens live **15 minutes**; the refresh token lives **30 days**.
+Grok access tokens are similar. Every request refreshes automatically when the
+access token is within five minutes of lapsing, and the Settings card refreshes
+eagerly while you are looking at it — so what it shows is the live expiry, and
+"token expired" appears only when a refresh genuinely failed and the account
+needs a new sign-in. Access-token expiry is normal and does not mean the login
+is gone.
+
+## Settings page
+
+| Every route folded | A subscription card open | A card with its catalog |
+| --- | --- | --- |
+| ![Folded provider list](docs/images/providers-folded.png) | ![GLM card with plan quota](docs/images/glm-card-open.png) | ![Kimi card with its catalog](docs/images/kimi-card-open.png) |
+
+The page leads with **`auto`**, the way to reach every other route at once; the
+routes it stands in for follow in the order they were configured. Each route is one
+**folded row** — status dot, name, route key, a one-line summary of the connection,
+and an **Edit** button — so the section reads as a list of providers and opens one
+on demand. **Every visit starts folded** — an open card is a gesture within one
+visit, not a stored setting — so re-opening Settings always shows the same compact
+list. Inside an open card are the
+account rows (★ sets the default account, `退出登录`/`Sign out` removes one), the
+model catalog, and the plan quota. Controls follow the host's own settings-form
+vocabulary — a 6 px radius (`--dsw-radius-sm`), a transparent fill, a hairline
+border, and the theme's hover/active/focus tokens — declared in one scoped
+stylesheet, so the page keeps that look instead of falling back to the browser's
+default button chrome.
+
+The **Models** heading is its own disclosure, **folded on every visit** too: click it to open the
+catalog. **Each model has its own switch** (a toggle,
+not a checkbox), which decides whether the session model picker offers it. The
+choice is stored on the host (`~/.dsh/plugins/kimi-oauth/preferences.json`) as a
+hidden list, so it survives restarts and every session sees it; a model added by a
+later catalog refresh appears automatically rather than arriving hidden. A hidden
+model is listed dimmed and stays **resolvable** — an existing session that already
+selected it keeps working — so hiding is a picker-visibility choice, not a
+revocation. `· 已隐藏 N 个` in the header counts the hidden ones.
+
+**Add model** publishes an id this build has never heard of, so a model released
+after the plugin was built is usable at once. The id is checked for shape, not
+against a list — the endpoint is the only authority on what it serves — and it is
+stored per route, published with conservative metadata, and listed with a `×` so a
+typo can be removed again. **Drag a row** by its ⠿ grip (or press ↑ / ↓ while the
+grip is focused) to re-order the list; that order is what the picker follows for
+that route.
+
+**`auto` is a provider of its own** (route `auto`), not a model inside each one: it
+stands in for the enabled models of *every* provider the harness serves in one list,
+each row badged with the provider that owns it. That includes the routes this plugin
+registers **and** the ones it does not — the built-in DeepSeek providers and any
+provider you added yourself — because it enumerates the harness roster
+(`ctx.llm.listProviders()` / `listModels()`) and dispatches through it rather than
+looking only at its own routes. It leads both the Settings section and the model
+picker, because it is the one entry that reaches every route. It has no account, so
+its card offers no connect or manage — only the list. A switch takes a model out of
+Auto **without** hiding it from the picker, drag re-orders what Auto tries first, and
+the arrangement is stored separately (`auto.order` / `auto.off`). Switch every model
+off and Auto is simply not offered in the picker.
+
+A provider with no signed-in account contributes no rows: `listModels` answers with
+nothing until a route has a session, so signing out removes that route's models from
+the picker and from Auto at the same time, and its card hides the catalog instead of
+offering models that cannot be called.
+
+Auto falls through to the next model when the provider refuses the preferred one
+(renamed or gone, rate-limited, out of allowance, or a transport failure). A
+concrete model id never falls back — it dispatches to exactly that model. Once a
+stream has produced any output the turn belongs to that model, so a later failure
+is reported instead of being papered over by a second model's text. Every fallback
+is logged (`model X unavailable … falling back to Y`).
+
+**Plan and usage** shows the subscription tier and every allowance the provider
+states, with a meter and a reset time: Kimi's rolling 5-hour window, weekly window
+and included credit (`GET /coding/v1/usages`); Grok's weekly included credit
+(`cli-chat-proxy.grok.com/v1/billing?format=credits`, plus the plan tier from the
+token's own `tier` claim); and Antigravity's **four** buckets — Gemini and Claude,
+each rolling and weekly — read from `v1internal:retrieveUserQuotaSummary`, falling
+back to the per-model `quotaInfo` of `fetchAvailableModels` (worst-spent model per
+family, classified by id, display name and tier, so an `Opus` row counts as
+Claude). A provider that states nothing says so instead of inventing a figure.
+
+A reset is stated by how far off it is, on every route: **minutes** within the hour
+(`40 分钟后重置`), **hours** within the day (`4 小时后重置`), and the date beyond that
+(`重置时间 2026/10/17 13:54`) — the count is what a reader acts on when deciding whether
+there is room left, and a date is what they need when it is a week away. Because the
+page re-reads the figures on a slow interval, the count follows along while it is
+open.
+
+**Manage** opens a dialog with per-account token refresh, the credential-file
+path, and the resolved endpoints.
+
+While a device authorization is pending the card shows the code, its expiry, and
+the buttons to open or copy it, and the status dot turns amber. A loopback
+provider (Grok) instead shows a sign-in link and waits for the browser redirect.
+
+## Install
+
+```sh
+dsh plugin --profile web add dsh-plugin-subscription-oauth
+```
+
+`web` is the profile that serves the Settings page; use `desktop` (or any other
+profile name) if that is the one you run.
+
+The CLI forwards its arguments to pnpm, so a pinned version, a git URL and a local
+path are all spelled the same way:
+
+```sh
+dsh plugin --profile web add dsh-plugin-subscription-oauth@0.2.2
+dsh plugin --profile web add github:EricFL1998/dsh-subscription-oauth
+dsh plugin --profile web add /path/to/dsh-plugin-subscription-oauth
+```
+
+Restart `dsh web` (or the desktop app) afterwards so the new bundle loads. A local
+directory is installed as a `link:`, so afterwards `npm run build` in the checkout
+is enough to publish a change; restart again to pick it up.
+
+The host packages (`@deepseek-ai/dsh-llm` and the rest) are **optional** peers: the
+harness provides them at runtime, so installing this plugin does not fetch a second
+copy of the host it is running inside.
+
+### Releasing (maintainers)
+
+`prepublishOnly` rebuilds `lib/` — the TypeScript output plus the browser bundle — so
+a published tarball can never carry a stale client:
+
+```sh
+npm version patch   # or minor/major
+npm publish
+```
+
+For a headless composition that only needs the model route (no Settings page):
+
+```sh
+dsh --profile headless --patch /path/to/dsh-plugin-subscription-oauth/overlay.yml "your task"
+```
+
+where `overlay.yml` is a one-entry patch naming
+`/path/to/dsh-plugin-subscription-oauth/lib/index.js`. Log in once from a web profile
+first — the token file is shared.
+
+## Hiding a built-in provider from the picker
+
+A plugin cannot unregister another bundle's route (`ctx.llm` has no unregister
+API), so hiding a built-in provider is a profile-patch change. To hide the
+**DeepSeek API-key** route and its models while keeping the **DeepSeek account**
+(sign-in) route:
+
+```yaml
+# $DSH_HOME/profiles/<profile>/cordis.patch.yml
+- id: llm-deepseek
+  name: "@deepseek-ai/dsh-llm-deepseek-api-key"
+  config:
+    models: []
+```
+
+`models` replaces the adapter's default catalog, so `deepseek-official` reports
+no models and the picker hides the empty group (`Empty groups are hidden`); the
+route stays registered, so a session that already saved one of its model ids
+keeps working. Leave `llm-deepseek-account` alone to keep the account route.
+Restart the profile (or let HMR reload) for the change to apply.
+
+## Use
+
+1. Open **Settings → Subscriptions** (订阅) and press **Connect** on the card you want.
+2. Finish the sign-in the card shows: Kimi Code and (when answered) a device code
+   you approve in the browser; Grok and Antigravity open a sign-in page and wait for
+   the redirect. The section updates by itself while an attempt is pending.
+3. Open the model picker in any session and choose a model under that provider —
+   or leave it on **Auto** to let the enabled models be tried in order.
+
+Not signed in? The provider stays out of the picker, and a request fails with
+`INVALID_CREDENTIAL` pointing at the Settings page. Nothing else breaks.
+
+Multiple accounts are supported: connect again to add another. The ★ default
+account serves requests; use **Use by default** to switch.
+
+## Config
+
+```yaml
+- id: llm-subscription-oauth
+  name: dsh-plugin-subscription-oauth
+  config:
+    providers: [kimi, grok, antigravity]  # routes to register; all are default
+    enabled: true
+    discovery: true                  # consult each endpoint's live model list
+    streamIdleTimeoutMs: 300000      # abandon a silent stream after this
+    defaultModel: kimi-for-coding    # model the picker preselects on the Kimi route
+    extraModels: []                  # Kimi ids to publish without shipped metadata
+    # oauthHost: https://auth.kimi.com
+    # apiBase: https://api.kimi.com/coding/v1
+```
+
+Only the Kimi route takes `oauthHost`/`apiBase`/`defaultModel`/`extraModels`: the
+Grok and Antigravity endpoints are fixed by their own clients, and their model
+lists come from the live catalog. Omitting a route from `providers` simply leaves
+it unregistered.
+
+`oauthHost` and `apiBase` can also come from the environment
+(`KIMI_CODE_OAUTH_HOST` / `KIMI_OAUTH_HOST`, `KIMI_CODE_API_BASE` /
+`KIMI_API_BASE`); an explicit config value wins. `apiBase` accepts either the
+bare base or the full `.../responses` URL.
+
+## How it works
+
+The package is a standard DeepSeek Harness plugin: `lib/index.js` exports
+`apply(ctx)`, which registers one `ctx.llm` adapter per route and mounts the
+Settings section through `ctx.slots`. `lib/client.js` is the browser half — the
+section itself, loaded by the harness bundle loader. Nothing runs outside the
+harness process, and uninstalling the bundle removes every route it added.
+
+**Login** is the RFC 8628 device authorization grant against
+`auth.kimi.com`. The plugin requests a device code, shows it, and polls the
+token endpoint with `authorization_pending` / `slow_down` / `access_denied` /
+`expired_token` handling until the browser approves. Tokens are stored per
+account, keyed by the `user_id` (or `sub`) claim inside Kimi's JWTs.
+
+**Grok** signs in with the flow its own CLI uses: OIDC discovery at
+`auth.x.ai`, an authorization-code exchange with PKCE on a loopback callback
+(`127.0.0.1:56121/callback`), and a refresh grant that keeps the client identity.
+**Antigravity** is Google's desktop OAuth client on `127.0.0.1:51121`, whose
+scopes include `cloud-platform`; login is only complete once `loadCodeAssist`
+reports the account's Cloud AI Companion project, because every later
+`v1internal` call is scoped to it.
+
+**Requests** carry three identity layers:
+
+* the bearer access token, refreshed ahead of expiry (5-minute preempt) with one
+  in-flight refresh shared per account;
+* Kimi's `X-Msh-*` client identity (`KimiCLI/<version>`, platform, device id) —
+  the service admits the request by this family;
+* the harness attribution product. Because Kimi admits a request by the CLI
+  product token while the harness requires its own attribution on every provider
+  request, the two are joined into one RFC 9110 `User-Agent` value rather than
+  sent as two competing fields.
+
+**The wire** is OpenAI Responses: `instructions` + `input` items,
+`function_call` / `function_call_output` kept adjacent (the endpoint requires
+it), `stream: true`, `store: false`, `prompt_cache_key` from the session id for
+cache affinity, and `reasoning.effort` mapped from the harness's effort id.
+Stored reasoning is never replayed as text — the endpoint keeps a subscription
+account's thinking encrypted server-side, so each turn stands on its own visible
+content.
+
+Kimi locks temperature and sampling penalties on subscription coding models, so a
+caller-supplied `temperature` is dropped rather than rejected upstream.
+
+## Troubleshooting
+
+| Symptom | Cause |
+| --- | --- |
+| `<provider> login expired; sign in again…` | the refresh token was rejected; connect again |
+| No models in the picker | not signed in, or the route was not re-announced — check **Settings → Subscriptions** |
+| No models at all for Antigravity | the account's `fetchAvailableModels` returned nothing; the route ships no curated list, so press **Refresh** after signing in |
+| `model not found` | the id is not served by your plan; use **Refresh** |
+| The code card never clears | the attempt is still pending or expired; press **Cancel** and connect again |
+| `model discovery failed … using the built-in catalog` | the live list was unreachable; the shipped catalog still works (Kimi and Grok ship one, Antigravity does not) |
+| Rows cannot be dragged | the layout is switched off in Settings, or the drag started on the checkbox — grab the ⠿ grip |
+
+## Security notes
+
+### What it stores, and where
+
+| Path | Contents | Mode |
+| --- | --- | --- |
+| `~/.dsh/plugins/kimi-oauth/auth.json` | one section per provider: access token, refresh token, expiry, account id, plan | `0600`, written atomically |
+| `~/.dsh/plugins/kimi-oauth/preferences.json` | model visibility, your ordering, and Auto's chain — no secrets | `0600` |
+| `~/.dsh/plugins/kimi-oauth/kimi-device-id` | the stable device id Kimi's API expects | `0600` |
+
+The directory keeps the name this plugin had when it served Kimi Code alone: it
+holds **live logins**, so renaming it would sign everyone out. Nothing is stored
+outside `~/.dsh`, and nothing is uploaded anywhere except to the providers
+themselves.
+
+### What it talks to
+
+| Route | Hosts contacted | Why |
+| --- | --- | --- |
+| `kimi` | `auth.kimi.com`, `api.kimi.com` | device-flow sign-in, then the coding API |
+| `grok` | `auth.x.ai`, `api.x.ai`, `cli-chat-proxy.grok.com` | OIDC sign-in, the Responses API, the plan's credit figure |
+| `antigravity` | `accounts.google.com`, `oauth2.googleapis.com`, `cloudcode-pa.googleapis.com` | Google sign-in, the account's project, then Cloud Code Assist (including its quota accounting) |
+| `glm` | `bigmodel.cn`, `zcode.z.ai`, `open.bigmodel.cn` | browser sign-in brokered by ZCode, then the coding-plan API and its allowance |
+| `ark` | `signin.volcengine.com`, `ark.cn-beijing.volces.com`, `ark.cn-beijing.volcengineapi.com` | Volcengine SSO, then the coding-plan API (data plane) and the signed control plane that mints the API key and reports the allowance |
+
+There is no analytics, no update ping and no relay through anyone else's server:
+every request goes to the host that owns the account. No request body, prompt or
+token is ever logged.
+
+### Boundaries worth knowing
+
+* The token file is written with mode `0600`; only the account id, email, host,
+  and device id are ever shown in the UI — never a token.
+* The Kimi and GLM flows need no listener on this machine at all: Kimi polls, and
+  GLM's browser callback is completed server-side by the provider. Grok and
+  Antigravity hold one loopback listener **only** while a login attempt is pending,
+  on `127.0.0.1:56121` and `127.0.0.1:51121`, and it is closed as soon as the
+  attempt settles or lapses. A loopback destination is never proxied.
+* Outbound requests honour `HTTPS_PROXY` / `HTTP_PROXY` / `ALL_PROXY` and
+  `NO_PROXY`.
+* Signing in authorizes this machine for that account — the provider's own consent
+  screen is the consent step, and it is never completed on your behalf.
+* A plugin cannot unregister another bundle's provider (`ctx.llm` has no unregister
+  API), so this plugin never hides anything you had before; see
+  [Hiding a built-in provider from the picker](#hiding-a-built-in-provider-from-the-picker)
+  if that is what you want.
+* **Known limits**: OpenAI-compatible API keys are not supported by design (this is
+  a subscription plugin); GLM's flow has no refresh grant, so a lapsed sign-in asks
+  you to sign in again rather than renewing silently; Antigravity ships no curated
+  model list and depends on its endpoint answering.
+
+## Develop
+
+```sh
+npm install        # development baseline: published DSH 0.2.0-rc.2 packages
+npm run build      # tsc (lib/) + tsdown (lib/client.js browser bundle)
+npm test           # node --test over the compiled unit specs
+npm run typecheck  # tsc --noEmit
+```
+
+`tools/probe-kimi-oauth.mjs` performs a live check that Kimi accepts the shipped
+client id and identity headers; it starts a device authorization and immediately
+abandons it, so no account is touched (`npm run build` first).
+
+### Reviewing the settings UI without a host
+
+`tools/preview-entry.tsx` mounts the real section with a stubbed RPC caller, so
+a design change can be screenshotted on its own. Query flags drive the states:
+`?dark=1`, `?grok=1`, `?ag=1`, `?busy=1`, `?hide=1`, `?collapse=1`, `?manage=1`.
+
+```sh
+npm run preview                                 # bundles probe/preview.js
+# then open probe/preview.html in a browser, or screenshot it headlessly:
+msedge --headless=new --user-data-dir=%TEMP%\shot --window-size=620,1900 \
+  --screenshot=shot.png "file:///<checkout>/probe/preview.html?dark=1&grok=1&ag=1"
+```
+
+The harness deliberately styles no `button` of its own: the shell gives its
+controls chrome through a CSS class plugin markup does not carry, so a preview
+that decorated bare buttons would hide exactly the regression this page had.
+
+Query flags: `dark=1` (dark theme), `compact=1` (model list collapsed),
+`busy=1` (pending device authorization), `manage=1` (manage dialog open).
+`probe/` holds only generated preview output and is gitignored; the committed
+screenshots live in `docs/images/`.
+
+After `npm run build`, restart `dsh web` to pick up the change.
+
+## License
+
+MIT