dsh-connect-minimaxcode 0.6.9 → 0.7.0

package/README.en.md

@@ -419,8 +419,46 @@ The OAuth token is valid for about an hour and is refreshed automatically by the
 - **The context window is declared as the gateway's real ceiling (1,000,000), not the 512,000 in the catalog.** Upstream's `limit.context` is the *default* window and the billing tier boundary (input above 512k costs more); the largest entry of `context_window_options` is the ceiling the gateway enforces. Measured on 2026-10-25: 946,206 tokens were served normally, 1,050,000 were refused (`invalid params, context window exceeds limit (2013)`). Declaring 512,000 meant every turn of a long conversation was reported as `pi-ai detected context overflow` — while the model had answered perfectly well and the reply was thrown away.
 - **The device code flow needs `account.minimax.cn` to be reachable**, and the browser that authorizes it has to be able to sign in to a MiniMax account. On some restricted networks the authorization page cannot be opened.
 
+## How to read the version number
+
+The plugin follows semantic versioning, and **each level means the same thing** — so the version number says what to expect:
+
+| Version | What it means |
+| --- | --- |
+| **patch** (x.y.**z**) | a defect is fixed. **No new configuration key, no interface change.** The existing surface and behaviour stay; one thing that was wrong is now right. |
+| **minor** (x.**y**.0) | a **user-visible** capability is added, or the shape of an existing message changes. **No interface change**; the meaning of the existing configuration keys is unchanged. |
+| **major** (**x**.0.0) | a breaking change: the meaning of an existing configuration key changes, the surface is rearranged enough to need re-learning, or the host interface it depends on has moved on. |
+
+Every entry in the changelog opens with why it is that level, and with **what this release deliberately did not do** — the boundaries are worth knowing more than the features, so they come first.
 ## Changelog
 
+### 0.7.0 (2026-11-15)
+
+> The version is **minor**: a new "Diagnostics" section and a switch for showing the balance in the composer, and a different shape for the message a failed generation shows. **No interface change**; the meaning of the existing configuration keys is unchanged.
+
+#### Added
+
+- **A "Diagnostics" section on the plugin page**: a read-only list of facts — the plugin version, the region, the upstream hosts, how the plugin is signed in, where the model catalog came from, which pieces of the host it found (eight of them), and **the upstream's own words about its most recent failure**. The one reason it exists is that **it can be copied into an issue as it stands**: there is no control in it that changes anything. The host's own version is **not** in it, because the host does not hand its version to a plugin — a line that had to be guessed would be worse than no line.
+- **A "show the credit balance in the composer" switch**: on by default. Turning it off hides the balance in the pill and changes nothing else; it can be turned back on at any time.
+
+#### Changed
+
+- **A failed generation now says three things instead of one**: ① what to do (by the kind of failure); ② **that this request may already have been charged for** (when a video task was submitted and could not be read back); ③ **the upstream's own words**, collapsed, quoted rather than paraphrased.
+- **Failures are classified** into `credentials` / `parameters` / `subscription` / `quota` / `rate-limited` / `upstream` / `local`, each with its own remedy. The classification reads the failure's *shape* (the HTTP status and the wording) rather than its code — a code is a number some other system chose, and the day it is renamed or withdrawn, a classifier keyed on it would quietly stop matching, while one keyed on what the failure *is* keeps working.
+
+#### Deliberately not done
+
+- **The session-title requests are not diverted to a lighter model.** The host sends one per new session, and it goes to the main model. Measured (2026-11-15): **our upstream catalog holds two models** (`MiniMax-M3` and `MiniMax-M3.1-Flash`, both with a 512K context, a 128K output and reasoning), there is **no lighter one**, and the catalog carries **no price field** — so there is no way to tell what diverting them would save. A change with no measured evidence behind it is not made.
+- **No cooldown for the failures that spent nothing.** Only the ones where the upstream may have accepted the work, and may have charged for it, are held back; a bad parameter, a missing sign-in and a request refused locally cost nothing and may be retried at once.
+- **No host version in the diagnostics.** The host does not offer its version to a plugin; that line could only be guessed.
+- **No "drop the tools for this model" fallback.** Letting a model quietly lose every tool is harder to notice than an error.
+
+#### Testing
+
+- New: `tests/failure.spec.ts` (9), `tests/generation-cost.spec.ts` (7), `tests/failure-wording.spec.ts` (5), `tests/diagnostics.spec.ts` (6), `tests/control-layers.spec.ts` (6).
+- **Mutation checks**: every fix in this release was reverted on its own to confirm the matching case turns red. All seven mutations of the classifier and all four of the cost distinction were caught. One mutation of the cost distinction **survived at first** — the case exercised the HTTP-failure branch while the mutation changed the "the answer was not JSON" one. Adding a case for that road caught it. It is exactly what "the test passed but was not proving what it claimed" looks like.
+- The protocol findings moved into `docs/` (published with the package): H3 generation, the account endpoints, the credentials and the error taxonomy, each fact carrying the date it was measured.
+
 ### 0.6.9 (2026-11-13)
 
 - **The oldest supported DSH moved from `0.2.1-rc.2` down to `0.1.6-alpha.2`.** The old floor was a conservative value, not a technical one. This release searched the host packages' published history version by version and, for every host capability the plugin uses, found the release it first appeared in.

package/README.md

@@ -430,8 +430,46 @@ OAuth 令牌有效期约 1 小时，由客户端自动续期。插件**只在自
 - **上下文窗口按网关的真实上限声明（1,000,000），不是目录里的 512,000**。上游 `limit.context` 是**默认档位与计费分界**（输入超过 512k 的部分按更高倍率计费），`context_window_options` 里最大的一档才是网关执行的硬上限。实测（2026-10-25）：946,206 tokens 正常受理，1,050,000 被拒（`invalid params, context window exceeds limit (2013)`）。此前按 512,000 声明，长会话一旦过线就**每一轮**都被判成「上下文溢出」，模型其实答得好好的，回复却被丢掉（`pi-ai detected context overflow`）。
 - **设备码流需要能访问 `account.minimax.cn`**，且授权时要在浏览器里能登录 MiniMax 账号。某些内网或受限网络下打不开授权页。
 
+## 版本号怎么读
+
+本插件的版本号遵循语义化版本，**而且每一级对应的事情是固定的** —— 读版本号就能预知能发生什么：
+
+| 版本号 | 意味着什么 |
+| --- | --- |
+| **patch**（x.y.**z**） | 修一处缺陷。**无新增配置项、无接口变化**。已有的界面与行为不变，只是某处原来不对。 |
+| **minor**（x.**y**.0） | 新增一项**用户可见**的能力，或改变已有提示的形状。**无接口变化**，既有配置键的含义不变。 |
+| **major**（**x**.0.0） | 破坏性变化：既有配置键的含义改变、界面重排到需要重新适应，或依赖的宿主接口换代。 |
+
+更新记录里的每一版开头都写着这一版为什么是该级别，以及**这一版刻意没做什么** —— 边界比功能更值得知道，所以它写在了前面。
 ## 更新记录
 
+### 0.7.0（2026-11-15）
+
+> 版本号是 **minor**：新增「诊断信息」分栏与「在输入框显示余额」开关，并改变生成失败时的提示形状。**无接口变化**，既有配置键的含义不变。
+
+#### 新增
+
+- **插件页新增「诊断信息」分栏**：只读事实表 —— 插件版本、区域、上游地址、登录来源、模型目录来源、宿主提供了哪几块能力（八项）、以及**上游最近一次错误的原文**。这一栏存在的唯一理由是**能被整段复制进 issue**：里面没有任何会改设置的控件。宿主的版本号**不在其中**，因为宿主没有把它交给插件 —— 一个要靠猜的行比没有这一行更糟。
+- **「在对话输入框显示积分余额」开关**：默认开。关掉即隐藏胶囊里的余额，积分与其它一切不受影响，随时可以再打开。
+
+#### 改变
+
+- **生成失败时的提示从一句话变成三件事**：① 该做什么（按失败性质分类）；② **本次可能已被上游计费**（视频任务提交后读不回来时）；③ **上游的原文**（折叠显示，原样引用不转述）。
+- **失败按性质分类**：`credentials` / `parameters` / `subscription` / `quota` / `rate-limited` / `upstream` / `local` 七类，每类各有各的建议。分类**按失败的形状**（HTTP 状态与措辞）而不是按错误码 —— 错误码是别的系统取的号，它改名或撤销那天，按号分类的代码会安静地不再匹配，而按「失败是什么」分类不会。
+
+#### 刻意没做
+
+- **没有把会话标题请求改到轻量模型**。宿主每个新会话会发一次标题请求，走的是主模型。实测（2026-11-15）：**我们的上游目录里只有两个模型**（`MiniMax-M3` 与 `MiniMax-M3.1-Flash`，同为 512K 上下文 / 128K 输出 / 推理模型），**没有更轻的模型**，而且目录里**没有价格字段** —— 无从判断改过去能省多少。没有实测证据支撑的改动不做。
+- **没有给额度窗口之外的失败加冷却**。只给「上游可能已经受理、可能已计费」的那一类加；「参数错、没登录、本地就拒了」这类一分钱没花的失败**不加冷却**，改完立刻可以重试。
+- **诊断栏里没有宿主版本号**。宿主没有向插件提供它的版本；那一行只能靠猜。
+- **没有做「按模型摘除工具」的降级**。让模型静默失去全部工具能力，比报错更难被发现。
+
+#### 测试
+
+- 新增 `tests/failure.spec.ts`（9）、`tests/generation-cost.spec.ts`（7）、`tests/failure-wording.spec.ts`（5）、`tests/diagnostics.spec.ts`（6）、`tests/control-layers.spec.ts`（6）。
+- **变异验证**：本轮的每一处修复都单独还原过，确认对应用例会转红。错误分类器的 7 个变异、扣费区分的 4 个变异，全部被抓到。其中「视频任务读回执失败是否算已扣费」这一条**最初变异存活了** —— 用例走的是 HTTP 失败分支，而变异改的是「响应体不是 JSON」那条路。补上那条路的用例之后，变异被抓住。这正是「测试通过了但证明的不是它声称的东西」的样子。
+- 协议取证搬进 `docs/`（随包发布）：H3 生成、账户接口、凭据、错误分类四篇，每条事实都带着测量日期。
+
 ### 0.6.9（2026-11-13）
 
 - **最低支持的 DSH 版本从 `0.2.1-rc.2` 降到 `0.1.6-alpha.2`**。原来的下限是保守取值，不是技术上的。这一版把宿主各包的发布历史逐版本查了一遍，对每个插件用到的宿主能力，核出它最早出现在宿主包的哪个版本里。

package/docs/ACCOUNT-ENDPOINTS.md

@@ -0,0 +1,118 @@
+# The account endpoints
+
+The upstream surfaces this plugin reads about the account, as measured on
+**2026-11-12** (and re-measured on **2026-11-15** against a subscribed
+account) in the **China** region.
+
+## The membership answer
+
+```
+POST https://agent.minimax.cn/matrix/api/v1/commerce/get_membership_info
+Authorization: Bearer <the desktop app's OAuth token>
+Content-Type: application/json
+Body: {}
+```
+
+The answer is the one place several facts arrive together:
+
+| Field | Meaning |
+| --- | --- |
+| `op_credit_summary.total_remaining_amount` | the balance, free plus purchased |
+| `op_credit_summary.purchased_remaining_amount` | the purchased part |
+| `op_credit_summary.free_remaining_amount` | the granted part |
+| `has_token_plan` | whether the account holds a plan |
+| `token_plan_tier` | the plan's name, e.g. `Go` |
+| `token_plan_expires_at` | when the plan ends, in milliseconds |
+| `subscription_type` | `mplan` once a plan is held, `none` before |
+| `opcredit_balance`, `total_remains_credit` | the older, flat view |
+
+**The flat fields are a legacy view.** On an account that has migrated to the
+credit pool they read zero even though credits remain, so the plugin uses
+them only when the summary is absent altogether.
+
+**A plan's tier is the upstream's own value.** `token_plan_tier` said `Go`
+for the account measured here; another plan would say its own name. Only an
+answer without that field falls back to a generic label.
+
+## The plan's limit windows
+
+```
+GET https://api.minimax.cn/v1/token_plan/remains
+Authorization: Bearer <the open-platform key>
+```
+
+**The field names and their meaning changed.** Before a plan was held the
+answer carried `current_interval_used_percent` and
+`current_weekly_used_percent` as strings (`"19%"`). With a plan it carries
+`current_interval_remaining_percent` and `current_weekly_remaining_percent`
+as plain numbers (`90`) — the *remaining* share, under a name that says so.
+
+Both shapes are accepted, and what leaves the plugin is always the share
+**used**: 92% remaining is 8% used. The window length is taken from the
+answer's own edges rather than from the plan's terms, because the terms have
+changed before: the measured answer is a five-hour window and a 168-hour one.
+
+A window the upstream marks as unlimited (`current_*_status` of 3) carries no
+allowance to be a percentage of, so it produces no window at all.
+
+**An account without a plan gets `2062 no active token plan subscription`**
+rather than an answer. That is the difference between "no windows" and "the
+read failed", and the plugin tells them apart.
+
+## The credit ledger
+
+```
+GET https://agent.minimax.cn/minimax-cloud/api/v1/credit/details?page_number=1&page_size=20
+```
+
+The answer's `details[]` carry `expire_at_ms` and the remaining amount. The
+upstream's lots expire **day by day, spread over thirty-odd days**, so the
+plugin's "expiring soon" window is a display choice, not something the
+upstream states.
+
+The credit-package summary lives at:
+
+```
+GET https://www.minimaxi.com/backend/account/token_plan_credit?business=Agent&device_platform=desktop
+```
+
+whose answer carries `total_credits`, `used_credits`, `remaining_credits`,
+`credit_packages_details[]` and the `balance_breakdown` buckets.
+
+## The usage profile
+
+```
+GET https://www.minimaxi.com/backend/account/token_plan/usage_summary?token_type=5&heatmap_days=365&business=Agent&device_platform=desktop
+```
+
+The answer carries `total_days`, `total_token_consumed`, `usage_ranking_percent`,
+`most_active_day`, `active_days`, `current_consecutive_days`, and per-day
+`date_model_usage[]` with a per-model breakdown (including
+`cache_hit_percent`).
+
+## What the catalog does not carry
+
+**No promotion-shaped fields.** A search of the whole catalog answer for
+`modelPromotions`, `promotions`, `activities`, `discount` and `free_trial`
+found nothing. The plugin therefore draws no activity badge: a badge would
+have to be invented, and an invented badge is worse than no badge.
+
+**No price fields.** The model catalog carries the models and their limits,
+but nothing about what a request costs, so the plugin cannot say what a
+title request or a long turn spent.
+
+## The model catalog
+
+```
+GET https://agent.minimax.cn/mavis/api/v1/models
+Authorization: Bearer <the desktop app's OAuth token>
+```
+
+The answer carries `providers[].config.models`, each with `name`,
+`attachment`, `reasoning`, `limit.context`, `limit.output` and `modalities`.
+
+At the time of measurement the catalog carried **two** models,
+`MiniMax-M3` and `MiniMax-M3.1-Flash`, both with a 512,000-token context and
+a 128,000-token output limit. There was **no lighter model** in it — which
+is why the plugin does not divert the host's session-title requests
+elsewhere; see the changelog for that entry.

package/docs/CREDENTIALS.md

@@ -0,0 +1,65 @@
+# The credentials, and where they come from
+
+The plugin can be signed in two ways, and they arrive by different paths.
+Which one is in use is what the card reports as its sign-in source.
+
+## The desktop app's login (the usual one)
+
+The MiniMax Code desktop app leaves its login state in a file. The plugin
+reads it and never writes it.
+
+The file's location is probed per platform, and the card lists every path it
+tried and why each one did not work — five distinct reasons, so that the
+commonest misdiagnosis ("the app is not signed in") is not mistaken for
+"the file is somewhere else".
+
+The desktop app's token is what the **model gateway** takes:
+
+```
+POST https://agent.minimax.cn/mavis/api/v1/llm/v1/messages
+Authorization: Bearer <the desktop app's OAuth token>
+```
+
+It is also what the **account endpoints** take — membership, the credit
+ledger, the usage profile, and the credit-package summary that hands out the
+open-platform key.
+
+## The plugin's own login (the fallback)
+
+With no desktop app on the machine, the plugin starts an OAuth device flow
+from the card and keeps its own token under the Harness home. The person
+confirms it in a browser.
+
+That token serves the model gateway and the account endpoints too. The
+**generation** endpoints do not take it — they take the open-platform key,
+which the credit-package summary hands out.
+
+## The open-platform key
+
+```
+GET https://www.minimaxi.com/backend/account/token_plan_credit?business=Agent&device_platform=desktop
+```
+
+The answer carries `api_key`, a `sk-cp-…` value. The plugin keeps it for as
+long as it runs and never writes it to disk.
+
+Passing the OAuth token to the generation endpoints instead is refused with
+`1004 login fail: Please carry the API secret key`.
+
+## The two paths that failed before
+
+Both of these were real, and both are why the plugin reads the account
+endpoints at all:
+
+- **The model gateway read only the legacy JWT.** It now falls back to the
+  desktop app's OAuth credential, and a re-login takes effect without
+  restarting the host.
+- **The credit endpoint was answered with an empty body.** The plugin now
+  reads the documented endpoints, and the answer's own summary.
+
+## What the plugin never does
+
+- It never writes to the desktop app's files.
+- It never prints a token. The plugin's own state file holds the OAuth
+  credential; the open-platform key is held in memory only.
+- It does not start a login of its own unless the card is pressed.

package/docs/ERROR-TAXONOMY.md

@@ -0,0 +1,72 @@
+# How a failure is classified
+
+The plugin turns an upstream refusal into three things a person can act on:
+**what kind of failure it is**, **whether it may already have been charged
+for**, and **the upstream's own words**.
+
+## Why the classification is by shape
+
+The upstream's failures arrive in several shapes: an HTTP status, a business
+code, a sentence, sometimes all three. The obvious thing to key on is the
+code — `2013` means a bad parameter, `2062` means no plan.
+
+**The plugin does not.** It keys on the *shape* of the failure: the HTTP
+status and the wording.
+
+The reason is that a code is a number **some other system chose**. It may be
+renamed, or withdrawn, or reused for something else, and a classifier that
+keyed on it would one day quietly stop matching — the plugin would report
+"something went wrong" for a failure it used to recognise, with no sign
+that anything had changed. A classifier that keyed on the *kind* of failure
+keeps working across renames, and only has to be extended when a genuinely
+new kind appears.
+
+This is the same rule the plugin follows elsewhere: a fact that travels with
+the **data** may be relied on; a fact that travels with another system's
+**code** may not.
+
+## The kinds
+
+| Kind | Recognised by | The remedy |
+| --- | --- | --- |
+| `credentials` | HTTP 401 / 403, or wording about a refused key or a failed sign-in | sign in again |
+| `parameters` | HTTP 400 / 422, or wording about an invalid or unsupported value | change the request |
+| `subscription` | wording about no active plan or subscription | check the plan |
+| `quota` | wording about an insufficient balance or a spent quota | wait, or check the windows |
+| `rate-limited` | HTTP 429, or wording about too many requests | wait |
+| `upstream` | anything else | show the upstream's words and ask for a report |
+| `local` | the request never left the plugin | fix it and try again |
+
+**A failure that is not recognised is not guessed at.** It becomes
+`upstream`, whose remedy is to show the upstream's own words — which is what
+a report needs, and better than a confident wrong answer.
+
+**The wording is checked before the status**, except for the two statuses
+that name a class outright (401/403 and 429). The reason is that a bad
+request can arrive for a reason that is not a bad request: the "no active
+subscription" refusal arrives as HTTP 400, and telling the reader to change
+the parameters would send them looking in the wrong place.
+
+## What it cost
+
+A failure that happened **before** the upstream accepted the work spent
+nothing: a bad parameter, a refused credential, a request the plugin
+refused to send. A retry after fixing something is free, and the plugin says
+so.
+
+A failure that happened **after** the upstream accepted the work — a video
+task that was submitted and then could not be read back — may already have
+been charged for. The plugin says so too, and holds off for a while.
+
+## What the reader sees
+
+Three lines, in this order:
+
+1. **the remedy**, in the host's language;
+2. **a warning when the work may have been charged for**;
+3. **the upstream's own words**, collapsed — they are read when a report is
+   being written, not when the failure happens.
+
+The upstream's words are shown **as they arrived**. A paraphrase would be a
+guess about what the upstream meant, and the guess would be the thing a
+reader would quote back.

package/docs/H3-GENERATION.md

@@ -0,0 +1,109 @@
+# H3 image and video generation
+
+The upstream endpoints this plugin calls to make a picture or a video with
+H3, as measured on **2026-11-12** against the account this plugin was
+developed with, in the **China** region.
+
+Everything here was observed, not read from documentation — the endpoints are
+not documented publicly. Where a measurement could be repeated, it was.
+
+## Credentials
+
+The generation endpoints do **not** take the OAuth bearer the model gateway
+takes. They take the **open-platform key**, which the account's own credit
+endpoint hands out:
+
+```
+GET https://www.minimaxi.com/backend/account/token_plan_credit?business=Agent&device_platform=desktop
+Authorization: Bearer <the desktop app's OAuth token>
+```
+
+The answer carries `api_key` — a `sk-cp-…` value — and the plugin keeps it
+for as long as it runs. Passing the OAuth token instead is refused with
+`1004 login fail: Please carry the API secret key`, which arrives with
+HTTP 200 and a code in the body.
+
+## Images
+
+```
+POST https://api.minimax.cn/v1/images/generations
+Authorization: Bearer <the open-platform key>
+Content-Type: application/json
+```
+
+The request carries `model`, `prompt`, `response_format`, and optionally
+`n`, `aspect_ratio` and `area`.
+
+| Model | Note |
+| --- | --- |
+| `MiniMax-H3-Image` | the default |
+| `MiniMax-H3-Image-Highspeed` | the faster one |
+
+The answer carries `data[]` with either a `url` (valid for **24 hours**) or
+`b64_json`. It also carries `usage.generated_images`, `usage.total_tokens`
+and a `request_id`.
+
+The plugin downloads the bytes while the link is still fresh, because a
+plugin that kept only the link would leave the picture behind.
+
+## Videos
+
+```
+POST https://api.minimax.cn/v2/video_generation
+```
+
+The request carries `model` and a `content[]` array whose entries are
+`{type: 'text'}`, `{type: 'image_url', image_url: {url}, role: 'first_frame' | 'last_frame'}`.
+`duration` is 4–15, `resolution` is `768P` or `2K`, and `ratio` runs from
+`21:9` to `9:16`.
+
+The answer carries a `task_id`; the state is read from:
+
+```
+GET https://api.minimax.cn/v2/query/video_generation/{task_id}
+```
+
+whose answer carries `task.status` (`running`, `succeeded`, and the failure
+spellings), `task.content.url`, `task.resolution`, `task.duration`,
+`task.ratio` and `task.usage.total_seconds`.
+
+The v1 path answers "该模型请使用 /v2/video_generation 接口" — the model moved
+to v2, and the old path says so.
+
+## What a refusal looks like
+
+**A refusal can arrive with HTTP 200.** The body carries `base_resp` with a
+`status_code` that is not zero. Reading only the HTTP status would call
+these a success.
+
+| Code | Meaning, as observed |
+| --- | --- |
+| `1004` | the credential was refused (`login fail`) |
+| `2013` | a parameter was refused; the message names the field |
+| `2062` | `no active token plan subscription` — the account has no plan |
+
+The plugin classifies these by shape, not by number: see
+[ERROR-TAXONOMY.md](ERROR-TAXONOMY.md).
+
+## What was charged
+
+The plugin distinguishes two failures, because the difference decides whether
+a retry is sensible:
+
+- a failure **before** the upstream accepted the work (a bad parameter, a
+  refused credential, a request the plugin refused to send) spent nothing
+  and may be retried at once;
+- a failure **after** the upstream accepted it — a video task that was
+  submitted and then could not be read back — may already have been charged
+  for, and a retry is another task and another charge.
+
+The plugin says which of the two happened, in the same place it shows the
+upstream's own words.
+
+## Not measured
+
+- Whether the 24-hour link can be refreshed rather than re-generated.
+- What a partially completed video task costs.
+- The international region's endpoints on this protocol: the same paths are
+  used against `api.minimaxi.com`, but nothing here was measured against
+  that region.

package/docs/README.md

@@ -0,0 +1,38 @@
+/**
+ * The upstream protocols this plugin speaks, as they were measured.
+ *
+ * Each file records one upstream surface: the endpoints, the shape of what
+ * comes back, and — most importantly — what was actually observed, with the
+ * date it was observed. The upstream is not under this project's control and
+ * may change, so a reader needs to know how old a measurement is before
+ * trusting it.
+ *
+ * Nothing here is read at runtime. These are notes for whoever works on the
+ * plugin next, and for whoever reads a bug report about a field they do not
+ * recognise.
+ */
+
+# Upstream protocols
+
+| Document | What it covers |
+| --- | --- |
+| [H3-GENERATION.md](H3-GENERATION.md) | The H3 image and video endpoints: requests, answers, the accounting, and what a refusal looks like. |
+| [ACCOUNT-ENDPOINTS.md](ACCOUNT-ENDPOINTS.md) | The account endpoints: the membership answer, the credit ledger, the plan's limit windows, and the usage profile. |
+| [CREDENTIALS.md](CREDENTIALS.md) | Where the login state comes from, and the two paths it can arrive by. |
+| [ERROR-TAXONOMY.md](ERROR-TAXONOMY.md) | How a failure is classified, and why the classification is by shape rather than by code. |
+
+## How a measurement is recorded
+
+Every fact here carries the date it was measured and the endpoint it came
+from. Two reasons:
+
+- the upstream answers differently over time — the plan's window fields were
+  renamed and their meaning inverted between one release and the next, and a
+  note without a date would have said the wrong thing for months;
+- a reader who wants to reproduce a measurement needs to know which build and
+  which account it came from, because an account without a plan gets a
+  different answer than one with it.
+
+A measurement that has not been repeated in a long time is treated as a
+hypothesis, not as a fact. The ones below were measured against the account
+this plugin was developed with, in the region named in each document.

package/lib/client.js

@@ -83,6 +83,26 @@
         usageRanking: '用量排名前 {percent}%',
         usageBestDay: '最活跃的一天 {date}',
         planNoSubscription: '未订阅 M Plan（仅积分包），因此没有限额窗口',
+        displayTitle: '显示',
+        showPill: '在对话输入框显示积分余额',
+        diagnosticsTitle: '诊断信息',
+        diagnosticsHint: '这一栏是只读的，可整段复制进 issue，它不会改变任何设置。',
+        diagnosticsPluginVersion: '插件版本',
+        diagnosticsRegion: '区域',
+        diagnosticsHosts: '上游地址',
+        diagnosticsAuthSource: '登录来源',
+        diagnosticsCatalogSource: '模型目录来源',
+        diagnosticsCapability: '宿主能力',
+        diagnosticsLastError: '最近一次上游错误',
+        failureCredentials: '登录凭据被拒绝。请在插件页重新登录 MiniMax Code。',
+        failureParameters: '请求的参数被上游拒绝。请调整提示词或选项后重试。',
+        failureSubscription: '账户没有可用的订阅套餐，因此调用被拒绝。请确认 M Plan 订阅是否生效。',
+        failureQuota: '账户的额度已用尽。请等待额度恢复，或查看套餐的限额窗口。',
+        failureRateLimited: '上游正在限流。请稍后重试。',
+        failureLocal: '请求没有发出，因此没有产生任何消耗。',
+        failureUpstream: '上游拒绝了这次请求。请把下面的原文一并反馈，以便定位。',
+        failureCharged: '本次请求可能已被上游计费，请勿立即重试。',
+        failureUpstreamDetail: '上游原文',
         planGeneric: 'M Plan 订阅',
         planExpires: '{date} 到期',
         generateTitle: '生成',
@@ -169,6 +189,26 @@
         usageRanking: 'Top {percent}% by usage',
         usageBestDay: 'Busiest day {date}',
         planNoSubscription: 'No M Plan subscription (credits only), so there are no usage windows',
+        displayTitle: 'Display',
+        showPill: 'Show the credit balance in the composer',
+        diagnosticsTitle: 'Diagnostics',
+        diagnosticsHint: 'This section is read-only. Copy it into an issue as it stands; it changes nothing.',
+        diagnosticsPluginVersion: 'Plugin version',
+        diagnosticsRegion: 'Region',
+        diagnosticsHosts: 'Upstream hosts',
+        diagnosticsAuthSource: 'Signed in via',
+        diagnosticsCatalogSource: 'Catalog source',
+        diagnosticsCapability: 'Host capabilities',
+        diagnosticsLastError: 'Last upstream error',
+        failureCredentials: 'The credential was refused. Sign in to MiniMax Code again on the plugin page.',
+        failureParameters: 'The upstream rejected the request parameters. Adjust the prompt or the options and try again.',
+        failureSubscription: 'The account holds no plan, so the call was refused. Check whether the M Plan subscription is active.',
+        failureQuota: "The allowance is spent. Wait for it to recover, or check the plan's limit windows.",
+        failureRateLimited: 'The upstream is throttling. Try again a little later.',
+        failureLocal: 'The request never left the plugin, so nothing was spent.',
+        failureUpstream: 'The upstream refused the request. Please report the original words below so it can be traced.',
+        failureCharged: 'This request may already have been charged for upstream; do not retry it at once.',
+        failureUpstreamDetail: 'Upstream words',
         planGeneric: 'M Plan subscription',
         planExpires: 'until {date}',
         generateTitle: 'Generate',
@@ -406,6 +446,97 @@
                     return null;
                 return h('div', { style: mutedStyle, 'data-minimax-plan-notice': true }, t('planNoSubscription'));
             }
+            /**
+             * The sentence that says what to do about a failed generation call.
+             *
+             * The kind is the server's verdict on what the failure *is*, and each
+             * kind has one remedy; the upstream's own words are kept beside it
+             * rather than in place of it, because the words are the evidence and
+             * the remedy is the help.
+             */
+            function generationRemedy(t, kind) {
+                switch (kind) {
+                    case 'credentials': return t('failureCredentials');
+                    case 'parameters': return t('failureParameters');
+                    case 'subscription': return t('failureSubscription');
+                    case 'quota': return t('failureQuota');
+                    case 'rate-limited': return t('failureRateLimited');
+                    case 'local': return t('failureLocal');
+                    default: return t('failureUpstream');
+                }
+            }
+            /**
+             * Turn a failed call into what the person is shown.
+             *
+             * Three things travel together: the remedy, whether the upstream had
+             * already accepted the work, and the upstream's own words. The last
+             * one is shown collapsed rather than inline — it can be long, and it is
+             * read when a report is being written, not when the failure happens.
+             */
+            function generationNote(t, failure) {
+                const upstream = failure.upstream?.message ?? failure.error;
+                return {
+                    text: generationRemedy(t, failure.kind),
+                    upstream,
+                    charged: failure.charged === true,
+                };
+            }
+            /**
+             * The diagnostics section: a read-only list of facts about this
+             * installation.
+             *
+             * Its purpose is to be copied. Every line is a fact, nothing here
+             * changes a setting, and the whole thing can be pasted into a report
+             * as it stands — which is the whole point, because the facts a report
+             * needs are exactly the ones nobody can be expected to remember.
+             */
+            function diagnosticsBlock(t, diagnostics) {
+                if (diagnostics === undefined)
+                    return null;
+                const lines = [];
+                const add = (label, value) => {
+                    if (value !== undefined && value.length > 0)
+                        lines.push(`${label}: ${value}`);
+                };
+                add(t('diagnosticsPluginVersion'), diagnostics.pluginVersion);
+                add(t('diagnosticsRegion'), diagnostics.region);
+                add(t('diagnosticsHosts'), diagnostics.hosts?.join('  '));
+                add(t('diagnosticsAuthSource'), diagnostics.authSource);
+                add(t('diagnosticsCatalogSource'), diagnostics.catalogSource);
+                add(t('diagnosticsCapability'), diagnostics.capability === undefined
+                    ? undefined
+                    : Object.entries(diagnostics.capability).map(([key, value]) => `${key}=${value}`).join('  '));
+                add(t('diagnosticsLastError'), diagnostics.lastUpstreamError);
+                if (lines.length === 0)
+                    return null;
+                return h('div', { style: boxStyle, 'data-minimax-diagnostics': true }, h('div', { style: boxTitleStyle }, t('diagnosticsTitle')), h('pre', { style: upstreamTextStyle, 'data-minimax-diagnostics-text': true }, lines.join('\n')), h('div', { style: mutedStyle }, t('diagnosticsHint')));
+            }
+            /**
+             * A note the card shows.
+             *
+             * Most notes are one sentence — the delivery refusals name what is
+             * missing — while a failed call carries its evidence with it. Both are
+             * drawn by the same helper, so the two kinds sit in one place.
+             */
+            function noteBlock(t, note) {
+                if (typeof note === 'string')
+                    return h('span', { style: mutedStyle }, note);
+                return generationNoteBlock(t, note);
+            }
+            /**
+             * The note as it is drawn: the remedy, then the upstream's words.
+             *
+             * The charged case says so in its own line: a person who was told
+             * only "try again" would spend again, and the upstream may already
+             * have taken the first one.
+             */
+            function generationNoteBlock(t, note) {
+                return h('div', { style: mutedStyle, 'data-minimax-generation-note': true }, h('div', null, note.text), note.charged === true
+                    ? h('div', { style: warnStyle, 'data-minimax-generation-charged': true }, t('failureCharged'))
+                    : null, note.upstream === undefined
+                    ? null
+                    : h('details', { style: mutedStyle, 'data-minimax-generation-upstream': true }, h('summary', null, t('failureUpstreamDetail')), h('pre', { style: upstreamTextStyle }, note.upstream)));
+            }
             /**
              * What the page card's plan box says when it has no windows to show.
              *
@@ -546,6 +677,10 @@
                 const provider = (projection?.next ?? projection?.lastUsed)?.provider;
                 if (provider !== undefined && provider !== MINIMAX_PROVIDER_ID)
                     return null;
+                // The balance may be hidden: a display choice, applied at once.
+                const [status] = useStatus();
+                if (status?.showPill === false)
+                    return null;
                 return h(CreditPill, props);
             }
             /**
@@ -610,7 +745,7 @@
                 }, []);
                 const [prompt, setPrompt] = React.useState('');
                 const [busy, setBusy] = React.useState(false);
-                const [note, setNote] = React.useState('');
+                const [note, setNote] = React.useState(undefined);
                 /**
                  * The session's own send path.
                  *
@@ -686,7 +821,7 @@
                     if (text === '')
                         return;
                     setBusy(true);
-                    setNote('');
+                    setNote(undefined);
                     try {
                         const response = await fetch(GENERATE_PATH, {
                             method: 'POST',
@@ -695,7 +830,7 @@
                         });
                         const body = await response.json();
                         if (body.ok !== true || body.dataUrl === undefined) {
-                            setNote(body.error ?? t('generateFailed'));
+                            setNote(generationNote(t, body));
                             return;
                         }
                         const part = imagePart(body.dataUrl, body.mediaType ?? 'image/jpeg');
@@ -737,7 +872,7 @@
                             setOpen(false);
                             // The picture's own arrival is the feedback: it is in the
                             // conversation now, so the composer needs no banner.
-                            setNote('');
+                            setNote(undefined);
                             return;
                         }
                         const drafts = draftFace();
@@ -760,7 +895,7 @@
                             addAttachments(created.map(draft => draft.id));
                             setPrompt('');
                             setOpen(false);
-                            setNote('');
+                            setNote(undefined);
                             return;
                         }
                         setNote(t('generateSendFailed'));
@@ -777,7 +912,7 @@
                         type: 'button',
                         style: buttonStyle,
                         title: t('generateToChatHint'),
-                        onClick: () => { setOpen(true); setNote(''); },
+                        onClick: () => { setOpen(true); setNote(undefined); },
                     }, t('generateToChat'));
                 }
                 return h('div', { style: dockStyle, 'data-minimax-generate-dock': true }, h('input', {
@@ -795,8 +930,8 @@
                     type: 'button',
                     style: buttonStyle,
                     disabled: busy,
-                    onClick: () => { setOpen(false); setPrompt(''); setNote(''); },
-                }, '✕'), note === '' ? null : h('span', { style: mutedStyle }, note));
+                    onClick: () => { setOpen(false); setPrompt(''); setNote(undefined); },
+                }, '✕'), note === undefined ? null : noteBlock(t, note));
             }
             /** Ask the host to do something, and let the card read the result. */
             async function act(action, body) {
@@ -914,14 +1049,14 @@
                 const [resolution, setResolution] = React.useState('2K');
                 const [ratio, setRatio] = React.useState('16:9');
                 const [busy, setBusy] = React.useState(false);
-                const [note, setNote] = React.useState('');
+                const [note, setNote] = React.useState(undefined);
                 const [picture, setPicture] = React.useState(undefined);
                 const [video, setVideo] = React.useState(undefined);
                 const imageModels = options?.imageModels ?? ['MiniMax-H3-Image'];
                 /** Ask for a picture; the answer carries the bytes inline. */
                 async function makeImage() {
                     setBusy(true);
-                    setNote('');
+                    setNote(undefined);
                     setVideo(undefined);
                     try {
                         const response = await fetch(GENERATE_PATH, {
@@ -937,7 +1072,7 @@
                         });
                         const body = await response.json();
                         if (body.ok !== true || body.dataUrl === undefined) {
-                            setNote(body.error ?? t('generateFailed'));
+                            setNote(generationNote(t, body));
                             return;
                         }
                         setPicture({ dataUrl: body.dataUrl, size: body.size, saved: body.attachment !== undefined });
@@ -952,7 +1087,7 @@
                 /** Start a video task, then wait for it the way the upstream does. */
                 async function makeVideo() {
                     setBusy(true);
-                    setNote('');
+                    setNote(undefined);
                     setPicture(undefined);
                     try {
                         const response = await fetch(GENERATE_PATH, {
@@ -968,7 +1103,7 @@
                         });
                         const body = await response.json();
                         if (body.ok !== true || body.taskId === undefined) {
-                            setNote(body.error ?? t('generateFailed'));
+                            setNote(generationNote(t, body));
                             return;
                         }
                         // The task takes a minute and a half; the upstream is asked every
@@ -979,11 +1114,11 @@
                             const task = await polled.json();
                             if (task.url !== undefined) {
                                 setVideo({ url: task.url, status: task.status });
-                                setNote('');
+                                setNote(undefined);
                                 return;
                             }
                             if (task.status !== undefined && /fail|cancel/i.test(task.status)) {
-                                setNote(task.error ?? t('generateFailed'));
+                                setNote(generationNote(t, task));
                                 return;
                             }
                         }
@@ -1022,7 +1157,7 @@
                     style: actionButtonStyle,
                     disabled: busy || prompt.trim() === '',
                     onClick: () => { void (mode === 'image' ? makeImage() : makeVideo()); },
-                }, busy ? (mode === 'video' ? t('generateVideoRunning') : t('generateRunning')) : t('generateRun'))), note === '' ? null : h('div', { style: mutedStyle }, note), picture === undefined
+                }, busy ? (mode === 'video' ? t('generateVideoRunning') : t('generateRunning')) : t('generateRun'))), note === undefined ? null : noteBlock(t, note), picture === undefined
                     ? null
                     : h('div', { style: generationResultStyle, 'data-minimax-generation-image': true }, h('img', { src: picture.dataUrl, alt: prompt, style: generatedImageStyle }), h('div', { style: rowStyle }, h('span', null, picture.size === undefined ? t('generateImageDone') : `${t('generateImageDone')} · ${picture.size}`), picture.saved === true ? h('span', null, t('generateSaved')) : null, h('a', { href: picture.dataUrl, download: 'minimax-h3-image.jpg', style: linkStyle }, t('generateDownload')))), video === undefined
                     ? null
@@ -1092,7 +1227,20 @@
                     ? h('div', { style: { ...boxStyle, ...span2Style }, 'data-minimax-usage-profile': true }, h('div', { style: boxTitleStyle }, t('accountUsage')), h('div', { style: profileGridStyle }, ...profileLines.map((line, index) => h('div', { key: `profile-${index}` }, line))))
                     : null, login !== undefined && login.state !== 'signed-in'
                     ? h('div', { style: span2Style }, loginBlock(t, login, refresh))
-                    : null)), 
+                    : null, 
+                // The read-only facts, last in the card: a report is made from
+                // them, and they are of no use to the person using the plugin.
+                diagnosticsBlock(t, status?.diagnostics), 
+                // A display choice: it takes effect at once, with no draft to
+                // save. The other things on this page are facts to read; this
+                // is the one control, and it changes only what is drawn.
+                h('div', { style: { ...boxStyle, ...span2Style }, 'data-minimax-pill-toggle': true }, h('div', { style: boxTitleStyle }, t('displayTitle')), h('label', { style: { display: 'inline-flex', alignItems: 'center', gap: '6px', fontSize: '12px' } }, h('input', {
+                    type: 'checkbox',
+                    checked: status?.showPill !== false,
+                    onChange: (event) => {
+                        void act('pillVisible', { showPill: event.target.checked });
+                    },
+                }), h('span', null, t('showPill')))))), 
                 // The generation panel does not need the balance: it spends the
                 // account's generation allowance, not its credits, so it stays
                 // usable even when the balance cannot be read.
@@ -1232,6 +1380,20 @@
             };
             const planExpiryStyle = { fontSize: '13px', fontWeight: 400, lineHeight: '1.6' };
             const mutedStyle = { opacity: 0.7, fontSize: '12px' };
+            /**
+             * The upstream's own words, as they arrive.
+             *
+             * Kept monospaced and wrapped, because it is quoted evidence: a report
+             * should carry it exactly as the upstream wrote it.
+             */
+            const upstreamTextStyle = {
+                margin: '4px 0 0',
+                whiteSpace: 'pre-wrap',
+                wordBreak: 'break-word',
+                fontFamily: 'var(--dsh-mono, ui-monospace, monospace)',
+                fontSize: '11px',
+                opacity: 0.9,
+            };
             const actionButtonStyle = {
                 appearance: 'none',
                 background: 'transparent',

package/lib/index.d.ts

@@ -719,6 +719,15 @@ interface PluginState {
   schemaVersion: number;
   /** Whether the plugin claims the daily grant on its own. */
   autoCheckin: boolean;
+  /**
+   * Whether the balance shows in the composer.
+   *
+   * A display choice rather than a setting about the account: it changes
+   * nothing upstream and nothing about what the plugin does, only whether
+   * the balance is drawn beside the composer. It therefore takes effect at
+   * once, with no draft to save — see the note on the settings below.
+   */
+  showPill?: boolean;
   /** The day the last claim happened, in the account's time zone. */
   lastClaimDay?: string;
   /** When the last claim happened, in milliseconds since the epoch. */
@@ -1026,6 +1035,29 @@ interface UsageStatus {
   /** How many requests were measured. */
   requests: number;
 }
+/**
+ * The facts a report needs, gathered in one place.
+ *
+ * The point of this section is that it can be copied as a whole into a
+ * report: every line is a fact about this installation, and nothing here
+ * changes any setting — there is no control on it, by design.
+ */
+interface DiagnosticsStatus {
+  /** This plugin's own version. */
+  pluginVersion?: string;
+  /** The region this plugin talks to. */
+  region?: string;
+  /** The upstream hosts this plugin uses. */
+  hosts?: string[];
+  /** How the plugin is signed in. */
+  authSource?: string;
+  /** Where the model catalog came from. */
+  catalogSource?: string;
+  /** The most recent upstream failure, in its own words. */
+  lastUpstreamError?: string;
+  /** What the host offered the card, one entry per piece. */
+  capability?: Record<string, string>;
+}
 /** The plan the account subscribes to, as the card reads it. */
 interface PlanStatus {
   /** Whether the account holds a plan. */
@@ -1137,6 +1169,10 @@ interface StatusDocument {
   usageProfile?: UsageProfileStatus;
   /** The plan the account subscribes to, when there is one. */
   plan?: PlanStatus;
+  /** The facts a report needs, gathered in one place. */
+  diagnostics?: DiagnosticsStatus;
+  /** Whether the balance is drawn beside the composer. */
+  showPill?: boolean;
   /** The choices the generation endpoints offer. */
   generation?: GenerationOptions;
   /** What the host offered the card the last time it looked. */
@@ -1178,6 +1214,10 @@ interface StatusDeps {
   usageProfile?: UsageProfileStatus;
   /** The plan the account subscribes to, when there is one. */
   plan?: PlanStatus;
+  /** The facts a report needs, gathered in one place. */
+  diagnostics?: DiagnosticsStatus;
+  /** Whether the balance is drawn beside the composer. */
+  showPill?: boolean;
   /** The choices the generation endpoints offer. */
   generation?: GenerationOptions;
   /** What the host offered the card the last time it looked. */

package/lib/index.js

@@ -1,4 +1,5 @@
 import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -733,6 +734,68 @@ function imageInputHooks(ctx) {
 	};
 }
 //#endregion
+//#region src/failure.ts
+/**
+* Match a shape of the upstream's message.
+*
+* The patterns name *facts* rather than identifiers: "no active subscription"
+* is a fact about the account, "2062" is a number another system chose.
+*/
+const SHAPES = [
+	{
+		kind: "subscription",
+		pattern: /no active (token plan|subscription)|not subscribed|no subscription/i
+	},
+	{
+		kind: "credentials",
+		pattern: /login fail|log ?in fail|unauthorized|invalid api[ _-]?key|api secret key|invalid credential|authentication (failed|error)/i
+	},
+	{
+		kind: "quota",
+		pattern: /insufficient|quota (exceed|exhaust)|balance (is )?(not enough|insufficient)|not enough (credit|balance)|credit (exceed|exhaust)|超出|余额不足/i
+	},
+	{
+		kind: "rate-limited",
+		pattern: /rate ?limit|too many requests|请求过于频繁|频率限制/i
+	},
+	{
+		kind: "parameters",
+		pattern: /invalid (parameter|argument|request|value)|parameter .* (invalid|must be|not allowed)|unsupported (parameter|value|model)|must be (a |an )?(string|number|array|object|boolean)|参数(错误|无效)|不合法/i
+	}
+];
+/**
+* Classify a failure by what the upstream said and how it said it.
+*
+* @param message - The upstream's message, or a description of what went
+*   wrong locally.
+* @param status - The HTTP status the answer arrived with, when there was one.
+* @returns The kind of failure. A failure this plugin does not recognise is
+*   `upstream` rather than a guess: the remedy for an unknown failure is to
+*   show the upstream's words, not to pretend to know better.
+*/
+function classifyFailure(message, status) {
+	if (status === 401 || status === 403) return "credentials";
+	if (status === 429) return "rate-limited";
+	for (const shape of SHAPES) if (shape.pattern.test(message)) return shape.kind;
+	if (status === 400 || status === 422) return "parameters";
+	return "upstream";
+}
+/**
+* How long to hold off before trying the same thing again.
+*
+* A failure that spent nothing has nothing to cool down: the caller fixed
+* something and may try again at once. A failure that happened after the
+* upstream accepted the work may already have been charged for, so a retry
+* right away is another charge — that one waits.
+*
+* @returns The wait in milliseconds, or zero when no wait is warranted.
+*/
+function cooldownFor(failure) {
+	return failure.charged ? COOLDOWN_MS : 0;
+}
+/** The wait after a failure that may already have been charged for. */
+const COOLDOWN_MS = 3e4;
+//#endregion
 //#region src/status-route.ts
 /** Route this plugin mounts, matching its settings card. */
 const MINIMAX_STATUS_PATH = "/plugins/dsh-connect-minimaxcode/status";
@@ -787,6 +850,8 @@ function statusDocument(deps) {
 		...deps.login === void 0 ? {} : { login: deps.login },
 		...deps.usageProfile === void 0 ? {} : { usageProfile: deps.usageProfile },
 		...deps.plan === void 0 ? {} : { plan: deps.plan },
+		...deps.diagnostics === void 0 ? {} : { diagnostics: deps.diagnostics },
+		...deps.showPill === void 0 ? {} : { showPill: deps.showPill },
 		...deps.capability === void 0 ? {} : { capability: deps.capability },
 		...deps.generation === void 0 ? {} : { generation: deps.generation }
 	};
@@ -888,10 +953,27 @@ const VIDEO_DURATIONS = [
 var GenerationError = class extends Error {
 	/** The upstream's own status code, when it gave one. */
 	code;
-	constructor(message, code) {
+	/**
+	* What kind of failure this is, and what it cost.
+	*
+	* The verdict is what a caller acts on: it says whether the remedy is to
+	* change something, to sign in again, or to wait, and whether the work may
+	* already have been charged for.
+	*/
+	verdict;
+	constructor(message, code, verdict) {
 		super(message);
 		this.name = "GenerationError";
 		this.code = code;
+		this.verdict = {
+			kind: verdict?.kind ?? classifyFailure(message, code),
+			charged: verdict?.charged ?? false,
+			upstream: verdict?.upstream ?? (code === void 0 ? void 0 : {
+				status: code,
+				code,
+				message
+			})
+		};
 	}
 };
 /**
@@ -981,12 +1063,38 @@ async function callGeneration(apiKey, url, body, fetchImpl) {
 	try {
 		document = JSON.parse(text);
 	} catch {
-		if (!response.ok) throw new GenerationError(`generation request failed: HTTP ${response.status}`, response.status);
-		throw new GenerationError("generation response was not JSON");
+		if (!response.ok) throw new GenerationError(`generation request failed: HTTP ${response.status}`, response.status, {
+			charged: false,
+			upstream: {
+				status: response.status,
+				message: `generation request failed: HTTP ${response.status}`
+			}
+		});
+		throw new GenerationError("generation response was not JSON", void 0, { charged: false });
+	}
+	if (!response.ok) {
+		const message = readErrorMessage(document) ?? `generation request failed: HTTP ${response.status}`;
+		const code = readErrorCode(document);
+		throw new GenerationError(message, code ?? response.status, {
+			kind: classifyFailure(message, response.status),
+			charged: false,
+			upstream: {
+				status: response.status,
+				code,
+				message
+			}
+		});
 	}
-	if (!response.ok) throw new GenerationError(readErrorMessage(document) ?? `generation request failed: HTTP ${response.status}`, readErrorCode(document) ?? response.status);
 	const refusal = readBodyRefusal(document);
-	if (refusal !== void 0) throw new GenerationError(refusal.message, refusal.code);
+	if (refusal !== void 0) throw new GenerationError(refusal.message, refusal.code, {
+		kind: classifyFailure(refusal.message, response.status),
+		charged: false,
+		upstream: {
+			status: response.status,
+			code: refusal.code,
+			message: refusal.message
+		}
+	});
 	return document ?? {};
 }
 /**
@@ -1092,11 +1200,37 @@ async function queryVideoTask(options) {
 	try {
 		document = JSON.parse(text) ?? {};
 	} catch {
-		throw new GenerationError(`video task query failed: HTTP ${response.status}`, response.status);
+		throw new GenerationError(`video task query failed: HTTP ${response.status}`, response.status, {
+			charged: true,
+			upstream: {
+				status: response.status,
+				message: `video task query failed: HTTP ${response.status}`
+			}
+		});
+	}
+	if (!response.ok) {
+		const message = readErrorMessage(document) ?? `video task query failed: HTTP ${response.status}`;
+		const code = readErrorCode(document);
+		throw new GenerationError(message, code ?? response.status, {
+			kind: classifyFailure(message, response.status),
+			charged: true,
+			upstream: {
+				status: response.status,
+				code,
+				message
+			}
+		});
 	}
-	if (!response.ok) throw new GenerationError(readErrorMessage(document) ?? `video task query failed: HTTP ${response.status}`, readErrorCode(document) ?? response.status);
 	const refusal = readBodyRefusal(document);
-	if (refusal !== void 0) throw new GenerationError(refusal.message, refusal.code);
+	if (refusal !== void 0) throw new GenerationError(refusal.message, refusal.code, {
+		kind: classifyFailure(refusal.message, response.status),
+		charged: true,
+		upstream: {
+			status: response.status,
+			code: refusal.code,
+			message: refusal.message
+		}
+	});
 	const task = document.task ?? document;
 	const content = task.content;
 	const usage = task.usage;
@@ -2642,6 +2776,16 @@ var UsageMeter = class {
 };
 //#endregion
 //#region src/index.ts
+/**
+* MiniMax Code models for DeepSeek Harness.
+*
+* Registers one provider, `minimaxcode`, that serves the models the signed-in
+* MiniMax Code desktop app has access to. Streaming, tool calls, and
+* permissions stay Harness-owned; this plugin only supplies the route and the
+* catalog.
+*
+* @module dsh-connect-minimaxcode
+*/
 /** Loader entry name; also the id the bundle patch inserts. */
 /**
 * Whether a message says the server refused the credential itself.
@@ -2727,6 +2871,13 @@ function apply(ctx) {
 	/** What the card last reported about what the host offered it. */
 	let capability;
 	/**
+	* The most recent upstream failure, in its own words.
+	*
+	* It is kept verbatim and unedited: a report that carries it does not
+	* depend on the reader describing it correctly.
+	*/
+	let lastUpstreamError;
+	/**
 	* Give up on the plugin's own credential after the server refused it.
 	*
 	* A revoked token keeps its expiry date, so every later call would send the
@@ -3024,6 +3175,54 @@ function apply(ctx) {
 		};
 	};
 	/**
+	* This plugin's own version, read from the package it was installed as.
+	*
+	* It is read at runtime rather than written into the bundle, so the number
+	* in a report is the number of the package that is actually installed — a
+	* number baked in at build time would drift from it on the first release
+	* that forgot to rebuild.
+	*
+	* A package root that cannot be read leaves the field out rather than
+	* guessing: a wrong version in a report is worse than no version.
+	*/
+	function readPluginVersion() {
+		try {
+			const manifest = JSON.parse(readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+			return typeof manifest.version === "string" ? manifest.version : void 0;
+		} catch {
+			return;
+		}
+	}
+	/** This plugin's own version, read once when it loads. */
+	const PLUGIN_VERSION = readPluginVersion();
+	/**
+	* The facts a report needs, gathered in one place.
+	*
+	* Every line is a fact about this installation and nothing here changes
+	* anything: the section exists so that a person can copy it into a report
+	* without having to work out what to include.
+	*
+	* The host's own version is not in here, because the host does not offer
+	* it to a plugin — a line that had to be guessed would be worse than no
+	* line at all.
+	*/
+	const buildDiagnostics = async () => {
+		const auth = await buildAuthStatus();
+		return {
+			pluginVersion: PLUGIN_VERSION,
+			region,
+			hosts: [.../* @__PURE__ */ new Set([
+				MINIMAX_GATEWAYS[region],
+				MINIMAX_ACCOUNT_HOSTS[region],
+				MINIMAX_API_HOSTS[region]
+			])],
+			authSource: auth.state === "signed-in" ? buildLoginStatus().source : auth.state,
+			catalogSource: catalog.source,
+			lastUpstreamError,
+			...capability === void 0 ? {} : { capability: capability.findings }
+		};
+	};
+	/**
 	* The plan the account holds, as the card reads it.
 	*
 	* It comes from the same membership answer as the balance, so it is free.
@@ -3188,6 +3387,8 @@ function apply(ctx) {
 			usageProfile: buildUsageProfileStatus(),
 			plan: buildPlanStatus(),
 			capability,
+			diagnostics: await buildDiagnostics(),
+			showPill: pluginState.showPill ?? true,
 			generation: {
 				imageModels: [...IMAGE_MODELS],
 				imageAspectRatios: [...IMAGE_ASPECT_RATIOS],
@@ -3299,6 +3500,22 @@ function apply(ctx) {
 					state: result.state
 				};
 			}
+			case "pillVisible": {
+				const showPill = body.showPill;
+				if (typeof showPill !== "boolean") return {
+					ok: false,
+					error: "showPill 必须是布尔值"
+				};
+				pluginState = {
+					...pluginState,
+					showPill
+				};
+				await writePluginState(pluginState);
+				return {
+					ok: true,
+					showPill
+				};
+			}
 			case "settings": {
 				const autoCheckin = body.autoCheckin;
 				if (typeof autoCheckin !== "boolean") return {
@@ -3334,9 +3551,15 @@ function apply(ctx) {
 	const resolvePlanApiKey = async () => {
 		if (planApiKey !== void 0) return planApiKey;
 		const account = await resolveAccountCredential();
-		if (account.state !== "signed-in") throw new GenerationError("尚未登录 MiniMax Code");
+		if (account.state !== "signed-in") throw new GenerationError("尚未登录 MiniMax Code", void 0, {
+			kind: "credentials",
+			charged: false
+		});
 		const key = await fetchPlanApiKey(account.credential, region);
-		if (key === void 0) throw new GenerationError("账户没有开放平台密钥，无法调用生成接口");
+		if (key === void 0) throw new GenerationError("账户没有开放平台密钥，无法调用生成接口", void 0, {
+			kind: "credentials",
+			charged: false
+		});
 		planApiKey = key;
 		return key;
 	};
@@ -3383,7 +3606,10 @@ function apply(ctx) {
 		const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
 		if (prompt.length === 0) return {
 			ok: false,
-			error: "请填写提示词"
+			error: "请填写提示词",
+			kind: "local",
+			charged: false,
+			cooldownMs: 0
 		};
 		const apiKey = await resolvePlanApiKey();
 		if (kind === "video") return {
@@ -3575,11 +3801,19 @@ function apply(ctx) {
 					res.end(JSON.stringify(await runGeneration(body)));
 				} catch (error) {
 					const status = error instanceof GenerationError ? 400 : 500;
+					if (error instanceof GenerationError) lastUpstreamError = error.verdict.upstream?.message ?? error.message;
 					res.writeHead(status, { "Content-Type": "application/json" });
+					const verdict = error instanceof GenerationError ? error.verdict : void 0;
 					res.end(JSON.stringify({
 						ok: false,
 						error: error instanceof Error ? error.message : String(error),
-						...error instanceof GenerationError && error.code !== void 0 ? { code: error.code } : {}
+						...error instanceof GenerationError && error.code !== void 0 ? { code: error.code } : {},
+						...verdict === void 0 ? {} : {
+							kind: verdict.kind,
+							charged: verdict.charged,
+							cooldownMs: cooldownFor(verdict)
+						},
+						...verdict?.upstream === void 0 ? {} : { upstream: verdict.upstream }
 					}));
 				}
 			}

package/package.json

@@ -2,7 +2,7 @@
   "name": "dsh-connect-minimaxcode",
   "displayName": "DSH Connect MiniMax Code",
   "description": "把本机已登录的 MiniMax Code 桌面 App 模型接入 DeepSeek Harness：零配置、Anthropic Messages 兼容、动态模型目录，并显示积分余额与到期 — bring MiniMax Code desktop app models into DSH with a dynamic model catalog and a credit balance with expiry details.",
-  "version": "0.6.9",
+  "version": "0.7.0",
   "author": "JeffTsuiCUG",
   "contributors": [
     {
@@ -58,6 +58,7 @@
   "files": [
     "lib",
     "locale",
+    "docs",
     "icon.svg",
     "cordis.patch.yml",
     "README.md",