dsh-plugin-subscriptions 0.5.3 → 0.6.0

package/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Use your **ChatGPT (Codex)**, **Claude**, and **Grok (X Premium)** subscriptions as LLM providers in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — no API keys. Codex and Grok log in via OAuth in the dsh web UI (Settings → Subscriptions); Claude imports credentials from an existing Claude Code session when there is one (macOS Keychain or `~/.claude/.credentials.json`) and otherwise falls back to the same browser OAuth flow, so the Claude Code CLI is not required. Tokens live at `~/.dsh/plugins/subscriptions/auth.json` (mode 0600) and refresh automatically.
+Use your **ChatGPT (Codex)**, **Claude**, **Grok (X Premium)**, and **GitHub Copilot** subscriptions as LLM providers in [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — no API keys. Codex and Grok log in via OAuth in the dsh web UI (Settings → Subscriptions), while Copilot uses the GitHub OAuth device flow; Claude imports credentials from an existing Claude Code session when there is one (macOS Keychain or `~/.claude/.credentials.json`) and otherwise falls back to the same browser OAuth flow, so the Claude Code CLI is not required. Tokens live at `~/.dsh/plugins/subscriptions/auth.json` (mode 0600) and refresh automatically.
 
 ## Demo
 
@@ -106,8 +106,8 @@ Either way, restart `dsh web` afterwards so the new version loads.
 ## Use
 
 1. `dsh web`, open the printed URL.
-2. Settings → **Subscriptions**: click **Connect** on a provider. For Claude, credentials are imported instantly if you have run `claude` and logged in at least once; without them, Claude authorizes in the browser like the others. For Codex and Grok, authorize in the opened browser tab; if the browser flow can't complete (headless host), expand the manual fallback and paste the callback URL or code.
-3. In any session, open the model picker (`/model`) and choose a model under **ChatGPT (Codex)** / **Claude (Subscription)** / **Grok (Subscription)**.
+2. Settings → **Subscriptions**: click **Connect** on a provider. For Claude, credentials are imported instantly if you have run `claude` and logged in at least once; without them, Claude authorizes in the browser like the others. For Codex and Grok, authorize in the opened browser tab; Copilot shows a GitHub device code to enter at `github.com/login/device`; if a browser flow can't complete (headless host), expand the manual fallback and paste the callback URL or code.
+3. In any session, open the model picker (`/model`) and choose a model under **ChatGPT (Codex)** / **Claude (Subscription)** / **Grok (Subscription)** / **GitHub Copilot**.
 
 Not logged in? The provider stays out of the picker, and requests fail with `MISSING_CREDENTIAL` pointing at the Settings page; nothing else breaks.
 
@@ -115,14 +115,23 @@ Not logged in? The provider stays out of the picker, and requests fail with `MIS
 
 Every provider accepts several accounts: once one is connected, the card grows an **Add account** button (Claude offers **Browser authorization** and **Import Claude Code** separately). Accounts are keyed by their identity (email / login) — re-logging the same account updates it in place, a different account appends. Browser authorization signs in whichever account the browser currently uses, so switch accounts there first (or use an incognito window with the manual code) to add a different one. The ★ default account serves the direct provider routes; pool routes use every account. A Claude account imported from Claude Code stays synced with the CLI's credential store; OAuth-added Claude accounts refresh standalone so several accounts never fight over the Keychain entry.
 
+### Default reasoning effort per model
+
+Every logged-in provider card in Settings → Subscriptions carries a collapsible **Default reasoning effort** section. It starts collapsed — the header shows how many models advertise reasoning levels and how many you have overridden — and the model list (with its live catalog lookup) loads only once you expand it, so a provider with dozens of models does not stretch the page or make it pay for a lookup nobody asked for. Expanded, each model that advertises reasoning levels gets a row whose options are the levels that provider's live catalog advertises for that exact model; past 8 such models the section also offers a name filter, and models without reasoning levels collapse into a single count line instead of one dead row each. With several accounts connected, the model list is the union across that provider's accounts, so a model any account advertises gets a row; the levels offered for it come from the first account whose catalog lists it (the ★ default account first), matching what the session picker resolves.
+
+Pick a level to make the session model picker preselect it whenever you switch to the model — no more settling for the provider's own default (e.g. Claude shows `Default`, Codex models follow `default_reasoning_level`). Choose **Follow provider** to clear the override. The choice is stored in `~/.dsh/plugins/subscriptions/model-defaults.json` (mode 0600) and survives restarts.
+
 ## Config
 
 ```yaml
 - id: llm-subscriptions
   name: dsh-plugin-subscriptions
   config:
-    providers: [codex, claude]        # subset; default all three
+    providers: [codex, claude]        # subset; default all four
     streamIdleTimeoutMs: 300000
+    rateLimit:
+      wait: true                       # wait out a closed rate-limit window (default)
+      maxWaitMs: 21600000              # ceiling on one wait; 6 h, covers a 5-hour session window
     models:                            # override the discovered/built-in catalogs
       codex:
         - { id: gpt-5.6-sol, name: GPT-5.6 Sol, contextWindow: 272000, inputModalities: [text, image] }
@@ -145,7 +154,7 @@ When a provider has **two or more logged-in accounts**, the picker shows the **u
 - **Explicit account lists (`families`).** Replace the auto member list for one catalog model (same provider only; cross-provider members are ignored). Pin `account` or omit it for the default.
 - **Tier extras (`tiers`, optional).** Extra picker rows with heterogeneous fallbacks, listed under the first member's provider. Not created automatically.
 
-Selection is sticky per session (prompt caches survive) with two strategies: `priority` (first healthy member wins) and `quota_aware` (the default — each member is scored by its required burn rate, `remaining quota / time until window reset`, so a window about to reset with plenty left gets spent instead of wasted; the sticky member holds until a challenger out-scores it by `switchMargin`). Members past 95% on any usage window are gated out; failures fail over before the first stream chunk with cooldowns (`retry-after` when the provider sends one) — quota and auth failures cool the whole account down (its quota is account-level; Claude's model-scoped lanes cool per member), transient server failures cool only the failing member. Copilot exposes no usage telemetry, so it scores zero and naturally serves as the fallback of last resort.
+Selection is sticky per session (prompt caches survive) with two strategies: `priority` (first healthy member wins) and `quota_aware` (the default — each member is scored by its required burn rate, `remaining quota / time until window reset`, so a window about to reset with plenty left gets spent instead of wasted; the sticky member holds until a challenger out-scores it by `switchMargin`). Members past 95% on any usage window are gated out; failures fail over before the first stream chunk with cooldowns (`retry-after`, or the window's own disclosed reset when the provider sends one) — quota and rate-limit failures cool the whole account down (its quota is account-level; Claude's model-scoped lanes cool per member), transient server failures cool only the failing member. Copilot exposes no usage telemetry, so it scores zero and naturally serves as the fallback of last resort.
 
 ```yaml
 - id: llm-subscriptions
@@ -167,6 +176,36 @@ Selection is sticky per session (prompt caches survive) with two strategies: `pr
           - { provider: grok, model: grok-4.6 }
 ```
 
+### Waiting out a rate-limit window
+
+A subscription plan is rate-limit shaped by design — a 5-hour session window, a weekly one, and on some plans a per-model weekly one — so a 429 is not a dead end: the window reopens at a time the provider discloses. Each route reads that reset off its own 429 and turns it into that account's pool cooldown (see Model pools above) instead of a fixed 5-minute guess.
+
+Only a signal that names the window which actually rejected the request is read: Anthropic's `anthropic-ratelimit-unified-reset`, the seconds Codex puts on a `usage_limit_reached` rejection, the delay xAI names in the error body, or a plain `retry-after`. The per-bucket rollover snapshots (`anthropic-ratelimit-{requests,tokens,…}-reset`, `x-codex-*-reset-after-seconds`, `x-ratelimit-reset-*`) ride every response and cannot say which bucket refused — the earliest is usually one that still had room — so a 429 carrying nothing else is logged through the plugin's warning sink, naming the headers and the head of the body, rather than parking the turn (or the pool cooldown) on a guess.
+
+Reading is confined to a 429. Every other failure keeps its short local backoff: those same headers ride a transient 500 too, and honouring them there would hold a turn for the rest of the window over an overload that clears in a second.
+
+With a pool, this is what actually does the waiting: a 429'd account is parked until its own disclosed reset and the request fails over to another account of the same provider immediately — no wait, no lost turn. Only once **every** account (the whole pool) is cooling down does the adapter report a `RATE_LIMIT` carrying the pool's *earliest* reset as the wait to take. With a single account (no pool, or a provider with only one login), that same disclosed reset is reported directly.
+
+Waiting on that reported delay is executed by [`@deepseek-ai/dsh-llm-retry`](https://www.npmjs.com/package/@deepseek-ai/dsh-llm-retry), which every route's retry policy is written for: add it to the composition, or nothing waits and a closed window fails the turn as before (falling back to whichever other pool accounts are healthy, if any).
+
+```yaml
+- name: '@deepseek-ai/dsh-llm-retry'
+```
+
+```yaml
+- name: dsh-plugin-subscriptions
+  config:
+    rateLimit:
+      wait: true            # default; false keeps the previous seconds-scale behaviour
+      maxWaitMs: 21600000   # 6 h — covers a 5-hour session window with slack
+```
+
+A reset further out than `maxWaitMs` — a weekly window days away, or a whole pool cooling down past it — fails the turn immediately with the reset time attached, rather than parking the session for days. `wait: false` drops back to local backoff alone.
+
+All four routes share Claude Code's own retry shape: ten retries after the first attempt, backing off from 1 s with 20% jitter under a 60 s cap. These are consumer subscription endpoints that shed load in bursts, and the dsh-llm defaults (five retries from 500 ms to 10 s) give up after about fifteen seconds, which is short for that. A 429 that discloses no reset is now retried locally for roughly 17 minutes before the turn fails — about 5 minutes with `wait: false`, where the 60 s cap actually binds. Copilot currently uses the generic `retry-after` signal; unrecognized GitHub rate-limit headers are surfaced through the plugin warning sink for a future provider-specific reader.
+
+One trade-off worth knowing: the delay ceiling is shared with that local backoff, so raising `maxWaitMs` also raises how long an unrelated transient failure (`TRANSPORT`, `SERVER`, `TIMEOUT`) can back off for before the finite retry budget runs out — up to 512 s on the last of the ten retries instead of the 60 s cap.
+
 ## Proxy
 
 Every subscription request — token exchanges, model-API streams, usage lookups, model discovery, and the `x_search` / `image_generate` / `video_generate` tools — can be routed through an HTTP(S) proxy. Configure it in **Settings → Subscriptions → Proxy → Configure…**: enable the flag, enter the proxy URL (`http://127.0.0.1:7890`), optional username/password, and an optional comma-separated bypass list of hostnames that stay direct (`127.0.0.1`, `localhost`, `*.example.com`). The password is stored in `~/.dsh/plugins/subscriptions/proxy.json` (mode 0600) and is never returned to the browser. A "Test" button probes one endpoint through the current configuration and shows the HTTP status/latency.
@@ -189,7 +228,7 @@ After `pnpm build`, restart `dsh web` to pick up changes.
 
 - `src/index.ts` — plugin entry: config schema, adapter registration, auth-change re-announce, RPC wiring
 - `src/auth/` — PKCE/JWT helpers, token store, OAuth flow engine (temp loopback callback server), Claude Code credential reader (Keychain/file), `/subscriptions-auth` RPC channel
-- `src/providers/` — per-provider OAuth constants/exchange/refresh + `LlmAdapter`s, multi-account token plumbing (`accounts.ts`), and the pool (`pool.ts` + `pool-health.ts` / `pool-usage.ts` / `pool-family.ts`)
+- `src/providers/` — per-provider OAuth constants/exchange/refresh + `LlmAdapter`s, multi-account token plumbing (`accounts.ts`), the pool (`pool.ts` + `pool-health.ts` / `pool-usage.ts` / `pool-family.ts`), and `rate-limit.ts` (reset-instant parsing + retry policy)
 - `src/translate/` — dsh `Message[]` ⟷ OpenAI Responses / Anthropic Messages wire formats, SSE → `StreamChunk`
 - `src/tools/` — `x_search`, `image_generate`, and `video_generate`
 - `src/client/` — the Settings → Subscriptions page (browser half, zh/en, theme-token aware)

package/README.zh.md

@@ -106,8 +106,8 @@ GitHub 安装的:重新执行一遍 `add github:V1ki/dsh-plugin-subscriptions`
 ## 使用
 
 1. `dsh web`,打开打印的 URL。
-2. **设置 → 订阅**:点对应 provider 的「连接」。若先运行过 `claude` 并登录,Claude 会即时导入凭据;没有凭据时,Claude 也和其他 provider 一样在浏览器里授权。Codex 和 Grok 在打开的标签页里授权;无浏览器环境下可展开手动兜底,粘贴回调 URL 或授权码。
-3. 在任意会话里打开模型选择器(`/model`),选择 **ChatGPT (Codex)** / **Claude (Subscription)** / **Grok (Subscription)** 下的模型。
+2. **设置 → 订阅**:点对应 provider 的「连接」。若先运行过 `claude` 并登录,Claude 会即时导入凭据;没有凭据时,Claude 也和其他 provider 一样在浏览器里授权。Codex 和 Grok 在打开的标签页里授权;Copilot 会显示 GitHub 设备码,需在 `github.com/login/device` 输入;无浏览器环境下可展开手动兜底,粘贴回调 URL 或授权码。
+3. 在任意会话里打开模型选择器(`/model`),选择 **ChatGPT (Codex)** / **Claude (Subscription)** / **Grok (Subscription)** / **GitHub Copilot** 下的模型。
 
 未登录时:该 provider 不出现在选择器里;直接请求会报 `MISSING_CREDENTIAL` 并提示去设置页登录,不影响其他功能。
 
@@ -115,14 +115,23 @@ GitHub 安装的:重新执行一遍 `add github:V1ki/dsh-plugin-subscriptions`
 
 每个 provider 可以登录多个账号:连上第一个之后,卡片会出现「添加账号」按钮(Claude 拆分为「浏览器授权」和「导入 Claude Code」两种)。账号按身份(邮箱/用户名)归档——重复登录同一账号是覆盖更新,不同账号才是新增。浏览器授权以浏览器当前登录的账号为准,要添加不同账号请先在浏览器切换账号,或用无痕窗口走手动授权码。★ 默认账号服务直连路由;池路由会使用所有账号。从 Claude Code 导入的 Claude 账号会与 CLI 的凭据存储保持同步;OAuth 添加的 Claude 账号独立刷新,多个账号不会互相覆盖 Keychain。
 
+### 按模型的默认推理档
+
+**设置 → 订阅**里每个已登录 provider 卡片都有一个可折叠的**默认推理档**区块。默认收起,标题栏直接给出「多少个模型声明了推理档 / 已覆盖多少个」;模型列表(以及它背后的 live 目录查询)只在展开时才加载 —— 这样模型数量很多的 provider(Copilot 动辄几十个)既不会把页面撑长,也不会白跑一次目录查询。展开后,凡声明了推理档的模型各占一行,可选档位就是该 provider live 目录为这个模型声明的档位;此类模型超过 8 个时区块还会给出一个名称筛选框;没有推理档的模型不再一行一条占位,而是合并成一行计数说明。登录了多个账号时,模型列表是该 provider 各账号目录的并集 —— 任一账号声明的模型都会出现;而某个模型可选的档位取自**第一个列出它的账号**(★ 默认账号优先),与会话选择器解析到的一致。
+
+选中某档后,会话模型选择器在切换到该模型时会自动预选该档位,不必再接受 provider 自己的默认值(例如 Claude 只显示 `Default`,Codex 模型跟随 `default_reasoning_level`)。选择「跟随服务商」可清除覆盖。配置存于 `~/.dsh/plugins/subscriptions/model-defaults.json`(权限 0600),重启后依然生效。
+
 ## 配置
 
 ```yaml
 - id: llm-subscriptions
   name: dsh-plugin-subscriptions
   config:
-    providers: [codex, claude]        # 子集;默认三个全启用
+    providers: [codex, claude]        # 子集;默认四个全启用
     streamIdleTimeoutMs: 300000
+    rateLimit:
+      wait: true                       # 等待限流窗口重开(默认开启)
+      maxWaitMs: 21600000              # 单次等待上限;6 小时,足够覆盖 5 小时会话窗口
     models:                            # 覆盖实时发现/内置目录
       codex:
         - { id: gpt-5.6-sol, name: GPT-5.6 Sol, contextWindow: 272000, inputModalities: [text, image] }
@@ -166,6 +175,36 @@ tools+effort 的自动改道。
           - { provider: grok, model: grok-4.6 }
 ```
 
+### 等待限流窗口
+
+订阅套餐天然是按限流窗口计费的 —— 5 小时会话窗口、周窗口，部分套餐还有按模型的周窗口 —— 所以 429 并不是终点：窗口会在 provider 自己告知的时刻重开。每条路由从自己的 429 里读出这个时刻，把它变成该账号在模型池里的冷却时长（见上文「模型池」），而不是固定猜测的 5 分钟。
+
+只有能指明「是哪个窗口拒绝了这次请求」的信号才会被读取：Anthropic 的 `anthropic-ratelimit-unified-reset`、Codex 在 `usage_limit_reached` 上给出的秒数、xAI 在错误体里给出的延迟，或通用的 `retry-after`。各分桶的滚动快照（`anthropic-ratelimit-{requests,tokens,…}-reset`、`x-codex-*-reset-after-seconds`、`x-ratelimit-reset-*`）每个响应上都有，说不出是哪个桶拒绝的 —— 其中最早的那个往往正是还有余量的桶 —— 所以只带这些的 429 会通过插件的告警回调打印出相关 header 与响应体开头，而不是照着猜测把本轮(或池冷却)挂起。
+
+读取只发生在 429 上。其他失败仍走各自的短本地退避:同样这些 header 也会出现在瞬时 500 上,在那里照办等于为一次一秒就恢复的过载把本轮挂满整个窗口。
+
+有模型池时，真正在做等待这件事的其实是账号 failover：某个账号 429 了就按它自己披露的重开时刻冷却下来，请求立刻切到同 provider 的下一个账号 —— 不等待，也不丢本轮对话。只有**整个池**（所有账号）都在冷却时，adapter 才会上报一个 `RATE_LIMIT`，携带池里**最早**的重开时刻作为应等待的时长。单账号（没配池，或该 provider 只登了一个号）时，同样的披露时刻会被直接上报。
+
+真正执行这段等待的是 [`@deepseek-ai/dsh-llm-retry`](https://www.npmjs.com/package/@deepseek-ai/dsh-llm-retry)，四条路由的重试策略都是为它写的：把它加进编排，否则不会有任何等待，关闭的窗口仍旧直接让本轮失败（如果池里还有别的健康账号，会先 failover 过去）。Copilot 当前使用通用的 `retry-after` 信号；GitHub 未识别的限流 header 会通过插件告警回调暴露出来，后续再添加 provider 专用解析器。
+
+```yaml
+- name: '@deepseek-ai/dsh-llm-retry'
+```
+
+```yaml
+- name: dsh-plugin-subscriptions
+  config:
+    rateLimit:
+      wait: true            # 默认；false 恢复此前秒级的行为
+      maxWaitMs: 21600000   # 6 小时 —— 留有余量地覆盖 5 小时会话窗口
+```
+
+重开时刻超过 `maxWaitMs`(比如几天后才重置的周窗口,或者整个池的冷却时间超过这个上限)会立即失败并带上重开时刻,而不是把会话挂上好几天。`wait: false` 则只保留本地退避。
+
+四条路由共用 Claude Code 自己的重试形状:首次尝试之后重试 10 次,从 1 秒开始退避,带 20% 抖动,上限 60 秒。这些都是面向消费者的订阅端点,过载时按突发丢流量,而 dsh-llm 默认值(5 次重试,500 毫秒到 10 秒)约 15 秒就放弃,对这种场景偏短。没有给出重开时刻的 429 现在会本地重试约 17 分钟才让本轮失败 —— `wait: false` 下约 5 分钟,那时 60 秒上限才真正生效。
+
+一个需要知道的取舍:延迟上限与这份本地退避共用,调高 `maxWaitMs` 同时也抬高了无关瞬时失败(`TRANSPORT`、`SERVER`、`TIMEOUT`)在有限重试预算耗尽前的退避时长 —— 第 10 次重试最长会从 60 秒上限变成 512 秒。
+
 ## 代理
 
 所有订阅相关请求 —— token 交换、模型 API 流式调用、用量查询、模型目录发现,以及 `x_search` / `image_generate` / `video_generate` 工具 —— 都可以通过 HTTP(S) 代理发出。在 **设置 → 订阅 → 代理 → 配置…** 中设置:勾选启用,填写代理地址(`http://127.0.0.1:7890`)、可选用户名/密码,以及可选的逗号分隔绕过列表(保持直连的主机名,如 `127.0.0.1`、`localhost`、`*.example.com`)。密码保存在 `~/.dsh/plugins/subscriptions/proxy.json`(权限 0600),不会回传给浏览器;「测试」按钮会用当前配置探测一次端点,显示 HTTP 状态码与耗时。
@@ -188,7 +227,7 @@ pnpm test      # 编译后跑 node --test 单测
 
 - `src/index.ts` —— 插件入口:配置 schema、adapter 注册、登录态变更通告、RPC 接线
 - `src/auth/` —— PKCE/JWT 工具、token 存储、OAuth 流程引擎(临时本地回调服务)、Claude Code 凭据读取器(Keychain/文件)、`/subscriptions-auth` RPC 通道
-- `src/providers/` —— 各 provider 的 OAuth 常量/换发/刷新 + `LlmAdapter` 实现,多账号 token 管理(`accounts.ts`),以及模型池(`pool.ts` + `pool-health.ts` / `pool-usage.ts` / `pool-family.ts`)
+- `src/providers/` —— 各 provider 的 OAuth 常量/换发/刷新 + `LlmAdapter` 实现，多账号 token 管理（`accounts.ts`），模型池（`pool.ts` + `pool-health.ts` / `pool-usage.ts` / `pool-family.ts`），以及 `rate-limit.ts`（限流重开时刻解析 + 重试策略）
 - `src/translate/` —— dsh `Message[]` 与 OpenAI Responses / Anthropic Messages 格式互转,SSE → `StreamChunk`
 - `src/tools/` —— `x_search`、`image_generate` 与 `video_generate`
 - `src/client/` —— 设置 → 订阅页面(浏览器面,中英文,跟随明暗主题)

package/lib/auth/rpc.d.ts

@@ -73,6 +73,34 @@ export interface ProxyConfigController {
         proxy?: ProxyDraft;
     }): Promise<ProxyTestResult>;
 }
+/** One model's default-effort picker state, as rendered by the Settings page. */
+export interface ModelDefaultView {
+    /** Wire model id. */
+    id: string;
+    /** Human-readable display name. */
+    name: string;
+    /** Advertised effort levels, in catalog order (empty when the model has no reasoning). */
+    efforts: {
+        id: string;
+        name: string;
+    }[];
+    /** The user-configured default effort, when set. */
+    configured?: string;
+}
+/** One provider's default-effort picker state. */
+export interface ModelDefaultsCatalog {
+    /** The subscription provider route. */
+    provider: ProviderId;
+    /** Models the picker can configure, in catalog order. */
+    models: ModelDefaultView[];
+}
+/** Default-effort picker operations behind the `modelDefaults/setModelDefault` endpoints. */
+export interface ModelDefaultsController {
+    /** Per-provider picker state for the Settings page. */
+    catalog(): Promise<ModelDefaultsCatalog[]>;
+    /** Set one model's configured default effort; undefined clears the override. */
+    set(provider: ProviderId, model: string, effort: string | undefined): Promise<void>;
+}
 /** Provider-agnostic auth operations the RPC handler delegates to. */
 export interface AuthController {
     /** Current status of one provider. */
@@ -105,10 +133,12 @@ export interface AuthController {
     /**
      * Current subscription usage of one account.
      * @param signal - caller cancellation from the RPC transport.
+     * @param force - bypass a fresh cached snapshot for an honest re-check
+     *   (the manual Refresh button); a live failure cooldown still applies.
      * @returns `{ supported: false }` when the provider has no usage endpoint.
      * @throws when logged out or the usage lookup fails.
      */
-    usage(provider: ProviderId, account: string, signal: AbortSignal): Promise<ProviderUsage>;
+    usage(provider: ProviderId, account: string, signal: AbortSignal, force?: boolean): Promise<ProviderUsage>;
     /**
      * Read one image attachment's bytes for inline display.
      * @param ref - the full durable reference (`readImage` verifies against it).
@@ -127,11 +157,15 @@ export interface AuthController {
      */
     readVideo(name: string, signal: AbortSignal): Promise<VideoBytesResult>;
 }
+/** Payload carried no usable provider id — an RPC client bug, not a server failure. */
+export declare class BadRequest extends Error {
+}
 /**
  * Register the `/subscriptions-auth` RPC channel when a host connection exists.
  * @param ctx - the plugin context (headless profiles have no `connection`).
  * @param controller - the auth operations backing the endpoints.
  * @param speed - the per-session speed-tier state backing the Speed toggle.
  * @param proxy - optional proxy-config controller backing `proxyGet`/`proxySet`/`proxyTest`.
+ * @param modelDefaults - optional per-model default-effort state backing `modelDefaults`/`setModelDefault`.
  */
-export declare function registerAuthRpc(ctx: Context, controller: AuthController, speed: SpeedController, proxy?: ProxyConfigController | undefined): void;
+export declare function registerAuthRpc(ctx: Context, controller: AuthController, speed: SpeedController, proxy?: ProxyConfigController | undefined, modelDefaults?: ModelDefaultsController | undefined): void;

package/lib/auth/rpc.js

@@ -13,7 +13,7 @@ const IMAGE_MEDIA_TYPES = ['image/png', 'image/jpeg', 'image/webp', 'image/gif']
 /** Bare MP4 file names the `video` endpoint accepts (no path separators). */
 const VIDEO_NAME_PATTERN = /^[\w.-]+\.mp4$/;
 /** Payload carried no usable provider id — an RPC client bug, not a server failure. */
-class BadRequest extends Error {
+export class BadRequest extends Error {
 }
 function ok(value) {
     return { ok: true, value };
@@ -42,6 +42,24 @@ function readString(payload, field) {
     }
     return value;
 }
+/** Validate the `setModelDefault` endpoint's payload. */
+function readModelDefaultInput(payload) {
+    const provider = readProvider(payload);
+    const model = readString(payload, 'model');
+    const record = payload;
+    let effort;
+    if (record.effort !== undefined) {
+        if (typeof record.effort !== 'string' || record.effort.length === 0) {
+            throw new BadRequest('payload.effort must be a non-empty string when present');
+        }
+        effort = record.effort;
+    }
+    return {
+        provider,
+        model,
+        ...(effort === undefined ? {} : { effort }),
+    };
+}
 /** Validate the optional Claude login method. */
 function readLoginMethod(payload, provider) {
     const method = payload.method;
@@ -108,6 +126,17 @@ function readVideoName(payload) {
     }
     return name;
 }
+/** Validate the `usage` endpoint's optional force flag. */
+function readForce(payload) {
+    if (typeof payload !== 'object' || payload === null)
+        return false;
+    const force = payload.force;
+    if (force === undefined)
+        return false;
+    if (typeof force !== 'boolean')
+        throw new BadRequest('payload.force must be a boolean when present');
+    return force;
+}
 /** Validate the session id both speed endpoints carry. */
 function readSessionId(payload) {
     if (typeof payload !== 'object' || payload === null)
@@ -196,7 +225,7 @@ function readProxyTestPayload(payload) {
         ...proxy === undefined ? {} : { proxy },
     };
 }
-async function dispatch(controller, speed, proxy, endpoint, payload, signal) {
+async function dispatch(controller, speed, proxy, modelDefaults, endpoint, payload, signal) {
     switch (endpoint) {
         case 'status': {
             const entries = await Promise.all(PROVIDER_IDS.map(async (provider) => [provider, await controller.status(provider)]));
@@ -226,7 +255,7 @@ async function dispatch(controller, speed, proxy, endpoint, payload, signal) {
         }
         case 'usage': {
             const provider = readProvider(payload);
-            return ok(await controller.usage(provider, readString(payload, 'account'), signal));
+            return ok(await controller.usage(provider, readString(payload, 'account'), signal, readForce(payload)));
         }
         case 'image':
             return ok(await controller.readImage(readImageRef(payload), signal));
@@ -249,6 +278,18 @@ async function dispatch(controller, speed, proxy, endpoint, payload, signal) {
             if (proxy === undefined)
                 throw new BadRequest('proxy configuration is unavailable');
             return ok(await proxy.test(readProxyTestPayload(payload)));
+        case 'modelDefaults':
+            if (modelDefaults === undefined)
+                throw new BadRequest('model defaults are unavailable');
+            return ok(await modelDefaults.catalog());
+        case 'setModelDefault':
+            if (modelDefaults === undefined)
+                throw new BadRequest('model defaults are unavailable');
+            {
+                const input = readModelDefaultInput(payload);
+                await modelDefaults.set(input.provider, input.model, input.effort);
+            }
+            return ok({ ok: true });
         default:
             throw new BadRequest(`unknown /subscriptions-auth endpoint "${endpoint}"`);
     }
@@ -259,8 +300,9 @@ async function dispatch(controller, speed, proxy, endpoint, payload, signal) {
  * @param controller - the auth operations backing the endpoints.
  * @param speed - the per-session speed-tier state backing the Speed toggle.
  * @param proxy - optional proxy-config controller backing `proxyGet`/`proxySet`/`proxyTest`.
+ * @param modelDefaults - optional per-model default-effort state backing `modelDefaults`/`setModelDefault`.
  */
-export function registerAuthRpc(ctx, controller, speed, proxy = undefined) {
+export function registerAuthRpc(ctx, controller, speed, proxy = undefined, modelDefaults = undefined) {
     // `connection` is not in this plugin's inject list (headless compositions
     // lack it), so its startup order is unconstrained: defer registration until
     // the service exists instead of probing once at apply time.
@@ -268,7 +310,7 @@ export function registerAuthRpc(ctx, controller, speed, proxy = undefined) {
         const connection = ctx.get('connection');
         ctx.effect(() => connection.rpc.handle(SUBSCRIPTIONS_AUTH_CHANNEL, async (endpoint, payload, signal) => {
             try {
-                return await dispatch(controller, speed, proxy, endpoint, payload, signal);
+                return await dispatch(controller, speed, proxy, modelDefaults, endpoint, payload, signal);
             }
             catch (error) {
                 return failure(error);

package/lib/client/ImageGenerateToolview.d.ts

@@ -1,5 +1,5 @@
 import type { ConnectionHandle } from '@deepseek-ai/dsh-api-remotes/client';
-import type { ToolCallBlock } from '@deepseek-ai/dsh-client-runtime/client';
+import type { ToolCallBlock } from '@deepseek-ai/dsh-client-ui-conversation/client';
 import type { ImageLoader } from './ImageGallery.js';
 import type { SubscriptionsKey } from './locales.js';
 /** Mirror of ui-tool's ToolCallOwnerProps (see the module header). */

package/lib/client/SpeedSelect.d.ts

@@ -12,6 +12,25 @@ export interface SpeedSelectState {
     visible: boolean;
     tier: SpeedTier;
 }
+/**
+ * Minimal structural face of ui-model-selection's `ctx.modelDirectories`
+ * service (the sanctioned cross-plugin channel: cordis services, not value
+ * imports — same mirroring discipline as ToolCallOwnerProps). Both dsh lines
+ * ship it with this shape; it replaces rc.2's `connection.api.sessions.models`
+ * read, which the 0.1.2-alpha removed along with the whole `.api` face.
+ */
+export interface ModelDirectoriesLike {
+    /** Resolve one session's shared model directory (throws for unknown sessions). */
+    directoryFor(sessionId: string): {
+        /** Load the directory; `current` is the session's effective model selection. */
+        load(): Promise<{
+            current: {
+                provider: string;
+                model: string;
+            } | null;
+        }>;
+    };
+}
 /** Injected dependencies of {@link SpeedSelect} (slot `inject`, session-bound). */
 export interface SpeedSelectInjected {
     /** Load the session's speed state; `visible` false keeps the control hidden. */
@@ -32,9 +51,13 @@ export type SpeedSelectProps = PropsRuntime<'conversation.input.right'> & Partia
  * known state, so a transient failure never locks the toggle away.
  *
  * `sessionId` is a plain string: slot and command contexts brand it through
- * different dsh-session copies, and only the API-client boundary needs one.
+ * different dsh-session copies, and only the service boundary needs one.
+ *
+ * `models` resolves lazily per call: the ui-model-selection service may
+ * register after this plugin applies, and a shell without it (no model seat
+ * at all) simply keeps the toggle hidden.
  */
-export declare function createSpeedLoader(connection: ConnectionHandle, sessionId: string): SpeedSelectInjected['loadSpeed'];
+export declare function createSpeedLoader(connection: ConnectionHandle, models: () => ModelDirectoriesLike | undefined, sessionId: string): SpeedSelectInjected['loadSpeed'];
 /** The `setSpeed` half of the inject face: boolean outcome for the component's busy state. */
 export declare function createSpeedSetter(connection: ConnectionHandle, sessionId: string): SpeedSelectInjected['setSpeed'];
 /**

package/lib/client/SpeedSelect.js

@@ -22,15 +22,19 @@ import { en } from './locales.js';
  * known state, so a transient failure never locks the toggle away.
  *
  * `sessionId` is a plain string: slot and command contexts brand it through
- * different dsh-session copies, and only the API-client boundary needs one.
+ * different dsh-session copies, and only the service boundary needs one.
+ *
+ * `models` resolves lazily per call: the ui-model-selection service may
+ * register after this plugin applies, and a shell without it (no model seat
+ * at all) simply keeps the toggle hidden.
  */
-export function createSpeedLoader(connection, sessionId) {
+export function createSpeedLoader(connection, models, sessionId) {
     return async () => {
         const state = await callSubscriptionsAuth(connection.rpc, 'speed', { sessionId });
-        const { result } = await connection.api.sessions.models({ sessionId: sessionId });
-        if (!result.ok)
-            throw new Error(`session.models failed: ${result.error.code}: ${result.error.message}`);
-        const current = result.value.current;
+        const directories = models();
+        if (directories === undefined)
+            return { visible: false, tier: state.tier };
+        const { current } = await directories.directoryFor(sessionId).load();
         const visible = current !== null && current.provider === 'codex'
             && state.fastModels.includes(current.model);
         return { visible, tier: state.tier };

package/lib/client/SubscriptionsSection.d.ts

@@ -29,6 +29,23 @@ export interface ProviderUsage {
     windows?: UsageWindow[];
     plan?: string;
 }
+/** One model's default-effort picker state as answered by `modelDefaults`. */
+export interface ModelDefaultView {
+    id: string;
+    name: string;
+    /** Advertised effort levels, in catalog order (empty when the model has no reasoning). */
+    efforts: {
+        id: string;
+        name: string;
+    }[];
+    /** The user-configured default effort, when set. */
+    configured?: string;
+}
+/** `modelDefaults` endpoint value: one provider's picker state. */
+export interface ModelDefaultsCatalog {
+    provider: SubscriptionProvider;
+    models: ModelDefaultView[];
+}
 /** `proxyGet` endpoint value: the node half owns this shape (no secrets). */
 export interface ProxyConfigView {
     enabled: boolean;
@@ -67,6 +84,63 @@ export type SubscriptionsSectionProps = Partial<SubscriptionsSectionInjected>;
  * @returns the success value, cast by the caller to the endpoint's shape.
  */
 export declare function callSubscriptionsAuth<T>(rpc: ConnectionHandle['rpc'], endpoint: string, payload: unknown): Promise<T>;
+/** What one provider's collapsible default-effort section renders. */
+export interface ModelDefaultsView {
+    /** Models with reasoning levels, after the name filter — one row each. */
+    shown: ModelDefaultView[];
+    /** Models with reasoning levels before filtering (the header total). */
+    total: number;
+    /** How many of those carry a user override (the header count). */
+    overridden: number;
+    /** Models without reasoning levels: one count line, never a row each. */
+    withoutEfforts: number;
+    /** Whether the list is long enough to deserve a filter box. */
+    showFilter: boolean;
+}
+/**
+ * Derive one provider's default-effort section from its catalog and filter.
+ * Pure so the collapsed-header counts and the filter stay testable without a
+ * DOM: rows come only from models that advertise levels, the count of the rest
+ * rides as one line, and the filter matches display name or model id.
+ * @param models - the provider's catalog models, or undefined while loading.
+ * @param filter - the raw filter input (trimmed and lowercased here).
+ * @returns the section's rows and header counts.
+ */
+export declare function deriveModelDefaultsView(models: readonly ModelDefaultView[] | undefined, filter: string): ModelDefaultsView;
+/** Inputs of the default-effort fetch decision (see {@link shouldFetchModelDefaults}). */
+export interface ModelDefaultsFetchInput {
+    /** Providers that currently have at least one account. */
+    loggedIn: readonly SubscriptionProvider[];
+    /** Providers whose disclosure is open. */
+    open: readonly SubscriptionProvider[];
+    /** The account signature the last completed fetch was answered for. */
+    loadedFor: string | undefined;
+    /** The account signature of the current status snapshot. */
+    signature: string;
+    /** Whether the last attempt failed (a failure latches until Retry). */
+    failed: boolean;
+}
+/**
+ * Whether the default-effort catalog needs (re)fetching.
+ *
+ * Fetching is gated on an *attempt* signature rather than on the payload
+ * being empty: an empty answer is a legitimate result (a narrowed
+ * `config.providers`, or a catalog that is momentarily unavailable), and
+ * treating it as "not loaded yet" re-ran this effect forever. The signature
+ * also covers the accounts, so logging a second provider in refetches
+ * instead of leaving that card on the previous answer.
+ * @param input - the decision inputs.
+ * @returns true when the caller should start a fetch.
+ */
+export declare function shouldFetchModelDefaults(input: ModelDefaultsFetchInput): boolean;
+/**
+ * Stable signature of the accounts a catalog answer depends on. A change
+ * means a previous answer is stale (an account arrived or left), so the next
+ * open disclosure refetches.
+ * @param statuses - the per-provider status snapshot.
+ * @returns a signature string, stable across renders with equal accounts.
+ */
+export declare function modelDefaultsSignature(statuses: Partial<Record<SubscriptionProvider, ProviderStatus>>): string;
 /**
  * The Subscriptions settings page component.
  * @param props - the slot inject face ({@link SubscriptionsSectionInjected}).